feat(ios): add support for modern button configuration

apidoc/Titanium/UI/Button.yml

@@ -56,16 +56,6 @@ description: |
 
     #### iOS Platform Notes
 
-    iOS buttons have two special properties, `style` and `systemButton`.
-
-    The `style` property specifies the type of button decoration, and can be set to one
-    of the values described in <Titanium.UI.iOS.SystemButtonStyle>.
-
-    To use a custom button style, such as a background gradient, you may need to explicitly set
-    the button's `style` property to `PLAIN`, to prevent the button style from overriding any background color or gradient.
-
-    Also note:
-
     * When assigning a custom image to the `backgroundImage` property, the image must be
     partially or wholly transparent for the background color or background gradient to be visible.
     * Similarly, for an assigned background gradient to show through, the `backgroundColor` may need to be
@@ -114,7 +104,7 @@ description: |
     iOS supplies a built-in effect for pressed buttons. For most iOS buttons, the effect
     dims the entire button (except for the text) while the button is being pressed.
 
-    For toolbar buttons that use the [PLAIN](Titanium.UI.iOS.SystemButtonStyle.PLAIN) style
+    For toolbar buttons that use the [PLAIN](Titanium.UI.BUTTON_STYLE_OPTION_NEUTRAL) style
     or use system icons such as [CAMERA](Titanium.UI.iOS.SystemButton.CAMERA), a glow effect is
     used. The glow effect shows as a white circular glow or highlight at the center of the button
     when the button is pressed.
@@ -231,6 +221,20 @@ properties:
     since: "3.2.0"
     platforms: [iphone, ipad, macos]
 
+  - name: configuration
+    summary: Button configuration for modern button styling.
+    description: |
+        A <Titanium.UI.iOS.ButtonConfiguration> object that defines the appearance and behavior 
+        of the button. This provides a modern way to configure buttons with support for titles, 
+        subtitles, images, and various styling options.
+
+        When using a button configuration, it takes precedence over individual styling properties
+        like `title`, `color`, and `backgroundColor`.
+    type: Titanium.UI.iOS.ButtonConfiguration
+    since: "13.0.0"
+    platforms: [iphone, ipad, macos]
+    osver: {ios: {min: "15.0"}}
+
   - name: enabled
     summary: Set to `true` to enable the button, `false` to disable the button.
     type: Boolean
@@ -294,9 +298,6 @@ properties:
     summary: The border and fill style the button will use.
     description: |
         On Android, this is a creation-only property and cannot be changed dynamically.
-
-        For Titanium versions older than 10.0.0, this is an iOS only property and must be assigned
-        a constant from <Titanium.UI.iOS.SystemButtonStyle> which is now deprecated.
     type: Number
     constants: Titanium.UI.BUTTON_STYLE_*
     platforms: [android, iphone, ipad, macos]

apidoc/Titanium/UI/DashboardView.yml

@@ -161,7 +161,7 @@ examples:
 
         var button = Ti.UI.createButton({
             title: 'Edit',
-            style: Ti.UI.iOS.SystemButtonStyle.DONE,
+            style: Ti.UI.BUTTON_STYLE_OPTION_POSITIVE,
         });
 
         var toolbar = Ti.UI.iOS.createToolbar({
@@ -223,13 +223,13 @@ examples:
 
         dashboard.addEventListener('edit', function(e) {
           button.title = 'Done';
-          button.style = Ti.UI.iOS.SystemButtonStyle.DONE;
+          button.style = Ti.UI.BUTTON_STYLE_OPTION_POSITIVE;
           isEditable = true;
         });
 
         dashboard.addEventListener('commit', function(e) {
           button.title = 'Edit';
-          button.style = Ti.UI.iOS.SystemButtonStyle.PLAIN;
+          button.style = Ti.UI.BUTTON_STYLE_OPTION_NEUTRAL;
           isEditable = false;
         });
 
@@ -290,13 +290,13 @@ examples:
 
         function handleEdit(e) {
           $.button.title = 'Done';
-          $.button.style = Ti.UI.iOS.SystemButtonStyle.DONE;
+          $.button.style = Ti.UI.BUTTON_STYLE_OPTION_POSITIVE;
           isEditable = true;
         }
 
         function handleCommit(e) {
           $.button.title = 'Edit';
-          $.button.style = Ti.UI.iOS.SystemButtonStyle.PLAIN;
+          $.button.style = Ti.UI.BUTTON_STYLE_OPTION_NEUTRAL;
           isEditable = false;
         }
 

apidoc/Titanium/UI/TabbedBar.yml

@@ -66,26 +66,20 @@ properties:
     summary: Style of the tabbed bar.
     description: |
         Specify one of the constants:
-        For iOS:
-        [Titanium.UI.iOS.SystemButtonStyle](Titanium.UI.iOS.SystemButtonStyle),
-        either `PLAIN`, `BORDERED`, or `BAR`.
-
-        The `BAR` style specifies a more compact style and allows the bar's background
-        color or gradient to show through.
+        For iOS, one use <Titanium.UI.BUTTON_STYLE_OPTION_POSITIVE> or <Titanium.UI.BUTTON_STYLE_OPTION_NEUTRAL>.
 
         For Android use [Titanium.UI.TABS_STYLE_DEFAULT](Titanium.UI.TABS_STYLE_DEFAULT) or
         [Titanium.UI.TABS_STYLE_BOTTOM_NAVIGATION](Titanium.UI.TABS_STYLE_BOTTOM_NAVIGATION) and
         it is only supported in the creation dictionary of the proxy.
     type: Number
-    default: Titanium.UI.iOS.SystemButtonStyle.PLAIN for iOS, Ti.UI.TABS_STYLE_DEFAULT for Android
+    default: Titanium.UI.BUTTON_STYLE_OPTION_NEUTRAL for iOS, Ti.UI.TABS_STYLE_DEFAULT for Android
 examples:
   - title: Simple Tabbed Bar with 3 items
     example: |
         ``` js
         var bb1 = Ti.UI.createTabbedBar({
           labels: ['One', 'Two', 'Three'],
           backgroundColor: '#336699',
-          style: Ti.UI.iOS.SystemButtonStyle.BAR,
           width: 200,
           height: 25,
           top: 50

apidoc/Titanium/UI/TextArea.yml

@@ -603,7 +603,7 @@ examples:
 
         ``` js
         var send = Ti.UI.createButton({
-            style : Ti.UI.iOS.SystemButtonStyle.DONE,
+            style : Ti.UI.BUTTON_STYLE_OPTION_POSITIVE,
             title : 'Send'
         });
 

apidoc/Titanium/UI/TextField.yml

@@ -665,7 +665,7 @@ examples:
 
         var send = Ti.UI.createButton({
             title: 'Send',
-            style: Ti.UI.iOS.SystemButtonStyle.DONE,
+            style: Ti.UI.BUTTON_STYLE_OPTION_POSITIVE,
         });
 
         var camera = Ti.UI.createButton({

apidoc/Titanium/UI/Toolbar.yml

@@ -284,7 +284,7 @@ examples:
 
         var send = Ti.UI.createButton({
             title: 'Send',
-            style: Ti.UI.iOS.SystemButtonStyle.DONE,
+            style: Ti.UI.BUTTON_STYLE_OPTION_POSITIVE,
         });
 
         var camera = Ti.UI.createButton({

apidoc/Titanium/UI/Window.yml

@@ -1498,7 +1498,7 @@ properties:
             <NavigationWindow>
                 <Window>
                     <WindowToolbar>
-                        <Button id="send" title="Send" style="Ti.UI.iOS.SystemButtonStyle.DONE" />
+                        <Button id="send" title="Send" style="Ti.UI.BUTTON_STYLE_OPTION_POSITIVE" />
                         <FlexSpace/>
                         <Button id="camera" systemButton="Ti.UI.iOS.SystemButton.CAMERA" />
                         <FlexSpace/>

apidoc/Titanium/UI/iOS/ButtonConfiguration.yml

@@ -0,0 +1,227 @@
+---
+name: Titanium.UI.iOS.ButtonConfiguration
+summary: |
+    A configuration object for customizing the appearance and behavior of a button.
+description: |
+    The ButtonConfiguration API provides a modern way to configure buttons on iOS with support for 
+    various styles, titles, subtitles, images, and padding. This API wraps the native `UIButtonConfiguration`
+    introduced in iOS 15.0 and represents a modern alternative to the existing Button API while retaining
+    backwards compatibility. In the future, this API may be merged into the root parameters of a button instead.
+
+    Use the <Titanium.UI.iOS.createButtonConfiguration> method to create a button configuration.
+
+    Button configurations support several predefined styles:
+    - **plain**: A plain button style with minimal background
+    - **tinted**: A tinted button style with a subtle background
+    - **filled**: A filled button style with a solid background
+    - **gray**: A gray button style
+    - **borderless**: A borderless button style
+    - **bordered**: A bordered button style with an outline
+    - **borderedTinted**: A bordered button style with a tinted outline
+    - **borderedProminent**: A bordered button style with a prominent appearance
+
+    Additional styles available on iOS 26.0+:
+    - **glass**: A glass-like appearance
+    - **prominentGlass**: A prominent glass-like appearance
+    - **clearGlass**: A clear glass-like appearance
+    - **prominentClearGlass**: A prominent clear glass-like appearance
+
+extends: Titanium.Proxy
+platforms: [iphone, ipad, macos]
+since: {iphone: "13.0.0", ipad: "13.0.0", macos: "13.0.0"}
+osver: {ios: {min: "15.0"}}
+
+properties:
+  - name: style
+    summary: The style of button configuration to create.
+    description: |
+        Sets the base configuration style for the button. This property should be set first
+        as it determines the initial configuration that other properties will modify.
+
+        Valid string values are:
+        - `"plain"`: A plain button style with minimal background
+        - `"tinted"`: A tinted button style with a subtle background
+        - `"filled"`: A filled button style with a solid background
+        - `"gray"`: A gray button style
+        - `"borderless"`: A borderless button style
+        - `"bordered"`: A bordered button style with an outline
+        - `"borderedTinted"`: A bordered button style with a tinted outline
+        - `"borderedProminent"`: A bordered button style with a prominent appearance
+        - `"glass"`: A glass-like appearance (iOS 26.0+)
+        - `"prominentGlass"`: A prominent glass-like appearance (iOS 26.0+)
+        - `"clearGlass"`: A clear glass-like appearance (iOS 26.0+)
+        - `"prominentClearGlass"`: A prominent clear glass-like appearance (iOS 26.0+)
+    type: String
+    availability: creation
+
+  - name: title
+    summary: The title text to display on the button.
+    type: String
+
+  - name: subtitle
+    summary: The subtitle text to display below the title.
+    type: String
+
+  - name: backgroundColor
+    summary: The background color of the button.
+    description: |
+        Sets the base background color for the button. This color may be modified
+        by the system based on the button state and configuration style.
+    type: [String, Titanium.UI.Color]
+
+  - name: color
+    summary: The foreground color of the button's content.
+    description: |
+        Sets the base foreground color for the button's title and subtitle text.
+        This color may be modified by the system based on the button state.
+    type: [String, Titanium.UI.Color]
+
+  - name: image
+    summary: The image to display on the button.
+    description: |
+        The image to display alongside the button's title. Use the imagePlacement
+        property to control where the image appears relative to the title.
+    type: [String, Titanium.Blob, Titanium.Filesystem.File]
+
+  - name: padding
+    summary: The padding around the button's content.
+    description: |
+        An object with top, left, bottom, and right properties to specify
+        the content insets for the button.
+    type: Padding
+
+  - name: imagePlacement
+    summary: The placement of the image relative to the title.
+    description: |
+        Controls where the button's image appears relative to its title text.
+
+        Valid string values are:
+        - `"leading"`: Place the image before the title text
+        - `"trailing"`: Place the image after the title text
+        - `"top"`: Place the image above the title text
+        - `"bottom"`: Place the image below the title text
+    type: String
+    default: "leading"
+
+  - name: imagePadding
+    summary: The spacing between the image and title.
+    description: |
+        The amount of spacing in points between the button's image and its title text.
+    type: Number
+    default: 0
+
+  - name: titlePadding
+    summary: The spacing between the title and subtitle.
+    description: |
+        The amount of spacing in points between the button's title and subtitle text.
+    type: Number
+    default: 0
+
+  - name: font
+    summary: Font to use for the button title.
+    description: |
+        Sets the font applied to the configuration’s title via the underlying
+        `UIButtonConfiguration.titleTextAttributesTransformer`.
+
+        When using `attributedString`, prefer setting font in the attributed content instead.
+    type: Font
+
+  - name: textAlign
+    summary: Text alignment of the configuration title.
+    description: |
+        Aligns the title within the button’s content area. Maps to
+        `UIButtonConfigurationTitleAlignment`.
+    type: [String, Number]
+    constants: Titanium.UI.TEXT_ALIGNMENT_*
+
+  - name: attributedString
+    summary: Specify an attributed string for the button title.
+    description: |
+        Sets the configuration’s `attributedTitle`. If set, avoid also setting
+        `title`, `color`, and `font` to prevent conflicting styles.
+    type: Titanium.UI.AttributedString
+
+  - name: backgroundSelectedColor
+    summary: Background color to use while the button is highlighted (pressed).
+    description: |
+        When this configuration is assigned to a <Titanium.UI.Button> and both
+        `backgroundColor` and `backgroundSelectedColor` are provided, the button will
+        automatically swap the configuration’s background to `backgroundSelectedColor`
+        when highlighted and restore the base color when not highlighted.
+
+        This mirrors the traditional `backgroundSelectedColor` behavior on views when
+        used with modern button configurations.
+    type: [String, Titanium.UI.Color]
+
+examples:
+  - title: Basic Button Configuration
+    example: |
+        ``` js
+        const button = Ti.UI.createButton({
+            configuration: Ti.UI.iOS.createButtonConfiguration({
+                style: 'filled',
+                title: 'Sign In',
+                subtitle: 'with your account',
+                backgroundColor: '#007AFF',
+                color: 'white'
+            })
+        });
+        ```
+
+  - title: Button with Image and Padding
+    example: |
+        ``` js
+        const button = Ti.UI.createButton({
+            configuration: Ti.UI.iOS.createButtonConfiguration({
+                style: 'borderedTinted',
+                title: 'Upload',
+                image: 'upload-icon.png',
+                imagePlacement: 'leading',
+                imagePadding: 8,
+                padding: {
+                    top: 12,
+                    left: 20,
+                    bottom: 12,
+                    right: 20
+                }
+            })
+        });
+        ```
+
+  - title: Prominent Button Style
+    example: |
+        ``` js
+        const button = Ti.UI.createButton({
+            configuration: Ti.UI.iOS.createButtonConfiguration({
+                style: 'borderedProminent',
+                title: 'Get Started',
+                backgroundColor: '#34C759'
+            })
+        });
+        ```
+
+  - title: Typography and Alignment
+    example: |
+        ``` js
+        const button = Ti.UI.createButton({
+            configuration: Ti.UI.iOS.createButtonConfiguration({
+                style: 'filled',
+                title: 'Continue',
+                font: { fontSize: 18, fontWeight: 'semibold' },
+                textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER
+            })
+        });
+        ```
+
+  - title: Highlighted Background Color
+    example: |
+        ``` js
+        const button = Ti.UI.createButton({
+            configuration: Ti.UI.iOS.createButtonConfiguration({
+                style: 'filled',
+                title: 'Tap Me',
+                backgroundColor: '#007AFF',
+                backgroundSelectedColor: '#005BBB' // shown while pressed
+            })
+        });
+        ```