@lightningjs/blits 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+# v0.6.2
+
+_12 jan 2024_
+
+- Fixed issue with Sprites not working correctly due to missing background color
+
+# v0.6.1
+
+_8 jan 2024_
+
+- Fixed issue with using single quotes as Text content
+- Added first Text-to-Speech / Announcer functionality
+
 # v0.6.0
 
 _4 jan 2024_

package/boilerplate/package.json

@@ -31,6 +31,6 @@
     "vite": "^4.0.4"
   },
   "dependencies": {
-    "@lightningjs/blits": "^0.6.0"
+    "@lightningjs/blits": "^0.6.2"
   }
 }

package/docs/_sidebar.md

@@ -9,4 +9,5 @@
 - [Watching for changes](watchers.md)
 - [Styling and positioning Elements](element_attributes.md)
 - [Displaying images](displaying_images.md)
+- [Text-to-Speech / Announcer](text-to-speech-announcer.md)
 

package/docs/text-to-speech-announcer.md

@@ -0,0 +1,50 @@
+# Blits - Lightning 3 App Development Framework
+
+## Text-to-Speech / Announcer
+
+Blits comes with a built-in Text-to-Speech / Announcer functionality, to easily make your App more accessible. This is something that's often overlooked when developing an App, but having speech assistance integrated into your App is a huge deal for those users that are visually impaired.
+
+### Integrated with the router
+
+The Announcer in Blits is directly integrated with the router functionality. This means that through simple configuration, a descriptive message can be announced, when navigating from page to page, without the need for adding extra custom code.
+
+Just add an `announce` key in the configuration of your route, that contains the message you would like to be announced when visiting that route.
+
+```js
+const routes = [
+  // ...
+  {
+    path: '/settings',
+    component: Settings,
+    announce: "Welcome to the Settings page",
+  },
+  // ...
+]
+```
+
+## Custom announcement messages
+
+Furthermore it's possible to speak out custom messages anywhere in your App logic, for example when a component receives focus, as a reaction to user input, or to announce error messages when an remote API call
+fails.
+
+Each component in Blits has a `this.$announcer.speak()` available, which accepts `string` of a message to be announced.
+
+```js
+Blits.Component('MyComponent', {
+  // ...
+  hooks: {
+    focus() {
+      this.$announcer.speak('MyComponent just got focus')
+    }
+  },
+  keys: {
+    right() {
+      if(this.focused === this.items.length - 1) {
+        this.$announcer.speak('End of row reached')
+      } else {
+        //
+      }
+    }
+  }
+})
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.cjs",
   "exports": {

package/src/announcer/announcer.js

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2024 Comcast Cable Communications Management, LLC
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import speechSynthesis from './speechSynthesis.js'
+
+let debounce
+
+const speak = (message, politeness = 'off') => {
+  clearTimeout(debounce)
+  speechSynthesis.cancel()
+  // assertive messages get spoken immediately
+  if (politeness === 'assertive') {
+    speechSynthesis.speak({ value: message })
+  } else {
+    debounce = setTimeout(() => {
+      speechSynthesis.speak({ value: message })
+    }, 400)
+  }
+}
+
+const polite = (message) => speak(message, 'polite')
+
+const assertive = (message) => speak(message, 'assertive')
+
+const stop = () => {
+  speechSynthesis.cancel()
+}
+
+export default {
+  speak,
+  polite,
+  assertive,
+  stop,
+}

package/src/announcer/speechSynthesis.js

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2024 Comcast Cable Communications Management, LLC
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const syn = window.speechSynthesis
+
+const getUA = () => (window.navigator || {}).userAgent || ''
+const isAndroid = () => /android/i.test(getUA())
+
+let initialized = false
+let infinityTimer = null
+const clear = () => infinityTimer && clearTimeout(infinityTimer)
+
+const resumeInfinity = (target) => {
+  if (!target || infinityTimer) {
+    return clear()
+  }
+
+  syn.pause()
+  syn.resume()
+
+  infinityTimer = setTimeout(() => {
+    resumeInfinity(target)
+  }, 5000)
+}
+
+const utterProps = {
+  lang: 'en-US',
+  pitch: 1,
+  rate: 1,
+  voice: null,
+  volume: 1,
+}
+
+const initialize = () => {
+  utterProps.voice = syn.getVoices()[0]
+  initialized = true
+}
+
+const utterance = (scope, e) => {
+  const utter = new SpeechSynthesisUtterance(e.value)
+
+  // utter props
+  utter.lang = e.lang || utterProps.lang
+  utter.pitch = e.pitch || utterProps.pitch
+  utter.rate = e.rate || utterProps.rate
+  utter.voice = e.voice || utterProps.voice
+  utter.volume = e.volume || utterProps.volume
+
+  // utter events
+  utter.onstart = () => {
+    if (!isAndroid()) {
+      resumeInfinity(utter)
+    }
+    scope.onstart()
+  }
+
+  utter.onresume = () => {
+    if (!isAndroid()) {
+      resumeInfinity(utter)
+    }
+    scope.onresume()
+  }
+
+  utter.onpause = () => {
+    scope.onpause()
+  }
+  utter.onend = () => {
+    scope.onend()
+  }
+  utter.onerror = () => {
+    clear()
+    scope.onerror()
+  }
+  syn.speak(utter)
+}
+
+export default {
+  speak(e) {
+    if (!initialized) {
+      initialize()
+    }
+    this.cancel()
+    utterance(this, e)
+  },
+  resume() {
+    syn.resume()
+  },
+  pause() {
+    syn.pause()
+  },
+  cancel() {
+    syn.cancel()
+    clear()
+  },
+  getVoices() {
+    return syn.getVoices()
+  },
+  onend() {
+    //event placeholder
+  },
+  onerror() {
+    //event placeholder
+  },
+  onstart() {
+    //event placeholder
+  },
+  onresume() {
+    //event placeholder
+  },
+  onpause() {
+    //eventplaceholder
+  },
+}

package/src/application.d.ts

@@ -70,6 +70,19 @@ declare namespace Application {
 
   type RouteTransitionFunction = (previousRoute: Route, currentRoute: Route) => RequireAtLeastOne<RouteTransition>
 
+  interface RouteAnnounce {
+    /**
+     * Message to be announced
+     */
+    message: String,
+    /**
+     * Politeness level
+     *
+     * Defaults to 'off'
+     */
+    politeness?: 'off' | 'polite' | 'assertive'
+  }
+
   function Application(
     config: Application.ApplicationConfig
   ) : Application.ApplicationInstance
@@ -94,7 +107,14 @@ declare namespace Application {
     /**
      * Extra route options
      */
-    options?: object // todo: specify which options are available
+    options?: object // todo: specify which options are available,
+    /**
+     * Message to be announced when visiting the route (often used for accessibility purposes)
+     *
+     * Can be either a `String` with the message or an object that defines the message and the
+     * politeness level
+     */
+    announce?: String | RouteAnnounce
   }
 
   export interface ApplicationInstance extends ComponentInstance {}

package/src/components/Sprite.js

@@ -22,7 +22,7 @@ import symbols from '../lib/symbols.js'
 export default () =>
   Component('Sprite', {
     template: `
-      <Element w="$w" h="$h" :texture="$texture" />
+      <Element w="$w" h="$h" color="#fff" :texture="$texture" />
     `,
     props: ['image', 'map', 'frame', 'w', 'h'],
     state() {
@@ -32,6 +32,7 @@ export default () =>
     },
     computed: {
       texture() {
+        console.log('texture')
         const options =
           'frames' in this.map
             ? { ...(this.map.defaults || {}), ...this.map.frames[this.frame] }
@@ -50,6 +51,7 @@ export default () =>
     },
     hooks: {
       ready() {
+        console.log('sprite!')
         this.spriteTexture = this[symbols.renderer].createTexture('ImageTexture', {
           src: `${window.location.protocol}//${window.location.host}/${this.image}`,
         })

package/src/lib/codegenerator/generator.js

@@ -316,7 +316,8 @@ const cast = (val = '', key = false, component = 'component.') => {
     if (val.startsWith('$')) {
       castedValue = `${component}${val.replace('$', '')}`
     } else {
-      castedValue = `'${parseInlineContent(val, component)}'`
+      // unescaped single quotes must be escaped
+      castedValue = `'${parseInlineContent(val.replace(/(?<!\\)'/g, "\\'"), component)}'`
     }
   }
   // numeric

package/src/lib/setup/base.js

@@ -28,6 +28,7 @@ import { default as log, Log } from '../log.js'
 import symbols from '../symbols.js'
 
 import { trigger } from '../reactivity/effect.js'
+import Announcer from '../../announcer/announcer.js'
 
 const shaderAlias = {
   rounded: 'radius',
@@ -222,6 +223,12 @@ export default (component) => {
       enumerable: false,
       configurable: false,
     },
+    $announcer: {
+      value: Announcer,
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    },
   })
 }
 

package/src/router/router.js

@@ -21,6 +21,7 @@ import symbols from '../lib/symbols.js'
 import { Log } from '../lib/log.js'
 import Element from '../element.js'
 import Focus from '../focus.js'
+import Announcer from '../announcer/announcer.js'
 
 export let currentRoute
 export let navigating = false
@@ -55,7 +56,7 @@ export const navigate = async function () {
     const route = matchHash(hash, this.parent[symbols.routes])
 
     if (route) {
-      // add the previous route (tecnhically still the current route at this point)
+      // add the previous route (technically still the current route at this point)
       // into the history stack, unless navigating back or inHistory flag of route is false
       if (navigatingBack === false && previousRoute && previousRoute.options.inHistory === true) {
         history.push(previousRoute)
@@ -132,6 +133,16 @@ export const navigate = async function () {
         }
       }
 
+      // Announce route change if a message has been specified for this route
+      if (route.announce) {
+        if (typeof route.announce === 'string') {
+          route.announce = {
+            message: route.announce,
+          }
+        }
+        Announcer.speak(route.announce.message, route.announce.politeness)
+      }
+
       // focus the new view
       focus ? Focus.set(focus) : view.focus()
       this.activeView = this[symbols.children][this[symbols.children].length - 1]