@lightningjs/blits 0.5.10 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+# 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_
+
+- Added pre-compilation functionality to improve performance. Requires an update to the `vite.config.js` to enable. Read more details in this [blog post](https://lightningjs.io/blogs/blitsPreCompilation.html)
+- Added `defaultFont` to the Launch settings
+
 # v0.5.10
 
 _3 jan 2024_

package/boilerplate/package.json

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

package/boilerplate/vite.config.js

@@ -1,9 +1,9 @@
 import { defineConfig } from 'vite'
-import { importChunkUrl } from '@lightningjs/blits/vite'
+import blitsVitePlugins from '@lightningjs/blits/vite'
 
 export default defineConfig(({ command, mode, ssrBuild }) => {
   return {
-    plugins: [importChunkUrl()],
+    plugins: [...blitsVitePlugins],
     resolve: {
       mainFields: ['browser', 'module', 'jsnext:main', 'jsnext'],
     },

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.5.10",
+  "version": "0.6.1",
   "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/component.js

@@ -47,13 +47,11 @@ const required = (name) => {
 }
 
 const Component = (name = required('name'), config = required('config')) => {
-  let code = null
-
   const setupComponent = (lifecycle) => {
     // code generation
-    if (!code) {
+    if (!config.code) {
       Log.debug(`Generating code for ${name} component`)
-      code = codegenerator.call(config, parser(config.template))
+      config.code = codegenerator.call(config, parser(config.template))
     }
 
     setupBase(component)
@@ -167,7 +165,7 @@ const Component = (name = required('name'), config = required('config')) => {
     this.lifecycle.state = 'init'
 
     Object.defineProperty(this, symbols.children, {
-      value: code.render.apply(stage, [parentEl, this, code.context]),
+      value: config.code.render.apply(stage, [parentEl, this, config]),
       writable: false,
       enumerable: false,
       configurable: false,
@@ -180,9 +178,9 @@ const Component = (name = required('name'), config = required('config')) => {
       configurable: false,
     })
 
-    code.effects.forEach((eff) => {
+    config.code.effects.forEach((eff) => {
       effect(() => {
-        eff.apply(stage, [this, this[symbols.children], code.context])
+        eff.apply(stage, [this, this[symbols.children], config])
       })
     })
 

package/src/components/Text.js

@@ -16,6 +16,7 @@
  */
 
 import Component from '../component.js'
+import Settings from '../settings.js'
 
 export default () =>
   Component('Text', {
@@ -41,7 +42,7 @@ export default () =>
       'content',
       {
         key: 'font',
-        default: 'lato',
+        default: Settings.get('defaultFont', 'lato'),
       },
       {
         key: 'size',

package/src/launch.d.ts

@@ -90,6 +90,15 @@ export interface Settings {
    * Fonts to be used in the Application
    */
   fonts?: Font[],
+  /**
+   * Default font family to use in the Application when no font attribute is specified
+   * on a Text-component
+   *
+   * The default font must be registered in the `fonts` array in the settings.
+   *
+   * Defaults to `lato` font family
+   */
+  defaultFont?: string,
   /**
    * Custom keymapping
    */

package/src/lib/codegenerator/generator.js

@@ -92,8 +92,8 @@ const generateElementCode = function (
   if (options.holder === true) {
     renderCode.push(`
     if(typeof cmp${counter} !== 'undefined') {
-      for(key in cmp${counter}.config.props) {
-        delete elementConfig${counter}[cmp${counter}.config.props[key]]
+      for(let key in cmp${counter}.config.props) {
+        delete  elementConfig${counter}[cmp${counter}.config.props[key]]
       }
     }
     `)
@@ -171,7 +171,7 @@ const generateComponentCode = function (
 
   renderCode.push(`
     if(!${elm}) {
-      ${elm} = (context.components && context.components['${templateObject.type}'] || component[Symbol.for('components')]['${templateObject.type}'] || (() => { console.log('component ${templateObject.type} not found')})).call(null, {props: props${counter}}, ${parent}, component)
+      ${elm} = (context.components && context.components['${templateObject.type}'] || component[Symbol.for('components')]['${templateObject.type}'] || (() => { console.error('component ${templateObject.type} not found')})).call(null, {props: props${counter}}, ${parent}, component)
       if (${elm}[Symbol.for('slots')][0]) {
         parent = ${elm}[Symbol.for('slots')][0]
         component = ${elm}
@@ -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]

package/vite/index.js

@@ -1 +1,7 @@
+import preCompiler from './preCompiler.js'
+import { importChunkUrl } from '@lightningjs/vite-plugin-import-chunk-url'
+
 export { importChunkUrl as importChunkUrl } from '@lightningjs/vite-plugin-import-chunk-url'
+export { default as preCompiler } from './preCompiler.js'
+
+export default [importChunkUrl(), preCompiler()]

package/vite/preCompiler.js

@@ -0,0 +1,46 @@
+import parser from '../src/lib/templateparser/parser.js'
+import generator from '../src/lib/codegenerator/generator.js'
+
+export default function () {
+  let config
+  return {
+    name: 'preCompiler',
+    configResolved(resolvedConfig) {
+      config = resolvedConfig
+    },
+    transform(source) {
+      if (config.blits && config.blits.precompile === false) return source
+      if (source.indexOf('Blits.Component(') > -1 || source.indexOf('Blits.Application(') > -1) {
+        // get the start of the template key in de component configuration object
+        const templateKeyRegex = /template:\s*([`"'])*/g
+        const templateStartResult = templateKeyRegex.exec(source)
+        const typeOfQuotesUsed = templateStartResult[1]
+        const templateStartIndex = templateStartResult.index
+
+        // get the template contents from the configuration object
+        const templateContentsRegex = new RegExp(
+          `${typeOfQuotesUsed}([\\s\\S]*?)${typeOfQuotesUsed}`
+        )
+
+        const templateContentResult = templateContentsRegex.exec(source.slice(templateStartIndex))
+        const templateEndIndex =
+          templateStartIndex + templateContentResult.index + templateContentResult[0].length
+
+        // Parse the template
+        const parsed = parser(templateContentResult[1])
+
+        // Generate the code
+        const code = generator.call({ components: {} }, parsed)
+
+        // Insert the code in the component using the 'code' key, replacing the template key
+        const replacement = `code: { render: ${code.render.toString()}, effects: [${code.effects.map(
+          (fn) => fn.toString() + ','
+        )}], context: {}}`
+        const newSource =
+          source.substring(0, templateStartIndex) + replacement + source.substring(templateEndIndex)
+
+        return newSource
+      }
+    },
+  }
+}