@lightningjs/blits 1.7.1 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v1.8.1
+
+_29 oct 2024_
+
+- Fixed issue with array based props not triggering reactivity
+- Upgraded renderer to 2.5.1
+
+
+## v1.8.0
+
+_22 oct 2024_
+
+- Refactored TypeScript definitions to give better autocompletion and general TS support for business logic
+- Added option for custom characters in MSDF generated fonts
+- Added export for symbols
+- Upgraded renderer to 2.4.0
+- Added transition progress event
+
+
 ## v1.7.1
 
 _14 oct 2024_

package/docs/essentials/displaying_text.md

@@ -32,6 +32,40 @@ The Text-tag accepts the following attributes:
 - `contain` - the strategy for containing text within the bounds, can be `none` (default), `width`, or `both`. In most cases, the value of this attribute will automatically be set by Blits, based on the other specified attributes
 - `textoverflow` - the suffix to be added when text is cropped due to bounds limits, defaults to `...`
 
+## Text dimensions
+
+When you want to center your Text element, or properly position other Elements around your text, it is useful know the exact dimensions of your text.
+
+Similar to the Image element (i.e. an Element with a `src`), Text elements also accept the `@loaded` attribute. This event is called, as soon as the text is rendered, and passes in the dimensions of the generated text texture.
+
+The example below shows how to use the `@loaded`-attribute to position an Element as an underline, under a piece of text.
+
+```js
+export default Blits.Component('MyComponent', {
+  template: `
+    <Element>
+      <Text :content="$myText" @loaded="$textLoaded" />
+      <!-- gray underline -->
+      <Element :w="$w" h="2" y="$y" color="#333" />
+    </Element>
+  `,
+  props: ['myText'],
+  state() {
+    return {
+      w: 0,
+      y: 0,
+    }
+  },
+  methods: {
+    textLoaded(dimensions) {
+      console.log(`The text has a width of ${dimensions.w} and a height of ${dimensions.h}`)
+      // set the underline width to the exact width of the text
+      this.w = dimensions.w
+      // position the underline 8px below the text
+      this.y = dimensions.h + 8
+    }
+  }
+```
 
 ## SDF and Canvas2d
 
@@ -49,7 +83,7 @@ When you create a new Blits app using the available [getting started boilerplate
 
 But of course, you can also use any custom font that you want, to give your App the unique look and feel that fits with the design.
 
-Adding is custom font to a Blits App is quite straightforward. First, you'll need to place a `.ttf` version of your font in the `public` folder (i.e. `public/fonts/comic-sans.ttf`).
+Adding is custom font to a Blits App is quite straightforward. First, you'll need to place a `.ttf`, `.woff` or `.otf` version of your font in the `public` folder (i.e. `public/fonts/comic-sans.ttf`).
 
 Then you'll need to register the custom font in the Launch settings of your app (in `src/index.js`). The `fonts`-key in the settings is an `Array` that specifies all available fonts in your App.
 
@@ -73,3 +107,21 @@ From this moment on you'll be able to use the font `ComicSans` anywhere in your
 <Text font="ComicSans" content="I'm Comic Sans font!" />
 ```
 
+### Custom characters
+
+For MSDF font, a font atlas is created. By default this atlas includes all printable main ASCII characters. If you know before hand that you won't need certain characters, it would be more optimal to generate only those characters that are actually needed.
+
+Similarly, if you need characters outside of the default set, like accents or other special characters, then these will need to be included in the generated font atlas.
+
+In order to control which characters are generated for a specific font, you can add a _font config file_ per font inside the `assets/fonts` folder. Its name should match the name of the font file, like so: `myfont.config.json`.
+
+The config file should look something like this:
+
+```json
+{
+  "charset": "0123456789éåaü"
+}
+```
+With the configuration above, only numbers and the specified letters with accents will be generated (i.e. the default character set is overwritten).
+
+> Please note that only special characters and accents that are part of the original font can be added to the generated font atlas. Other characters will show up as a `?`.

package/docs/transitions_animations/transitions.md

@@ -104,7 +104,7 @@ Besides a reference to the `value`, you can also use dynamic values for the othe
 
 ## Listening to transition events
 
-Sometimes you may want to perform an action when a transition ends or when it starts.
+Sometimes you may want to perform an action when a transition _ends_ or when it _starts_.
 
 You can easily hook into these transition events by adding a `start` and `end` key to the transition object. Both values should be a function (or a reference to a `method` on your component).
 
@@ -128,3 +128,23 @@ export default Blits.Component('Gold', {
   }
 ```
 
+It is also possible to keep track of the entire progress of a transition. Every frametick during a transition (ideally once every 1.6ms), the renderer reports the progress of the transition. You can hook into this event by specifying a `progress` key on the transition configuration object, with a function to excute.
+
+This function is executed _every_ frametick, and receives the current progress and the previous progress as its arguments. The progress is indicated as a value between `0` and `1`, where 0 means start and 1 means finished.
+
+```js
+export default Blits.Component('Gold', {
+  template: `
+    <Element color="gold" w="100" h="100"
+      :x.transition="{value: $x, progress: $transitionProgress}"
+    />
+  `,
+  ///
+  methods: {
+    transitionprogress(progress, previousProgress) {
+      if(progress >= 0.5 && previousProgress < 0.5) {
+        // halfway through the transition
+      }
+    },
+  }
+```