react-native-platform-components 0.8.9 → 0.9.0

package/README.md

@@ -371,18 +371,22 @@ export function Example() {
 
 ```tsx
 import { SegmentedControl } from 'react-native-platform-components';
-import { Platform } from 'react-native';
 
 const segments = [
   {
     label: 'List',
     value: 'list',
-    icon: Platform.OS === 'ios' ? 'list.bullet' : 'list_bullet',
+    // Native symbol on each platform, no Platform.OS branching
+    icon: {
+      ios: { type: 'sfSymbol', name: 'list.bullet' },
+      android: { type: 'drawable', name: 'list_bullet' },
+    },
   },
   {
-    label: 'Grid',
-    value: 'grid',
-    icon: Platform.OS === 'ios' ? 'square.grid.2x2' : 'grid_view',
+    label: 'Alerts',
+    value: 'alerts',
+    // One image asset shared by both platforms, tinted like a template
+    icon: { type: 'image', source: require('./bell.png') },
   },
 ];
 
@@ -394,6 +398,8 @@ export function Example() {
       segments={segments}
       selectedValue={selected}
       onSelect={(value) => setSelected(value)}
+      // 'auto' | 'labeled' | 'unlabeled'
+      labelVisibility="auto"
       ios={{ apportionsSegmentWidthsByContent: true }}
     />
   );
@@ -611,42 +617,132 @@ Native segmented control using **UISegmentedControl** on iOS and **MaterialButto
 
 ### Props
 
-| Prop            | Type                                     | Description                          |
-| --------------- | ---------------------------------------- | ------------------------------------ |
-| `segments`      | `SegmentedControlSegment[]`              | Array of segments to display         |
-| `selectedValue` | `string \| null`                         | Currently selected segment's `value` |
-| `disabled`      | `boolean`                                | Disables the entire control          |
-| `onSelect`      | `(value: string, index: number) => void` | Called when user selects a segment   |
+| Prop              | Type                                     | Description                                                                                                                                                |
+| ----------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `segments`        | `SegmentedControlSegment[]`              | Array of segments to display                                                                                                                               |
+| `selectedValue`   | `string \| null`                         | Currently selected segment's `value`                                                                                                                       |
+| `disabled`        | `boolean`                                | Disables the entire control                                                                                                                                |
+| `labelVisibility` | `'auto' \| 'labeled' \| 'unlabeled'`     | How labels and icons combine. See [Label visibility](#label-visibility). Default: `'auto'`                                                                 |
+| `selectedSegmentColor` | `ColorValue`                        | Background of the selected segment                                                                                                                         |
+| `activeTintColor` | `ColorValue`                             | Text and icon color of the selected segment                                                                                                                |
+| `inactiveTintColor` | `ColorValue`                           | Text and icon color of unselected segments                                                                                                                 |
+| `labelStyle`      | `{ fontFamily?, fontSize?, fontWeight?, fontStyle? }` | Font for segment labels. See [Styling](#styling)                                                                                              |
+| `badgeStyle`      | `{ backgroundColor?, color? }`           | Colors for segment badges. See [Badges](#badges)                                                                                                            |
+| `onSelect`        | `(value: string, index: number) => void` | Called when user selects a segment                                                                                                                         |
+| `onDeselect`      | `() => void`                             | Called when the user clears the selection by tapping the selected segment. Android only; requires `android.selectionRequired: false`                        |
 
 ### SegmentedControlSegment
 
-| Property   | Type      | Description                                       |
-| ---------- | --------- | ------------------------------------------------- |
-| `label`    | `string`  | Display text for the segment                      |
-| `value`    | `string`  | Unique value returned in callbacks                |
-| `disabled` | `boolean` | Disables this specific segment                    |
-| `icon`     | `string`  | Icon name (SF Symbol on iOS, drawable on Android) |
+| Property             | Type                   | Description                                                                                                       |
+| -------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `label`              | `string`               | Display text for the segment                                                                                      |
+| `value`              | `string`               | Unique value returned in callbacks                                                                                |
+| `disabled`           | `boolean`              | Disables this specific segment                                                                                    |
+| `icon`               | `SegmentedControlIcon` | Optional icon. See [Icon Support](#icon-support-1)                                                                |
+| `badge`              | `string \| number`     | Badge at the segment's top-right corner, e.g. an unread count. See [Badges](#badges)                              |
+| `accessibilityLabel` | `string`               | Screen-reader label. Defaults to `label`. On iOS it applies to icon segments; text segments announce their title |
 
 ### iOS Props (`ios`)
 
-| Prop                               | Type      | Description                                         |
-| ---------------------------------- | --------- | --------------------------------------------------- |
-| `momentary`                        | `boolean` | If true, segments don't show selected state         |
-| `apportionsSegmentWidthsByContent` | `boolean` | If true, segment widths are proportional to content |
-| `selectedSegmentTintColor`         | `string`  | Tint color for selected segment (hex string)        |
+| Prop                               | Type      | Description                                                                 |
+| ---------------------------------- | --------- | --------------------------------------------------------------------------- |
+| `momentary`                        | `boolean` | If true, segments don't show selected state                                 |
+| `apportionsSegmentWidthsByContent` | `boolean` | If true, segment widths are proportional to content                         |
+| `selectedSegmentTintColor`         | `string`  | **Deprecated.** Use `selectedSegmentColor`, which works on both platforms. |
 
 ### Android Props (`android`)
 
-| Prop                | Type      | Description                                  |
-| ------------------- | --------- | -------------------------------------------- |
-| `selectionRequired` | `boolean` | If true, one segment must always be selected |
+| Prop                | Type         | Description                                                                                                                                  |
+| ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `selectionRequired` | `boolean`    | If true (default), one segment must always be selected. Set to `false` to let a tap on the selected segment clear it and fire `onDeselect`. |
+| `rippleColor`       | `ColorValue` | Ripple shown while pressing a segment                                                                                                        |
+| `strokeColor`       | `ColorValue` | Outline color of the segments                                                                                                                |
 
 ### Icon Support
 
-Icons work the same as ContextMenu:
+`icon` accepts a single source, or an `{ ios, android }` pair so you never branch on `Platform.OS`:
+
+| Shape                                       | iOS                                 | Android                                       |
+| ------------------------------------------- | ----------------------------------- | --------------------------------------------- |
+| `'name'` (string)                           | SF Symbol name                      | Drawable resource name                        |
+| `{ type: 'sfSymbol', name }`                | SF Symbol                           | Ignored (segment shows its label)             |
+| `{ type: 'drawable', name }`                | Ignored (segment shows its label)   | Drawable from `res/drawable`                  |
+| `{ type: 'image', source, tinted? }`        | Image asset or `{ uri }`            | Image asset or `{ uri }`                      |
+| `{ ios: <source>, android: <source> }`      | Uses `ios`                          | Uses `android`                                |
+
+```tsx
+// A bundled asset works everywhere and is tinted like a template.
+icon: { type: 'image', source: require('./icons/bell.png') }
+
+// Keep the original colors of a full-color image.
+icon: { type: 'image', source: require('./icons/logo.png'), tinted: false }
+
+// Remote images load asynchronously; pass `scale` for @2x/@3x artwork.
+icon: { type: 'image', source: { uri: 'https://example.com/icon@2x.png', scale: 2 } }
+```
+
+Image icons render at their point size, so ship `@2x` / `@3x` variants sized around 18–22 points. Local assets load synchronously in release builds; in development they stream from Metro and the segment shows its label until the image arrives.
+
+### Label visibility
+
+`UISegmentedControl` shows either a title or an image per segment, while Material buttons can show both. `labelVisibility` makes the outcome predictable:
+
+| Value                 | iOS                                        | Android                    |
+| --------------------- | ------------------------------------------ | -------------------------- |
+| `'auto'` (default)    | Icon when the segment has one, else label  | Icon and label             |
+| `'labeled'`           | Label only (icon is not shown)             | Icon and label             |
+| `'unlabeled'`         | Icon when the segment has one, else label  | Icon only, else label      |
+
+Screen readers announce the label (or `accessibilityLabel`) in every mode on both platforms.
+
+### Styling
+
+Colors take any React Native `ColorValue` (hex, `rgba()`, named colors, `PlatformColor`, `DynamicColorIOS`). Fonts follow the `Text` style conventions, and each field falls back to the platform default.
+
+```tsx
+<SegmentedControl
+  segments={segments}
+  selectedValue={selected}
+  onSelect={setSelected}
+  selectedSegmentColor="#FF6B35"
+  activeTintColor="white"
+  inactiveTintColor="#8E8E93"
+  labelStyle={{ fontWeight: '700', fontSize: 14 }}
+  android={{ rippleColor: 'rgba(255, 107, 53, 0.25)', strokeColor: '#FF6B35' }}
+/>
+```
+
+| Prop                   | iOS                                          | Android                                      |
+| ---------------------- | -------------------------------------------- | -------------------------------------------- |
+| `selectedSegmentColor` | `selectedSegmentTintColor` (the pill)        | Checked button background                    |
+| `activeTintColor`      | Selected title / template image color        | Checked button text and icon tint            |
+| `inactiveTintColor`    | Normal title / template image color          | Unchecked button text and icon tint          |
+| `labelStyle`           | Title font (default: 13pt system)            | Button typeface and size (default: theme)    |
+| `android.rippleColor`  | —                                            | Press ripple                                 |
+| `android.strokeColor`  | —                                            | Button outline                               |
+
+Images with `tinted: false` keep their own colors and ignore the tint props.
+
+### Badges
+
+Give a segment a `badge` to show a count or short status at its top-right corner. Numbers render as-is, so format them yourself (`'99+'`); `undefined` hides the badge.
+
+```tsx
+<SegmentedControl
+  segments={[
+    { label: 'Inbox', value: 'inbox', badge: unreadCount || undefined },
+    { label: 'Sent', value: 'sent' },
+    { label: 'Drafts', value: 'drafts', badge: 'new' },
+  ]}
+  selectedValue={mailbox}
+  onSelect={setMailbox}
+  badgeStyle={{ backgroundColor: '#5856D6', color: 'white' }}
+/>
+```
 
-- **iOS**: Use SF Symbol names (e.g., `'list.bullet'`, `'square.grid.2x2'`)
-- **Android**: Use drawable resource names (e.g., `'list_bullet'`, `'grid_view'`)
+- **iOS**: a capsule label drawn over the segment (UISegmentedControl has no badge API). Defaults to system red with white text.
+- **Android**: a Material `BadgeDrawable` attached to the button. Defaults to the theme's error color.
+- Screen readers announce the badge with the segment label ("Inbox, 3").
 
 ---
 
@@ -746,7 +842,7 @@ All color props in this library support the same formats as React Native's `back
 **Props that accept colors:**
 
 - `ContextMenu`: `imageColor` (icon tint)
-- `SegmentedControl`: `ios.selectedSegmentTintColor`
+- `SegmentedControl`: `selectedSegmentColor`, `activeTintColor`, `inactiveTintColor`, `badgeStyle.backgroundColor`, `badgeStyle.color`, `android.rippleColor`, `android.strokeColor` (these also accept `PlatformColor` / `DynamicColorIOS`)
 - `LiquidGlass`: `ios.tintColor`, `android.fallbackBackgroundColor`
 
 ```tsx
@@ -897,7 +993,7 @@ Then run `npx expo prebuild` to apply the configuration.
 
 ## Icons
 
-ContextMenu supports icons on menu items. Icons are specified by name and resolved differently on each platform.
+ContextMenu supports icons on menu items. Icons are specified by name and resolved differently on each platform. SegmentedControl accepts the same names, plus image assets and per-platform pairs; see [SegmentedControl Icon Support](#icon-support-1).
 
 ### iOS
 

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

@@ -0,0 +1,88 @@
+package com.platformcomponents
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import android.util.Base64
+import android.util.DisplayMetrics
+import android.util.Log
+import android.util.LruCache
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.concurrent.Executors
+import kotlin.math.roundToInt
+
+/**
+ * Loads images referenced by React Native asset URIs for native controls that
+ * take a Drawable (segmented control icons).
+ *
+ * Release builds ship local assets as drawable resources, which callers resolve
+ * directly. Debug builds (Metro), `file://`, `content://`, `data:` and remote
+ * sources go through here on a background thread and are cached in memory.
+ */
+object PCImageLoader {
+  private const val TAG = "PCImageLoader"
+  private const val TIMEOUT_MS = 10_000
+
+  private val executor = Executors.newFixedThreadPool(2)
+  private val mainHandler = Handler(Looper.getMainLooper())
+  private val cache = LruCache<String, Bitmap>(32)
+
+  /**
+   * Loads [uri] and delivers the bitmap on the main thread. [scale] is the
+   * asset scale React Native resolved (2 for an `@2x` file), used to set the
+   * bitmap density so the drawable measures in dp like an `Image` would.
+   *
+   * Cached images are delivered synchronously.
+   */
+  fun load(context: Context, uri: String, scale: Float, callback: (Bitmap?) -> Unit) {
+    val key = "$uri@${scale}x"
+    cache.get(key)?.let {
+      callback(it)
+      return
+    }
+
+    val appContext = context.applicationContext
+    executor.execute {
+      val bitmap = try {
+        decode(appContext, uri)
+      } catch (e: Exception) {
+        Log.w(TAG, "Failed to load $uri: ${e.message}")
+        null
+      }
+      if (bitmap != null) {
+        bitmap.density = (scale.coerceAtLeast(0.01f) * DisplayMetrics.DENSITY_DEFAULT).roundToInt()
+        cache.put(key, bitmap)
+      }
+      mainHandler.post { callback(bitmap) }
+    }
+  }
+
+  private fun decode(context: Context, uri: String): Bitmap? {
+    val parsed = Uri.parse(uri)
+    return when (parsed.scheme?.lowercase()) {
+      "http", "https" -> {
+        val connection = URL(uri).openConnection() as HttpURLConnection
+        connection.connectTimeout = TIMEOUT_MS
+        connection.readTimeout = TIMEOUT_MS
+        try {
+          connection.inputStream.use { BitmapFactory.decodeStream(it) }
+        } finally {
+          connection.disconnect()
+        }
+      }
+      "file" -> parsed.path?.let { BitmapFactory.decodeFile(it) }
+      "content" -> context.contentResolver.openInputStream(parsed)?.use { BitmapFactory.decodeStream(it) }
+      "data" -> {
+        val comma = uri.indexOf(',')
+        if (comma < 0) return null
+        val bytes = Base64.decode(uri.substring(comma + 1), Base64.DEFAULT)
+        BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
+      }
+      else -> null
+    }
+  }
+}