feat: core 8.8 features (#148)

content/configuration/nativescript.md

@@ -107,7 +107,7 @@ Specifies the [webpack config](./webpack) location. The default is `webpack.conf
 projectName: string = 'projectName'
 ```
 
-Specifies the name of the project.  The default is the basename of the project directory.
+Specifies the name of the project. The default is the basename of the project directory.
 
 ### profiling
 

content/guide/styling.md

@@ -573,6 +573,141 @@ To allow for flexible styling and theming, NativeScript provides the following C
 In native modals in Angular, the classes are applied to the first layout view in your modal component's HTML. If you are targeting a class that is applied to the root layout in your modal, you would target it with `.ns-dark.your-class`.
 :::
 
+### Media Queries (8.8+)
+
+Media queries will allow you to apply CSS styles conditionally depending on a device's features or characteristics such as screen orientation, theme, or viewport width and height.
+
+NativeScript supports [Media Queries Level 3](https://www.w3.org/TR/mediaqueries-3) specification including the following features:
+
+- orientation
+- prefers-color-scheme (Even though this one is part of Media Queries Level 5, it was added along with current implementation to make theme styling possible)
+- width
+- height
+- device-width (same as width)
+- device-height (same as height)
+
+Viewport features like width and height support ranged values by using the `min-` or `max-` prefix.
+
+Here are few examples of how to declare media queries in NativeScript:
+
+```css
+@media only screen and (orientation: landscape) {
+ Label {
+ color: yellow;
+ font-size: 24;
+ }
+}
+
+@media only screen and (prefers-color-scheme: dark) {
+ Label {
+ background-color: #fff;
+ color: #000;
+ }
+}
+
+@media only screen and (max-width: 400) {
+ Label {
+ font-size: 10;
+ }
+}
+
+@media only screen and (min-height: 800) {
+ Page {
+ background-color: red;
+ }
+}
+```
+
+Just like style properties, length feature values (e.g. width) can also accept DIP or device pixel (px) units.
+
+#### The not operator
+
+The `not` operator is used to negate a media query, returning true if the query would otherwise return false.
+
+```css
+@media screen and not (orientation: portrait) {
+ Label {
+ color: yellow;
+ font-size: 24;
+ }
+}
+```
+
+#### Nested Media Queries
+
+```css
+@media only screen and (orientation: landscape) {
+ Label {
+ color: yellow;
+ font-size: 24;
+ }
+
+ @media only screen and (max-width: 400) {
+ Label {
+ font-size: 10;
+ }
+ }
+}
+```
+
+#### Nesting Keyframes inside Media Queries
+
+Apart from CSS selectors, keyframes can also be conditional using Media Queries.
+
+```css
+@keyframes slidein {
+ from {
+ background-color: yellow;
+ }
+
+ to {
+ background-color: pink;
+ }
+}
+
+/** This one will apply if condition is truthy **/
+@media only screen and (orientation: landscape) {
+ @keyframes slidein {
+ from {
+ background-color: red;
+ }
+
+ to {
+ background-color: green;
+ }
+ }
+}
+```
+
+#### matchMedia and conditional Navigation with Media Queries
+
+Sometimes, there's the need for an application to navigate to a completely different `Page` based on device screen size or orientation.
+Right now, that's possible using NativeScript's [Screen Size Qualifiers](https://old.docs.nativescript.org/ui/supporting-multiple-screens) API however it's limited to plain JS/TS apps and not available to the rest of JavaScript flavors.
+
+For various flavors, you can instead use [matchMedia()](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) providing many possibilities.
+
+The example below demonstrates how to navigate to an alternate `Page` if screen width is larger than 600 DIP:
+
+```ts
+const mql = matchMedia('only screen and (max-width: 600)')
+
+Frame.topmost().navigate({
+ // Navigate to another page if screen is too big
+ moduleName: mql.matches ? './pages/phone' : './pages/tablet',
+})
+```
+
+#### Using listeners to track Media Query changes
+
+The [matchMedia()](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) method returns a NativeScript [Observable](/core/observable#observable-api) instance, giving you the chance to track Media Query changes using event listeners.
+
+```ts
+const mql = matchMedia('only screen and (orientation: portrait)')
+mql.addEventListener('change', (event) => {
+ console.log('Is screen orientation still portrait? ' + event.matches)
+})
+```
+
 ## Supported Measurement Units
 
 NativeScript supports `DIPs` (Device Independent Pixels), `pixels` (via postfix px) and `percentages` (partial support for width, height and margin) as measurement units.

content/guide/visionos.md

@@ -315,7 +315,7 @@ You can follow along in these "Vision Pro 🥽 Hello World" tutorials:
 - [Develop Vision Pro 🥽 apps with Svelte](https://blog.nativescript.org/develop-visionos-apps-with-svelte)
 - [Develop Vision Pro 🥽 apps with Vue](https://blog.nativescript.org/develop-visionos-apps-with-vue)
 
-### Vision Pro for Angular Developers 
+### Vision Pro for Angular Developers
 
 This tutorial was hosted by [This Dot Media](https://www.youtube.com/@ThisDotMedia)
 
@@ -329,4 +329,4 @@ https://blog.nativescript.org/particles-and-multiple-scenes-vision-pro-developme
 
 ### How to add visionOS to an existing app?
 
-https://blog.nativescript.org/add-visionos-to-existing-nativescript-app/
+https://blog.nativescript.org/add-visionos-to-existing-nativescript-app/

content/ui/image.md

@@ -81,6 +81,81 @@ Font symbols can be rendered as an image by prefixing the source with `font://`
 }
 ```
 
+### Using SF Symbols on iOS (8.8+)
+
+Images can also be used to display [SF Symbols](https://developer.apple.com/sf-symbols/) on iOS by using the `sys://` prefix along with the symbol name. These also support `iosSymbolEffect` for animated effects as well as `iosSymbolScale` with a possible value of `small|medium|large`;
+
+```html
+<GridLayout rows="auto,auto" columns="*,*">
+ <image
+ src="sys://photo.on.rectangle.angled"
+ tintColor="green"
+ [iosSymbolEffect]="symbolBounceEffect"
+ />
+
+ <image
+ col="1"
+ src="sys://photo.on.rectangle.angled"
+ tintColor="green"
+ [iosSymbolEffect]="symbolBounceEffect"
+ iosSymbolScale="small"
+ />
+
+ <image
+ row="1"
+ src="sys://photo.on.rectangle.angled"
+ tintColor="green"
+ [iosSymbolEffect]="symbolBounceEffect"
+ iosSymbolScale="medium"
+ />
+
+ <image
+ row="1"
+ col="1"
+ src="sys://photo.on.rectangle.angled"
+ tintColor="green"
+ [iosSymbolEffect]="symbolBounceEffect"
+ iosSymbolScale="large"
+ />
+</GridLayout>
+```
+
+```ts
+import { ImageSymbolEffects } from '@nativescript/core'
+
+const symbolBounceEffect = ImageSymbolEffects.Bounce
+```
+
+<iframe style="width: 100%; min-height: 200px; aspect-ratio: 16 / 9;" src="https://www.youtube.com/embed/y_ULvYe5mTA" title="SF Symbol usage with NativeScript" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+
+This demonstrates using various built-in presets for effects and also using the `iosSymbolScale` property which is useful when you apply affects so the animation doesn't exceed the bounds of it's Image container (_as can be seen in the top left usage in the video_).
+
+#### Custom Symbol Effects
+
+You can also create custom effects using the full expansive iOS symbol API, for example:
+
+```ts
+import { ImageSymbolEffect } from '@nativescript/core'
+
+const effect = new ImageSymbolEffect(NSSymbolBounceEffect.effect())
+effect.options =
+ NSSymbolEffectOptions.optionsWithSpeed(2).optionsWithRepeatCount(6)
+effect.completion = (context) => {
+ console.log('effect completed!', context)
+}
+const customSymbolEffect = effect
+```
+
+```html
+<image
+ src="sys://heart.fill"
+ tintColor="red"
+ [iosSymbolEffect]="customSymbolEffect"
+/>
+```
+
+<iframe style="width: 100%; min-height: 200px; aspect-ratio: 16 / 9;" src="https://www.youtube.com/embed/IuyGBoqJNKo" title="SF Symbol custom effects with NativeScript" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+
 ## Props
 
 ### src
@@ -125,6 +200,58 @@ Gets or sets the way the image is resized to fill its allocated space.
 
 See [`ImageStretchType`](/api/namespace/CoreTypes#imagestretchtype)
 
+### iosSymbolEffect (8.8+)
+
+```ts
+iosSymbolEffect: ImageSymbolEffect | ImageSymbolEffects
+```
+
+Gets or sets the effect of the SF Symbol. You can create your own custom `ImageSymbolEffect` or use presets defined from `ImageSymbolEffects`, for example:
+
+```ts
+export enum ImageSymbolEffects {
+ Appear = 'appear',
+ AppearUp = 'appearUp',
+ AppearDown = 'appearDown',
+ Bounce = 'bounce',
+ BounceUp = 'bounceUp',
+ BounceDown = 'bounceDown',
+ Disappear = 'disappear',
+ DisappearDown = 'disappearDown',
+ DisappearUp = 'disappearUp',
+ Pulse = 'pulse',
+ Scale = 'scale',
+ ScaleDown = 'scaleDown',
+ ScaleUp = 'scaleUp',
+ VariableColor = 'variableColor',
+ Breathe = 'breathe',
+ BreathePlain = 'breathePlain',
+ BreathePulse = 'breathePulse',
+ Rotate = 'rotate',
+ RotateClockwise = 'rotateClockwise',
+ RotateCounterClockwise = 'rotateCounterClockwise',
+ Wiggle = 'wiggle',
+ WiggleBackward = 'wiggleBackward',
+ WiggleClockwise = 'wiggleClockwise',
+ WiggleCounterClockwise = 'wiggleCounterClockwise',
+ WiggleDown = 'wiggleDown',
+ WiggleForward = 'wiggleForward',
+ WiggleUp = 'wiggleUp',
+ WiggleLeft = 'wiggleLeft',
+ WiggleRight = 'wiggleRight',
+}
+```
+
+Keep in mind that some are only iOS 17 or 18 and above.
+
+### iosSymbolScale (8.8+)
+
+```ts
+iosSymbolScale: number
+```
+
+Gets or sets the scale of the SF Symbol.
+
 ### loadMode
 
 ```ts