@nativescript-community/ui-appbar 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 1.0.0 (2026-10-18)
+
+### Features
+
+* hideOnScroll for the floating action button and bottom navigation bar, app bar docs ([db77d43](https://github.com/nativescript-community/ui-material-components/commit/db77d43097eb1188a053420d955264ad842059d5))
+* native-api-usage.json for every package on Android and iOS ([cfd7dcc](https://github.com/nativescript-community/ui-material-components/commit/cfd7dcc4b996b02319cfacee233bc56c29df70e4))
+* **ui-appbar:** a view inside an appBarItem is its actionView (uibutton in the bar) ([dcb9a7f](https://github.com/nativescript-community/ui-material-components/commit/dcb9a7f4fbeb04955558ce42408fca079a78467c))
+* **ui-appbar:** action items with menu / prominent, search (UISearchController / SearchView) ([5b59641](https://github.com/nativescript-community/ui-material-components/commit/5b596415b3891ed375a6969f57f1e006f750c200))
+* **ui-appbar:** Android searchMode=bar (Material 3 SearchBar + SearchView, searchContent) ([5bae2cb](https://github.com/nativescript-community/ui-material-components/commit/5bae2cbfffa68586779e4c569bb4152c43d5f54b))
+* **ui-appbar:** AppBar (size, scroll behavior, subtitle, spans, translucent, scrollTarget) for Android and iOS ([75f8aee](https://github.com/nativescript-community/ui-material-components/commit/75f8aee2a5c513de549345083051499566016287))
+* **ui-appbar:** AppPage spike (Coordinator nested in the Page root, gesturehandler compatible) ([0c063c3](https://github.com/nativescript-community/ui-material-components/commit/0c063c33b1c5c875605642ac81406d4778c9dbe4))
+* **ui-appbar:** badges on items and bottom items, iOS 26 searchPlacement ([d262fb5](https://github.com/nativescript-community/ui-material-components/commit/d262fb588cb30842eeb237fe00184d06a945eea1))
+* **ui-appbar:** bottomItems (UIToolbar / BottomAppBar), inline title of collapsed pushed large titles on iOS ([baab2b7](https://github.com/nativescript-community/ui-material-components/commit/baab2b79a134c7f717cd31179d4fd0d0ad0069c3))
+* **ui-appbar:** page overlay, hide for large bars, translucent bar with content under it (iOS blur, Android tint) ([05e7a88](https://github.com/nativescript-community/ui-material-components/commit/05e7a88372a2b78404f3069acc01678596ef74e7))
+
+### Bug Fixes
+
+* **ui-appbar:** Android bar surface, modern tinted icons, lift, translucent small/large, keyboard and search layout ([c08c549](https://github.com/nativescript-community/ui-material-components/commit/c08c54918c0cc3f61f4a3dc08c30705bd4ab650c))

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,280 @@
-# Temporary Holding Version
+<!-- ⚠️ This README has been generated from the file(s) "blueprint.md" ⚠️-->
+<!--  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      DO NOT EDIT THIS READEME DIRECTLY! Edit "bluesprint.md" instead.
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
+<h1 align="center">@nativescript-community/ui-appbar</h1>
+<p align="center">
+		<a href="https://npmcharts.com/compare/@nativescript-community/ui-appbar?minimal=true"><img alt="Downloads per month" src="https://img.shields.io/npm/dm/@nativescript-community/ui-appbar.svg" height="20"/></a>
+<a href="https://www.npmjs.com/package/@nativescript-community/ui-appbar"><img alt="NPM Version" src="https://img.shields.io/npm/v/@nativescript-community/ui-appbar.svg" height="20"/></a>
+	</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <b>App bar and page: Material top app bar (collapsing, lift on scroll) on Android, native navigation bar on iOS</b></br>
+  <sub><sub>
+</p>
+
+<br />
+
+
+| iOS | Android |
+| --- | --- |
+| <img src="https://github.com/nativescript-community/ui-native-components/raw/master/images/ui-appbar-ios.png" height="500" /> | <img src="https://github.com/nativescript-community/ui-native-components/raw/master/images/ui-appbar-android.png" height="500" /> |
+
+
+[](#table-of-contents)
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Usage](#usage)
+* [API](#api)
+* [Items](#items)
+* [Hide on scroll](#hide-on-scroll)
+* [Bottom items](#bottom-items)
+* [Overlay](#overlay)
+* [Demos and Development](#demos-and-development)
+	* [Repo Setup](#repo-setup)
+	* [Build](#build)
+	* [Demos](#demos)
+* [Contributing](#contributing)
+	* [Update repo ](#update-repo-)
+	* [Update readme ](#update-readme-)
+	* [Update doc ](#update-doc-)
+	* [Publish](#publish)
+	* [modifying submodules](#modifying-submodules)
+* [Questions](#questions)
+
+
+[](#installation)
+
+## Installation
+
+```bash
+npm install @nativescript-community/ui-appbar
+```
+
+The Android components use **Material 3**: see the [repository README](https://github.com/nativescript-community/ui-native-components#installation) for the theme.
+
+
+[](#usage)
+
+## Usage
+
+| | Android | iOS |
+|---|---|---|
+| `AppPage` | Page whose content is in a `CoordinatorLayout` (nested in the Page root: compatible with gesturehandler) | regular Page |
+| `AppBar` | `MaterialToolbar` in an `AppBarLayout`, M3 `CollapsingToolbarLayout` for `medium` / `large` | the navigation bar (Liquid Glass buttons on iOS 26), large title |
+
+```svelte
+<appPage>
+  <appBar title="Inbox" subtitle="3 unread" size="large" scrollBehavior="lift" />
+  <collectionview ... />
+</appPage>
+```
+
+Register the svelte elements once (`registerElement` of svelte-native): `import { register } from '@nativescript-community/ui-appbar/svelte'; register();`.
+
+
+[](#api)
+
+## API
+
+| property | |
+|---|---|
+| `size` | `small` (default), `medium`, `large`: title that collapses with the scroll |
+| `scrollBehavior` (Android notes: the surface of the bar is the AppBarLayout, the toolbar is flat and transparent; the icons follow the css `color`, the surface the css `background-color`, else the theme colors; `lift` changes the surface color and the status bar area follows) | `none`, `lift` (elevation / separator only when content scrolls under the bar), `hide` (the whole bar, also a large one, leaves the screen when scrolling down and comes back when scrolling up) |
+| `subtitle`, `formattedTitle` | subtitle, title with spans |
+| `translucent` | the content scrolls under the bar, which is see through: iOS a blur tinted with the color of the bar, Android the color of the bar at 85%. Set `scrollTarget`; the scrolling view must be the content of the page (iOS) |
+| `searchable`, `searchHint` | search: iOS `UISearchController` under the title, Android a collapsible `SearchView` action. Events `searchChange`, `searchSubmit`, `searchCancel` (`text`) |
+| `searchMode` | Android: `collapsible` (default, a search icon in the bar) or `bar` (Material 3 `SearchBar` under the title which opens a full screen `SearchView`; its suggestions / results go in `<appPageSearchContent>`, a child of the page) |
+| `searchPlacement` | iOS 26: where the search bar goes: `stacked` (under the title, default), `integrated` (a glass button / field in the bar), `integratedButton`, `integratedCentered`, `automatic` |
+| `scrollTarget` | the scrolling view the bar follows (iOS: `setContentScrollView`) |
+
+Status and limits: see [APPBAR_PLAN.md](../../APPBAR_PLAN.md). On iOS a large title on a pushed page uses the UIKit `Always` mode, which never shows the inline title: a title view is shown while the bar is collapsed (the height of the bar tells). On the root page of the Frame UIKit does it.
+On Android the bar draws under the status bar (edge to edge) and the page handles the inset.
+
+
+[](#items)
+
+## Items
+
+`<appBarItem>` is the core `ActionItem` with `menu` (items of `@nativescript-community/ui-menu`: iOS native menu of the bar button, Android popup menu) and `prominent` (iOS 26 tinted glass).
+
+```svelte
+<appBar title="Inbox">
+  <appBarItem text="More" icon="sys://ellipsis" menu={[{ title: 'Share', onSelect }, { separator: true }, { title: 'Delete', destructive: true }]} />
+  <appBarItem text="Edit" prominent />
+</appBar>
+```
+
+
+[](#hide-on-scroll)
+
+## Hide on scroll
+
+`hideOnScroll` (the scrolling view) of `@nativescript-community/ui-floatingactionbutton` and `@nativescript-community/ui-bottomnavigationbar`: hidden when the content scrolls down, shown when it scrolls up.
+
+```svelte
+<appPage>
+  <appBar searchable searchMode="bar" on:searchChange={(e) => (query = e.text)} />
+  <collectionview ... />
+  <appPageSearchContent><label text="results for {query}" /></appPageSearchContent>
+</appPage>
+```
+On iOS `searchMode` and `searchContent` are ignored: the `UISearchController` is used, filter the main content from `searchChange`.
+
+`badge` on an item (and on a bottom item): a number, a text or `true` (a dot). Android `BadgeDrawable`, iOS 26 `UIBarButtonItemBadge` (the iOS 26.5 bottom toolbar does not draw it, the navigation bar does).
+
+A view inside the item is its `actionView`: use our components in the bar. The view gets its own `tap` event.
+On iOS 26 the system puts it in a Liquid Glass capsule, use a plain / text variant of the button.
+
+```svelte
+<appBarItem ios.position="right" android.position="actionBar">
+  <uibutton text="Go" variant="text" on:tap={go} />
+</appBarItem>
+```
+
+
+[](#bottom-items)
+
+## Bottom items
+
+`bottomItems` (`{ text, icon, spacer, onTap }`, event `bottomItemTap`): iOS the bottom toolbar of the navigation controller (Liquid Glass buttons on iOS 26, `spacer` is a flexible space), Android a Material `BottomAppBar` (with `scrollBehavior="hide"` it hides on scroll; the actions are at the start, `spacer` is ignored).
+The last items of the `scrollTarget` stay above the Android bar.
+
+```svelte
+<appBar bottomItems={[{ icon: 'sys://house', text: 'Home', onTap }, { spacer: true }, { icon: 'sys://plus', text: 'Add', onTap }]} />
+```
+
+
+[](#overlay)
+
+## Overlay
+
+Views anchored to the page itself (a FAB, a bottom bar) go in `<appPageOverlay>`, not in the page content: on Android the content of an `AppPage` is taller than the screen while a medium / large bar is expanded, so a bottom anchored view would be off screen.
+On iOS the overlay is laid out over the content, inside the safe area; its empty areas let the touches go through.
+
+```svelte
+<appPage>
+  <appBar ... />
+  <collectionview ... />
+  <appPageOverlay>
+    <uifloatingactionbutton verticalAlignment="bottom" horizontalAlignment="right" />
+  </appPageOverlay>
+</appPage>
+```
+
+
+[](#demos-and-development)
+
+## Demos and Development
+
+
+### Repo Setup
+
+The repo uses submodules. If you did not clone with ` --recursive` then you need to call
+```
+git submodule update --init
+```
+
+The package manager used to install and link dependencies must be `pnpm` or `yarn`. `npm` wont work.
+
+To develop and test:
+if you use `yarn` then run `yarn`
+if you use `pnpm` then run `pnpm i`
+
+**Interactive Menu:**
+
+To start the interactive menu, run `npm start` (or `yarn start` or `pnpm start`). This will list all of the commonly used scripts.
+
+### Build
+
+```bash
+npm run build.all
+```
+WARNING: it seems `yarn build.all` wont always work (not finding binaries in `node_modules/.bin`) which is why the doc explicitly uses `npm run`
+
+### Demos
+
+```bash
+npm run demo.[ng|react|svelte|vue].[ios|android]
+
+npm run demo.svelte.ios # Example
+```
+
+Demo setup is a bit special in the sense that if you want to modify/add demos you dont work directly in `demo-[ng|react|svelte|vue]`
+Instead you work in `demo-snippets/[ng|react|svelte|vue]`
+You can start from the `install.ts` of each flavor to see how to register new demos 
+
+
+[](#contributing)
+
+## Contributing
+
+### Update repo 
+
+You can update the repo files quite easily
+
+First update the submodules
+
+```bash
+npm run update
+```
+
+Then commit the changes
+Then update common files
+
+```bash
+npm run sync
+```
+Then you can run `yarn|pnpm`, commit changed files if any
+
+### Update readme 
+```bash
+npm run readme
+```
+
+### Update doc 
+```bash
+npm run doc
+```
+
+### Publish
+
+The publishing is completely handled by `lerna` (you can add `-- --bump major` to force a major release)
+Simply run 
+```shell
+npm run publish
+```
+
+### modifying submodules
+
+The repo uses https:// for submodules which means you won't be able to push directly into the submodules.
+One easy solution is t modify `~/.gitconfig` and add
+```
+[url "ssh://git@github.com/"]
+	pushInsteadOf = https://github.com/
+```
+
+
+[](#questions)
+
+## Questions
+
+If you have any questions/issues/comments please feel free to create an issue or start a conversation in the [NativeScript Community Discord](https://nativescript.org/discord).

package/index-common.d.ts

@@ -0,0 +1,101 @@
+import { ActionBar, ActionItem, EventData, FormattedString, GridLayout, ImageSource, Property, View } from '@nativescript/core';
+import { MenuItem } from '@nativescript-community/ui-menu';
+/** small: standard bar, medium / large: a title that collapses on scroll (M3 collapsing app bar on Android, large title on iOS) */
+export type AppBarSize = 'small' | 'medium' | 'large';
+/**
+ * none: the bar stays,
+ * lift: the bar gets an elevation / separator only when the content scrolls under it,
+ * hide: the bar leaves the screen when scrolling down and comes back when scrolling up
+ */
+export type AppBarScrollBehavior = 'none' | 'lift' | 'hide';
+export declare const sizeProperty: Property<AppBarBase, AppBarSize>;
+export declare const scrollBehaviorProperty: Property<AppBarBase, AppBarScrollBehavior>;
+export declare const subtitleProperty: Property<AppBarBase, string>;
+export declare const formattedTitleProperty: Property<AppBarBase, FormattedString>;
+export declare const translucentProperty: Property<AppBarBase, boolean>;
+export declare const searchableProperty: Property<AppBarBase, boolean>;
+export declare const searchHintProperty: Property<AppBarBase, string>;
+export declare const scrollTargetProperty: Property<AppBarBase, View>;
+export declare const badgeProperty: Property<AppBarItem, string | number | boolean>;
+export declare const menuProperty: Property<AppBarItem, MenuItem[]>;
+export declare const prominentProperty: Property<AppBarItem, boolean>;
+/**
+ * An action of the bar. In addition to the core `ActionItem` (text, icon, `actionView`, `android.position`...):
+ * - `menu`: items of a menu shown when the action is tapped (iOS: native menu of the bar button, Android: popup menu)
+ * - `prominent`: iOS 26 tinted Liquid Glass button
+ */
+export declare class AppBarItem extends ActionItem {
+    menu: MenuItem[];
+    prominent: boolean;
+    /** a badge on the action: a number, a text, or `true` for a dot. iOS 26 and Android */
+    badge: string | number | boolean;
+    _addChildFromBuilder(name: string, value: any): void;
+    _raiseTap(): void;
+}
+export interface AppBarSearchEventData extends EventData {
+    text: string;
+}
+/**
+ * An action of the bottom bar (`bottomItems`): iOS a button of the bottom toolbar (Liquid Glass on iOS 26), Android an action of the Material `BottomAppBar`.
+ */
+export interface AppBarBottomItem {
+    /** `sys://name` (SF Symbol, iOS), `res://name` or a file path, an ImageSource, or a FormattedString */
+    icon?: string | ImageSource | FormattedString;
+    text?: string;
+    /** iOS: a flexible space between the buttons. Android: ignored (the actions are at the end of the bar) */
+    spacer?: boolean;
+    /** a badge on the action: a number, a text, or `true` for a dot */
+    badge?: string | number | boolean;
+    /** called when the action is tapped */
+    onTap?: (item: AppBarBottomItem) => void;
+    [key: string]: any;
+}
+/** collapsible: a search icon in the bar that expands (Android SearchView action). bar: Android Material 3 `SearchBar` under the title that opens a full screen `SearchView`. iOS: always the `UISearchController` */
+export type AppBarSearchMode = 'collapsible' | 'bar';
+export declare const searchModeProperty: Property<AppBarBase, AppBarSearchMode>;
+/** iOS 26 placement of the search bar of the navigation bar: stacked (under the title, default), integrated (a field / button in the bar), integratedButton (always a button), integratedCentered (centered on iPad), automatic */
+export type AppBarSearchPlacement = 'automatic' | 'stacked' | 'integrated' | 'integratedButton' | 'integratedCentered';
+export declare const searchPlacementProperty: Property<AppBarBase, AppBarSearchPlacement>;
+export declare const bottomItemsProperty: Property<AppBarBase, AppBarBottomItem[]>;
+export declare class AppBarBase extends ActionBar {
+    static bottomItemTapEvent: string;
+    /** actions of a bar at the bottom of the page: iOS the bottom toolbar, Android a `BottomAppBar` */
+    bottomItems: AppBarBottomItem[];
+    /** raised when the text of the search changes */
+    static searchChangeEvent: string;
+    /** raised when the search is submitted (keyboard search key) */
+    static searchSubmitEvent: string;
+    /** raised when the search is closed / cancelled */
+    static searchCancelEvent: string;
+    /** adds a search: iOS `UISearchController` under the title, Android a collapsible `SearchView` action */
+    searchable: boolean;
+    searchHint: string;
+    searchMode: AppBarSearchMode;
+    searchPlacement: AppBarSearchPlacement;
+    /** the current text of the search (read only) */
+    searchText: string;
+    size: AppBarSize;
+    scrollBehavior: AppBarScrollBehavior;
+    subtitle: string;
+    /** the title with spans (needs `@nativescript-community/text` for the full support) */
+    formattedTitle: FormattedString;
+    /** the content goes under the bar, the bar is see through until the content scrolls */
+    translucent: boolean;
+    /** the scrolling view (collectionview, scrollview...) that drives the bar. By default the first one found */
+    scrollTarget: View;
+    onAppBarPropertyChanged(): void;
+}
+/**
+ * Layout for the views anchored to the page itself (a floating action button, a bottom bar...), not to the scrolling content: use it as the `overlay` of an AppPage.
+ * Android: the content of an AppPage is taller than the screen while the bar is expanded (the content moves up when the bar collapses), so a view anchored to the bottom of the content would be off screen.
+ */
+export declare class AppPageOverlay extends GridLayout {
+    constructor();
+}
+/** raises the tap of a bottom item: the `onTap` of the item and the `bottomItemTap` event of the bar */
+export declare function notifyBottomItemTap(bar: AppBarBase, item: AppBarBottomItem): void;
+/**
+ * Android `searchMode="bar"`: the content of the full screen search (suggestions, results): use it as the `searchContent` of an AppPage. Ignored on iOS.
+ */
+export declare class AppPageSearchContent extends GridLayout {
+}