Merge remote-tracking branch 'origin/main' into feat/flavor-snippets

Author: NathanWalker

.vitepress/config.mts

@@ -27,6 +27,15 @@ export default defineConfig({
   lang: 'en-US',
   title: 'NativeScript',
   description: 'NativeScript docs',
+  head: [
+    [
+      'script',
+      {
+        async: 'true',
+        src: 'https://vueschool.io/banner.js?affiliate=NSCRIPT&type=top',
+      }  
+    ],
+  ],
   ignoreDeadLinks: true,
   cleanUrls: true,
   lastUpdated: true,

content/configuration/nativescript.md

@@ -359,9 +359,9 @@ Discard any uncaught JS exceptions. This can be useful in production environment
 
 ### ios.SPMPackages
 
-::: tip Experimental
+::: tip
 
-SPM packages are available in `[email protected]` or newer and are experimental.
+SPM packages are available in `[email protected]` or newer.
 
 :::
 

content/core/observable.md

@@ -71,7 +71,7 @@ this.notifyPropertyChange('fruits', this.fruits)
 
 ### Avoiding Event Handler Memory Leak
 
-To ensure that your app doesn't have memory leak caused by handlers that are no longer needed, use the [addWeakEventListener](#addweakeventlistener) function:
+To ensure that your app doesn't have memory leak caused by handlers that are no longer needed, use the [addWeakEventListener](#addweakeventlistener) function.
 
 <!-- TODO: Add a working example -->
 
@@ -144,21 +144,28 @@ Adds a one-time listener for the specified event.
 
 ### addWeakEventListener()
 
+```ts
+observable.addWeakEventListener(source, eventName, callback, target)
+```
+
+Attaches a Weak Event Listener.
+
+- `source`: Observable class which emits the event.
+- `eventName`: The event name the specified listener listens to.
+- `callback`: The function which should be called when event occurs.
+- `target`: Subscriber (target) of the event listener. It will be used as a thisArg in the handler function.
+
 ### removeEventListener()
 
 ```ts
-Observable.removeEventListener(eventNames, callback, thisArg)
-
-//or
-observable.removeEventListener(eventNames, callback, thisArg)
+observable.removeEventListener(eventNames, callback, target)
 ```
 
 Removes listener(s) for the specified event name(s).
 
-- `eventNames` is a comma delimited string containing the names of the events the specified listener listens to.
-- _Optional_: The `callback` parameter points to a specific listener to be removed. If not defined, all listeners for the event names will be removed.
-<!-- Is the following definition correct -->
-- _Optional_: `thisArg` is a parameter used as `this` context in which the listener to be removed will be searched.
+- `eventNames`: Comma delimited string containing the names of the events the specified listener listens to.
+- `callback`: A specific listener to be removed. If not defined, all listeners for the event names will be removed.
+- `target`: Subscriber (target) of the event listener. It will be used as a thisArg in the handler function.
 
 ---
 

content/guide/extending-classes-and-implementing-interfaces-android.md

@@ -282,7 +282,7 @@ This approach will not work if `application.android.ts` requires external module
 
 @nativescript/core ships with a default `androidx.appcompat.app.AppCompatActivity` implementation, that bootstraps the NativeScript application, without forcing users to declare their custom Activity in every project. In some cases you may need to implement a custom Android Activity.
 
-Create a new `activity.android.ts` or `activity.android.js` when using plain JS.
+Create a new `./src/activity.android.ts` or `./src/activity.android.js` when using plain JS.
 
 ::: info Note
 Note the `.android` suffix - we only want this file on Android.
@@ -493,9 +493,10 @@ To include the new Activity in the build, make sure it's added to the `webpack.c
 const webpack = require('@nativescript/webpack')
 
 module.exports = (env) => {
-  env.appComponents = (env.appComponents || []).concat(['./activity.android'])
-
   webpack.init(env)
+  env.appComponents = (env.appComponents || []).concat([
+    './src/activity.android',
+  ])
 
   return webpack.resolveConfig()
 }

content/guide/navigation/modals.md

@@ -4,67 +4,143 @@ description: Navigation using modals - detached from the current backstack.
 contributos:
   - Ombuweb
   - rigor789
+  - flipperlite
 ---
 
 ## Showing a modal
 
 To show a modal, call the [showModal](https://docs.nativescript.org/api/class/ViewCommon#showmodal) method on a [View](https://docs.nativescript.org/api/class/View) instance and pass it the path to the modal view file:
 
+<!-- note: we need a "Open In StackBlitz" button, and also put these in an official NativeScript collection to link on the docs. -->
+<!-- A strongly typed, working, Typescript application can be [found here](https://stackblitz.com/edit/nativescript-stackblitz-templates-3bvo1g?file=app%2Fdetails-page.ts,app%2Fdetails-page.xml,app%2Fmain-page.ts).  -->
+
 ```xml
-<Button text="View details" tap="onTap" />
+<Button text="Show a Modal" tap="onShowModal" />
 ```
 
 ```ts
-onTap(args: EventData) {
-  const button = args.object as Button
-  button.showModal("details-page")
+import { EventData, View, ShowModalOptions } from '@nativescript/core'
+
+export function onShowModal(args: EventData) {
+  const view = args.object as View
+  const options: ShowModalOptions = {
+    // ...
+  }
+  view.showModal('details-page', options)
 }
 ```
 
+:::warning Note
+If your modal does not appear when tapping the button, confirm you set the correct path and the modal page exists. `showModal` does not throw an error when the provided path doesn't exist.
+:::
+
 ## Closing a modal
 
-To close a modal, call the `closeModal` method of any `View` from the modal. Optionally pass it data you want to access in the parent page:
+To close a modal, call the `closeModal` method of any `View` from the modal.
+
+For passing data back to the parent, see [Passing Data](#passing-data).
 
 ```xml
-<Button text="Close" tap="onTap" />
+<Button text="Close a Modal" tap="onCloseModal"/>
 ```
 
 ```ts
-onTap(args: EventData) {
-  const button = args.object as Button
-  button.closeModal({
-    name: 'John Doe - EDITED',
-  })
+export function onCloseModal(args: EventData) {
+  const view = args.object as View
+  view.closeModal()
 }
 ```
 
-## Passing data to and from a modal
+## Passing data {#passing-data}
+
+Modals are often used for prompting the user for input, this requires passing data between the parent and the modal.
 
-Passing data can be done by passing a `context` in the `showModal` options parameter.
+### From parent to modal
+
+To pass data to the modal, provide it in the `context` field of the ShowModalOptions:
 
 ```ts
+// main-page.ts
+import { ShowModalOptions } from '@nativescript/core'
+
+// optionally use strong types
+import { ExampleModalContext } from './details-page'
+
 const options: ShowModalOptions = {
-  context: { name: 'John Doe' },
-  closeCallback(args: { name: string }) {
-    console.log('Modal closed', args.name)
-  },
+  context: {
+    name: 'John Doe',
+  } as ExampleModalContext,
 }
-// ...
+
 button.showModal('details-page', options)
 ```
 
-To access the data in the modal, handle the `shownModally` event, and access it via `args.context`.
+In the modal page, listen to the `shownModally` event to access the `context`:
 
 ```xml
+<!-- details-page.xml -->
+<Page shownModally="onShownModally"/>
+```
+
+```ts
+// details-page.ts
+import { ShownModallyData } from '@nativescript/core'
+
+// optional strong type for the context
+export type ExampleModalContext = {
+  name: string
+}
+
+export function onShownModally(args: ShownModallyData) {
+  const context = args.context as ExampleModalContext
+  console.log(context.name) // 'John Doe'
+}
+```
+
+### From modal to parent
+
+When closing a modal, you can optionally pass data back to the parent. To do so, provide a `closeCallback` option in the ShowModalOptions:
+
+```ts
+// main-page.ts
+
+import { ShowModalOptions } from '@nativescript/core'
+
+// optionally use strong types
+import { ExampleModalContext, ExampleModalResult } from './details-page'
+
+const options: ShowModalOptions = {
+  context: {
+    name: 'John Doe',
+  } as ExampleModalContext,
+  closeCallback(result?: ExampleModalResult) {
+    if (result) {
+      console.log(`Modal returned: ${result.newName}`) // 'Modal returned: Jane Doe'
+      return
+    }
+    console.log('Modal was cancelled.')
+  },
+}
+
+button.showModal('details-page', options)
+```
+
+In the modal page, listen to the `shownModally` event to access the `context`.
+
+::: code-group
+
+```xml [details-page.xml]
 <Page shownModally="onShownModally">
   <StackLayout>
+    <!-- ... -->
     <TextField text="{{ name }}" />
-    <Button text="Close" tap="onClose"/>
+    <Button text="Change Name" tap="onChangeName"></Button>
+    <Button text="Cancel" tap="onCancel"></Button>
   </StackLayout>
 </Page>
 ```
 
-```ts
+```ts [details-page.ts]
 import {
   fromObject,
   Page,
@@ -73,17 +149,39 @@ import {
   EventData,
 } from '@nativescript/core'
 
+// optional strong type for the context
+export type ExampleModalContext = {
+  name: string
+}
+
+export type ExampleModalResult = {
+  newName: string
+}
+
 export function onShownModally(args: ShownModallyData) {
   const page = args.object as Page
-  const context = fromObject({
-    ...args.context,
-    onClose(args: EventData) {
+  const incomingContext = args.context as ExampleModalContext
+
+  const bindingContext = fromObject({
+    ...incomingContext,
+    onChangeName(args: EventData) {
       const button = args.object as Button
       button.closeModal({
-        name: context.name, // 'John Doe - EDITED'
-      })
+        newName: bindingContext.name, // 'Jane Doe'
+      } as ExampleModalResult)
+    },
+    onCancel(args: EventData) {
+      const view = args.object as View
+      view.closeModal()
     },
   })
-  page.bindingContext = context
+  page.bindingContext = bindingContext
 }
 ```
+
+:::
+
+## Additional Resources
+
+- [NativeScript XML Data Binding](/guide/data-binding)
+- [TextField](/ui/text-field)