docs: UI docs

.github/workflows/ci.yml

@@ -5,6 +5,8 @@ on:
     branches: [main, docs/ui]
   pull_request:
     branches: [main, docs/ui]
+  merge_group:
+    branches: [main, docs/ui]
 
 jobs:
   build:

.gitignore

@@ -5,5 +5,7 @@ node_modules
 .vitepress/dist
 .vitepress/cache
 
+explore/
+
 yarn.lock
 .DS_Store

.textlintrc

@@ -72,6 +72,7 @@
         ["labelled", "labeled"],
         ["licence", "license"],
         ["organise", "organize"],
+        ["optimise", "optimize"],
 
         // Common misspellings
         ["gaurantee", "guarantee"],

.vitepress/config.mts

@@ -1,6 +1,7 @@
 import { defineConfig } from 'vitepress'
 import apiSidebar from '../content/api/sidebar.json'
 import mainSidebar from '../content/sidebar'
+import uiSidebar from '../content/ui/sidebar'
 import nav from './nav'
 import './theme/cliLanguage'
 import path from 'node:path'
@@ -36,6 +37,7 @@ export default defineConfig({
     nav,
     sidebar: {
       '/api': apiSidebar,
+      '/ui': uiSidebar,
       '/': mainSidebar,
     },
   },

.vitepress/nav.ts

@@ -12,21 +12,22 @@ export default [
   {
     text: 'Docs',
     link: '/',
-    activeMatch: '^/(?!plugins|best-practices|api|dev-reference|tutorials)',
+    activeMatch: '^/(?!plugins|best-practices|api|dev-reference|tutorials|ui)',
     icon: 'BookOpenIcon',
   },
-  {
-    text: 'Preview',
-    link: 'https://preview.nativescript.org',
-    icon: 'DevicePhoneMobileIcon',
-    target: '_blank',
-  },
+
   {
     text: 'Tutorials',
     link: '/tutorials/',
     activeMatch: '^/tutorials',
     icon: 'AcademicCapIcon',
   },
+  {
+    text: 'Preview',
+    link: 'https://preview.nativescript.org',
+    icon: 'DevicePhoneMobileIcon',
+    target: '_blank',
+  },
   {
     text: 'Plugins',
     link: '/soon',
@@ -44,6 +45,12 @@ export default [
     link: '/soon',
     icon: 'CpuChipIcon',
   },
+  {
+    text: 'UI Components',
+    link: '/ui/',
+    activeMatch: '^/ui',
+    icon: 'CubeTransparentIcon',
+  },
   {
     text: 'API Reference',
     link: '/api/',

content/api/class/Image.md

@@ -10,7 +10,7 @@ breadcrumbs:
   - name: 'Image'
 layout: api
 seo:
-  description: "Represents a class that provides functionality for loading and streching image(s)."
+  description: "Represents a class that provides functionality for loading and streching images."
 ---
 
 <!-- This page is auto generated, do not edit manually. -->

content/guide/navigation/modals.md

@@ -0,0 +1,89 @@
+---
+title: Navigation using Modals
+description: Navigation using modals - detached from the current backstack.
+contributos:
+  - Ombuweb
+  - rigor789
+---
+
+## Showing a modal
+
+To show a modal, call the [showModal](https://docs.nativescript.org/api-reference/classes/view#showmodal) method on a [View](https://docs.nativescript.org/api-reference/classes/view) instance and pass it the path to the modal view file:
+
+```xml
+<Button text="View details" tap="onTap" />
+```
+
+```ts
+onTap(args: EventData) {
+  const button = args.object as Button
+  button.showModal("details-page")
+}
+```
+
+## 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:
+
+```xml
+<Button text="Close" tap="onTap" />
+```
+
+```ts
+onTap(args: EventData) {
+  const button = args.object as Button
+  button.closeModal({
+    name: 'John Doe - EDITED',
+  })
+}
+```
+
+## Passing data to and from a modal
+
+Passing data can be done by passing a `context` in the `showModal` options parameter.
+
+```ts
+const options: ShowModalOptions = {
+  context: { name: 'John Doe' },
+  closeCallback(args: { name: string }) {
+    console.log('Modal closed', args.name)
+  },
+}
+// ...
+button.showModal('details-page', options)
+```
+
+To access the data in the modal, handle the `shownModally` event, and access it via `args.context`.
+
+```xml
+<Page shownModally="onShownModally">
+  <StackLayout>
+    <TextField text="{{ name }}" />
+    <Button text="Close" tap="onClose"/>
+  </StackLayout>
+</Page>
+```
+
+```ts
+import {
+  fromObject,
+  Page,
+  Button,
+  ShownModallyData,
+  EventData,
+} from '@nativescript/core'
+
+export function onShownModally(args: ShownModallyData) {
+  const page = args.object as Page
+  const context = fromObject({
+    ...args.context,
+    onClose(args: EventData) {
+      const button = args.object as Button
+      button.closeModal({
+        name: context.name, // 'John Doe - EDITED'
+      })
+    },
+  })
+  page.bindingContext = context
+}
+```

content/project-structure/src/fonts.md

@@ -8,7 +8,7 @@ A folder for storing custom fonts. Any `.ttf` files placed here are automaticall
 
 ## Using Custom Fonts
 
-Place the `.ttf` file(s) in the `src/fonts` folder, then run
+Place the `.ttf` files in the `src/fonts` folder, then run
 
 ```cli
 ns fonts

content/sidebar.ts

@@ -18,10 +18,10 @@ export default [
         text: 'Creating a Project',
         link: '/guide/creating-a-project',
       },
-      // {
-      //   text: 'Tutorials',
-      //   link: '/tutorials/',
-      // },
+      {
+        text: 'Using Modals',
+        link: '/guide/navigation/modals',
+      },
       {
         text: 'Troubleshooting',
         link: '/troubleshooting',
@@ -162,8 +162,4 @@ export default [
       },
     ],
   },
-  {
-    text: 'UI / Layout Containers',
-    items: [{ text: 'AbsoluteLayout', link: '/ui/absolute-layout' }],
-  },
 ] as NSSidebarGroup[]

content/tutorials/build-a-master-detail-app-with-angular.md

@@ -97,7 +97,7 @@ Let's start with creating the files for our home feature with the following cont
 
 <!-- tab:home.component.html -->
 
-```html
+```xml
 <!-- src/app/features/home/home.component.html -->
 ```
 
@@ -336,7 +336,7 @@ Next, let's break down the layout and UI elements of the home page.
 
 The home page can be divided into two main parts, the ActionBar with the title and the scrollable main content area with the cards (we will talk about the cards in the next section). Let's start with creating the ActionBar with the title. Open `home.component.html` and add the following code:
 
-```html
+```xml
 <!-- src/app/features/home/home.component.html -->
 
 <ActionBar title="NativeFlix"></ActionBar>
@@ -370,7 +370,7 @@ export class HomeComponent {
 
 Next, open your `home.component.html` and add the `ListView` component:
 
-```html{6-12}
+```xml{6-12}
 <!-- src/app/features/home/home.component.html -->
 
 <ActionBar title="NativeFlix"></ActionBar>
@@ -427,7 +427,7 @@ Before we dive into creating the card below, let's create some classes for our b
 
 As you can see in the image above, each card is made up of 3 components, the preview image, a title, and a description. We will be using a `GridLayout` as our container and use the `Image` and `Label` components for the preview image and texts. Open your `home.component.html` and add the following:
 
-```html{8-35}
+```xml{8-35}
 <!-- src/app/features/home/home.component.html -->
 
 <ActionBar title="NativeFlix"></ActionBar>
@@ -479,7 +479,7 @@ Let's start with creating the files for our details feature with the following c
 
 <!-- tab:details.component.html -->
 
-```html
+```xml
 <!-- src/app/features/details/details.component.html -->
 ```
 
@@ -610,7 +610,7 @@ export class HomeComponent {
 
 Next, let's add the tap event to the ListView items. Open `home.component.html` and add the following:
 
-```html{10}
+```xml{10}
 <!-- src/app/features/home/home.component.html -->
 
 <ActionBar title="NativeFlix"></ActionBar>
@@ -701,7 +701,7 @@ Let's break down the layout and UI elements of the details page.
 
 The details page can be divided into three main parts, the ActionBar with the flick title, the hero image, and the main content with the flick details. We will use the `details` array from our `flicks` object to populate the flick details section. The `details` array contains objects with a `title` and `body` which are rendered uniformly, each with their style. We can use Angular's `*ngFor` directive to loop through the array and create a UI element or set of elements for each entry in the array. Open `details.component.html` and add the following code:
 
-```html
+```xml
 <!-- src/app/features/details/details.component.html -->
 
 <!-- actionbar -->
@@ -710,25 +710,25 @@ The details page can be divided into three main parts, the ActionBar with the fl
 <ScrollView height="100%">
   <StackLayout>
     <!-- hero image -->
-    <image margin="0" stretch="aspectFill" [src]="flick?.image"></image>
+    <Image margin="0" stretch="aspectFill" [src]="flick?.image"></Image>
 
     <!-- main content -->
     <StackLayout padding="10 20">
       <ng-container *ngFor="let detail of flick?.details">
-        <label
+        <Label
           marginTop="15"
           fontSize="16"
           fontWeight="700"
           class="text-primary"
           textWrap="true"
           [text]="detail.title"
-        ></label>
-        <label
+        ></Label>
+        <Label
           fontSize="14"
           class="text-secondary"
           textWrap="true"
           [text]="detail.body"
-        ></label>
+        ></Label>
       </ng-container>
     </StackLayout>
   </StackLayout>

content/tutorials/build-a-master-detail-app-with-plain-javascript.md

@@ -522,7 +522,7 @@ Next, let's add the tap event to the ListView items. Open `home-page.xml` and ad
 
 ### Access navigation props
 
-We passed in the `id` of the flick card the user tapped on in the previous section as we navigate to the details page. We can access the passed in `id` via the page's `navigationContext`. We will first get the `navigationContext` on our details page and pass it along to our `DetailsViewModel`. We can then use the `id` to get the selected flick information to be displayed in our details component's template. Open `details-page.js` and add the following:
+We passed in the `id` of the flick card the user tapped on in the previous section as we navigate to the details page. We can access the passed-in `id` via the page's `navigationContext`. We will first get the `navigationContext` on our details page and pass it along to our `DetailsViewModel`. We can then use the `id` to get the selected flick information to be displayed in our details component's template. Open `details-page.js` and add the following:
 
 ```javascript{9}
 // app/details/details-page.js
@@ -547,7 +547,7 @@ import { FlickService } from '../services/flick.service'
 export class DetailsViewModel extends Observable {
   #flick
 
-  // the passed in context object during the navigation will be here
+  // the passed-in context object during the navigation will be here
   constructor(_context) {
     super()
 

content/tutorials/build-a-master-detail-app-with-plain-typescript.md

@@ -550,7 +550,7 @@ Next, let's add the tap event to the ListView items. Open `home-page.xml` and ad
 
 ### Access navigation props
 
-We passed in the `id` of the flick card the user tapped on in the previous section as we navigate to the details page. We can access the passed in `id` via the page's `navigationContext`. We will first get the `navigationContext` on our details page and pass it along to our `DetailsViewModel`. We can then use the `id` to get the selected flick information to be displayed in our details component's template. Open `details-page.ts` and add the following:
+We passed in the `id` of the flick card the user tapped on in the previous section as we navigate to the details page. We can access the passed-in `id` via the page's `navigationContext`. We will first get the `navigationContext` on our details page and pass it along to our `DetailsViewModel`. We can then use the `id` to get the selected flick information to be displayed in our details component's template. Open `details-page.ts` and add the following:
 
 ```typescript{9}
 // app/details/details-page.ts
@@ -578,7 +578,7 @@ import { FlickModel } from '../models'
 export class DetailsViewModel extends Observable {
   private _flick: FlickModel
 
-  // the passed in context object during the navigation will be here
+  // the passed-in context object during the navigation will be here
   constructor(private _context: { flickId: number }) {
     super()
 

content/tutorials/build-a-master-detail-app-with-react.md

@@ -732,7 +732,7 @@ export function HomeScreen({ navigation }: HomeScreenProps) {
 
 ### Access navigation props
 
-We passed in the `id` of the flick card the user tapped on in the previous section as we navigate to the details page. We can access the passed in `id` via the `route.params` property. We can then use the `id` to get the selected flick information to be displayed in our details component's template. Open `DetailsScreen.tsx` and add the following:
+We passed in the `id` of the flick card the user tapped on in the previous section as we navigate to the details page. We can access the passed-in `id` via the `route.params` property. We can then use the `id` to get the selected flick information to be displayed in our details component's template. Open `DetailsScreen.tsx` and add the following:
 
 ```tsx{9,17,19}
 // src/components/DetailsScreen.tsx