feat: core 8.8 features (#148)

NathanWalker · web-flow · commit a97790ace8ae · 2024-07-11T08:38:29.000-07:00
diff --git a/content/configuration/nativescript.md b/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
 
diff --git a/content/guide/styling.md b/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.
diff --git a/content/guide/visionos.md b/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/
diff --git a/content/ui/image.md b/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
