diff --git a/README.md b/README.md index 9af8dca7..716a313a 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ You may be wondering where the name Blits comes from? Firstly, it's short, memorable and just has a nice ring to it. -"Blits" is a Dutch word (a significant portion of the Lightning Open Source teams is based in the Netherlands). It means _flashy_ and it's often used to for things that are _great_ or _cool_. +"Blits" is a Dutch word (a significant portion of the Lightning Open Source team is based in the Netherlands). It means _flashy_ and it's often used for things that are _great_ or _cool_. Finally it's a nerdy reference to the computer term "Bit Blits" commonly used in graphics processing, for rapidly moving a block of data into memory - quite similar to what Lightning is doing 🙂 diff --git a/docs/README.md b/docs/README.md index e83ab480..aeedbbe4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,6 @@ You may be wondering where the name Blits comes from? Firstly, it's short, memorable and just has a nice ring to it. -"Blits" is a Dutch word (a significant portion of the Lightning Open Source teams is based in the Netherlands). It means _flashy_ and it's often used to for things that are _great_ or _cool_. +"Blits" is a Dutch word (a significant portion of the Lightning Open Source team is based in the Netherlands). It means _flashy_ and it's often used for things that are _great_ or _cool_. Finally it's a nerdy reference to the computer term "Bit Blits" commonly used in graphics processing, for rapidly moving a block of data into memory - quite similar to what Lightning is doing 🙂 - diff --git a/docs/built-in/directives.md b/docs/built-in/directives.md index 597f4436..48a2f721 100644 --- a/docs/built-in/directives.md +++ b/docs/built-in/directives.md @@ -41,7 +41,7 @@ At the moment it's not possible to use the `is`-attribute as a _reactive_ attrib The declarative coding style that is promoted in Blits components, should generally remove the need to directly interact with individual Elements or Components in your template. However, in some cases you may need to reference them directly. For example, in order to delegate the focus. -For this use case, you can specify a `ref`-attribute on Elements (or Components). And by using the helper function `this.select()`, which is vailable on every Blits component, you can gain access to the child Element or Component inside your business logic. +For this use case, you can specify a `ref`-attribute on Elements (or Components). And by using the helper function `this.select()`, which is available on every Blits component, you can gain access to the child Element or Component inside your business logic. The `select()`-function accepts the `ref`-value that you are looking for as a single argument, and returns the Element or Component if found. diff --git a/docs/built-in/for-loop.md b/docs/built-in/for-loop.md index 22156746..e50e2704 100644 --- a/docs/built-in/for-loop.md +++ b/docs/built-in/for-loop.md @@ -1,10 +1,10 @@ # For loop -The for loop is technically also a [directive](../directives.md), but such an important one that it deserves it's own section. +The for loop is technically also a [directive](../directives.md), but such an important one that it deserves its own section. The for loop directive can be used when you want to repeat multiple instances of an Element or a Component, without having to specify them hardcoded one by one in your template. -The for loop take an `Array` of data, loops over it and for each Array-item an Element or Component is created. The `Array` can be a fixed one, but it' can also dynamically be filled or modified and have it's changes reflect in the rendered result. +The for loop takes an `Array` of data, loops over it and for each Array-item an Element or Component is created. The `Array` can be a fixed one, but it can also dynamically be filled or modified and have it's changes reflect in the rendered result. > Important: the for loop is a powerful and often used directive. Within Blits it's optimized to be as performant as possible. But if used incorrectly, it can be the cause of slow performance. So please read carefully through this entire section. @@ -33,9 +33,9 @@ The example above will generate 3 _lime green_ elements, based on the array of ` ## Using the index -In order to fix the example above and make all 3 elements visible, we can use the `index` of the Array, to position each item correctly. +In order to fix the example above and make all 3 elements visible, we can use the `index` of the Array to position each item correctly. -All we need to do is declare the `index` in the `for`-directive and subsequently use it in the the `x`-attribute, with a simple calculation. +All we need to do is declare the `index` in the `for`-directive and subsequently use it in the `x`-attribute, with a simple calculation. You may choose any name for the `index` variable (like `i` or `forIndex`). This may be useful when you already have the `index`-key specified as a `state` or `prop` variable on your component, causing a conflict. @@ -95,13 +95,13 @@ export default Blits.Component('ForLoop', { }) ``` -This will generate 3 squares aligned next to each other, each with a differrent color and they will use the _alpha_ specific in the Component state. +This will generate 3 squares aligned next to each other, each with a different color and they will use the _alpha_ specific in the Component state. ## The importance of using the key attribute The examples above have demonstrated the basic usage of the for-loop. But they are all missing one _very important_ ingredient to make sure that for-loops that are subject to change, continue to perform well. Meet the `key`-attribute. -For perfomance reasons, it is essential to be able track the _identity_ of an Element or Component, whenever changes are made to the Array in the for loop. +For performance reasons, it is essential to be able track the _identity_ of an Element or Component, whenever changes are made to the Array in the for loop. Think of _identity_ as the field that makes an item in the Array unique, such as an `id` or a `hash`. It's basically the thing that allows you to distinguish between the poster of _The Matrix_ and the poster of _Frozen 2_, for example. @@ -109,7 +109,7 @@ Providing this information, allows the for-loop to decide whether it should _upd Correctly using the `key`-attribute enables Blits to _reuse_ existing instances whenever possible - which obviously is good for performance. -It's important that the `key`-attribute is _unique_ for each Array item. Also beware that we can't rely on the `index` parameter provided in for loop, because that only indentifies the position in the Array, and not the actual item itself. +It's important that the `key`-attribute is _unique_ for each Array item. Also beware that we can't rely on the `index` parameter provided in for loop, because that only identifies the position in the Array, and not the actual item itself. ```js @@ -156,7 +156,7 @@ export default Blits.Component('ForLoop', { In the example above we have added the `key`-attribute in the template. Now whenever we push a new item to the `items`-array, the for-loop will reuse the Elements previously created and only instantiate a new Element for the newly added item. -If we would ommit the `key`-attribute, then whenever we push a new item to the Array, the for-loop would dispose all the old Elements and create new instances for _each_ item in the array. +If we would omit the `key`-attribute, then whenever we push a new item to the Array, the for-loop would dispose all the old Elements and create new instances for _each_ item in the array. ## Referencing elements in the for loop diff --git a/docs/built-in/layout.md b/docs/built-in/layout.md index 36ad6e8e..9a1403d1 100644 --- a/docs/built-in/layout.md +++ b/docs/built-in/layout.md @@ -1,22 +1,22 @@ # Layout -A big portion of building a pixel perfect App is all about correctly positioning Elements and Components on screen. In Lightning and Blits _absolute_ positions are used. This fits the whole concept of building a TV app where the viewport dimensions are known and fixed. Absolute positioning (versus spacing Elements relative to each other) is also more performant. +A big portion of building a pixel-perfect App is all about correctly positioning Elements and Components on the screen. In Lightning and Blits, _absolute_ positions are used. This fits the whole concept of building a TV app where the viewport dimensions are known and fixed. Absolute positioning (versus spacing Elements relative to each other) is also more performant. -Imagine a complex design with several nested layers. Relying solely on _relative_ positioning and elements automatically floating as space is available, may lead to heavy and recursive calculations. Then throw some dynamically changing dimensions and animations in the mix as well, and your App may be starting to noticeably drop frames due to expensive re-calculations. +Imagine a complex design with several nested layers. Relying solely on _relative_ positioning and elements automatically floating as space is available may lead to heavy and recursive calculations. Then throw some dynamically changing dimensions and animations in the mix as well, and your App may be starting to noticeably drop frames due to expensive re-calculations. That being said, there are often cases where it becomes very cumbersome to calculate all the positions manually. Especially when dimensions are not known in advance and elements may load asynchronously. If you come from a CSS background, you may be tempted to say: "_this is why we have Flexbox!_". And while Flexbox is great and versatile in CSS and running on a powerful device, a full flexbox implementation does come at a cost and the risk of slowing down your App, when applied extensively or incorrectly. -In order to address the core problem "_how do I easily position a bunch of Elements and Components, without writing a lot of code with `@loaded` event handlers_", Blits offers the built-in ``-component - a basic and performant solution that automatically puts your Elements in the right place. +In order to address the core problem of "_how do I easily position a bunch of Elements and Components without writing a lot of code with `@loaded` event handlers_", Blits offers the built-in `` component - a basic and performant solution that automatically puts your Elements in the right place. ## How to use -Since the Layout-component is a built-in component, there is no need to register it separately. You can use the ``-tag anywhere in your templates, just as you would use `` and ``. +Since the Layout component is a built-in component, there is no need to register it separately. You can use the `` tag anywhere in your templates, just as you would use `` and ``. -The Layout component is a wrapper component, that encloses a number of children. All the direct children that are wrapped in a ``-tag are automatically positioned in order, one next to the other. +The Layout component is a wrapper component that encloses a number of children. All direct children wrapped in a `` tag are automatically positioned in order, one next to the other. -Whenever the dimensions of a child change, the positioning of the next children is automatically recalculated and re-applied. +Whenever dimensions of a child change, the positioning of the next children is automatically recalculated and reapplied. ```xml @@ -29,31 +29,31 @@ Whenever the dimensions of a child change, the positioning of the next children ### Horizontal and vertical layout -By default the Layout component lays out it's contents _horizontally_. The Layout component accepts a `direction` attribute which allows you to control the direction. +By default, the Layout component lays out its contents _horizontally_. The Layout component accepts a `direction` attribute that allows you to control the direction. -In order to align vertically use ``. And use `` to explicitly apply the default horizontal layout. +In order to align vertically, use ``. And use `` to explicitly apply the default horizontal layout. ### Spacing between children -By default the Layout-component places each Element directly besides (or below) the previous one. By adding the `gap`-attribute you can control how much space will be added between each Element or Component. The `gap`-attribute accepts a number in pixels. +By default, the Layout-component places each Element directly besides (or below) the previous one. By adding the `gap`-attribute, you can control how much space will be added between each Element or Component. The `gap`-attribute accepts a number in pixels. ### Aligning items -The layout component positions its children based on the provided direction (`horizontal` or `vertical`). With the `align-items`-attribute you can specify how to align the children on the opposite axis: +The layout component positions its children based on the provided direction (`horizontal` or `vertical`). With the `align-items`-attribute, you can specify how to align the children on the opposite axis: -- `start` (the default value) - aligns the children in the _top_ for horizontal layouts, and on the _left_ for vertical layouts +- `start` (the default value) - aligns the children at the _top_ for horizontal layouts and on the _left_ for vertical layouts - `center` - align the children in the center - `end` - aligns the children in the _bottom_ for horizontal layouts, and on the _right_ for vertical layouts ### Dynamic dimensions -For the Layout component to work properly, the direct children all need to have dimensions (i.e `w` and `h` attributes). The exception here being Text elements. +For the Layout component to work properly, all direct children need to have dimensions (i.e., `w` and `h` attributes). The exception here being Text elements. -Due to the asynchronous nature of rendering text, the final text dimensions are not known beforehand. The width and height of Text elements are automatically set when the text has been loaded. This fires a `@loaded` event, that you can tap into as described [here](../essentials/displaying_text#text-dimensions). +Due to the asynchronous nature of rendering text, the final text dimensions are not known beforehand. The width and height of Text elements are automatically set when the text has been loaded. This fires a `@loaded` event that you can tap into as described [here](../essentials/displaying_text#text-dimensions). -The Layout component also uses this event, to execute its calculation and position the text and other elements around it properly. +The Layout component also uses this event to execute its calculation and properly position the text and other elements around it. -When the children of the Layout-component have _reactive_ dimensions (i.e. `), the Layout component ensures that all child elements are properly re-positioned whenever a dimension changes. +When the children of the Layout-component have _reactive_ dimensions (i.e., ``), the Layout component ensures that all child elements are properly repositioned whenever a dimension changes. ### Components inside a Layout @@ -85,11 +85,11 @@ export default Blits.Component('MyButton', { } }) ``` -At this moment Blits does not have support for automatically growing the dimensions of a Component based on it's contents, because of the performance impact that this functionality has. +At this moment, Blits does not support automatically growing a Component's dimensions based on its contents due to the performance impact of this functionality. ### Nesting Layouts -It's also possible to nest layouts. Simply place a new ``-tag, with it's own children in between the children of another Layout-component. The Layout-component itself will grow automatically with the dimensions of it's children. In other words, it's not required to specify a width (`w`) or height (`h`) on the ``-tag itself. +It's also possible to nest layouts. Simply place a new ``-tag, with it's own children in between the children of another Layout-component. The Layout component itself will grow automatically with the dimensions of its children. In other words, it's not required to specify a width (`w`) or height (`h`) on the `` tag itself. And of course you can nest _vertical_ Layouts inside a _horizontal_ one - and vice versa. @@ -123,7 +123,7 @@ The ``-component can also take into account when dimensions of children ### Updated event -The ``-tag automatically updates its dimensions based on the dimensions of its children. After each update in the children, the an `updated`-event is emitted on the ``-tag. It will receive the current dimensions of the layout. +The ``-tag automatically updates its dimensions based on the dimensions of its children. After each update in the children, an `updated`-event is emitted on the ``-tag. It will receive the current dimensions of the layout. You can tap into this event by adding an `@updated`-attribute to the ``-tag and refer to a method in your Component logic. @@ -151,18 +151,18 @@ export default Blits.Component('LayoutUpdate', { ## Performance -The Layout-component is a very useful utility, that will make it a lot easier to put together complex layouts. It will reduce the code required, it means less hardcoding of values and removes the need to manually wire up `@loaded` events when working with dynamic / asynchronous elements. +The Layout component is a very useful utility that will make it a lot easier to put together complex layouts. It will reduce the code required, it means less hardcoding of values and removes the need to manually wire up `@loaded` events when working with dynamic / asynchronous elements. -We've done our best to make the Component as performant as possible, by deliberately keeping it simple and straight forward. But it's important to understand that the Layout component does come at a cost. Depending on the use case these costs may be negligible, but there are cases where the Layout component might prove to be a bottle-neck. +We have done our best to make the Component as performant as possible by deliberately keeping it simple and straightforward. However, it is important to understand that the Layout component does come at a cost. Depending on the use case these costs may be negligible, but there are cases where the Layout component might prove to be a bottleneck. -The performance costs may always be there to some degree. Whether it's the Layout component that does the complex calculations, or you do it in your custom code. So please feel encouraged to use the ``-tag! +The performance costs may always be there to some degree. Whether it's the Layout component that does the complex calculations, or you do it in your custom code. So, please feel encouraged to use the `` tag! Some pointers to keep in mind, though: - Every change in the dimensions of a child, triggers the Layout component to recalculate and reposition. If your child elements change frequently, the Layout component may have a performance impact. -- The Layout component support transitions, but beware that when transitioning child dimensions a recalculation happens every frame-tick. If you see frame-drops in your App, you may want to see if the ``-tag has an impact on this. +- The Layout component support transitions, but beware that when transitioning child dimensions a recalculation happens every frame tick. If you see frame-drops in your App, you may want to see if the ``-tag has an impact on this. - Be mindful to not apply unnecessary deep nesting of Layout tags. Each change in a deep child, will trigger recalculations up the tree of Layout tags. -- When using the ``-tag with a for-loop, it may be more performant to use the `$index` of the for-loop and manually position the elements yourself (i.e. ``). Especially if the dimensions are know before hand and possibly are the same for each child. +- When using the ``-tag with a for-loop, it may be more performant to use the `$index` of the for-loop and manually position the elements yourself (i.e. ``). Especially if the dimensions are known beforehand and possibly are the same for each child. diff --git a/docs/components/user_input.md b/docs/components/user_input.md index 75c6447f..8d1ba2eb 100644 --- a/docs/components/user_input.md +++ b/docs/components/user_input.md @@ -86,15 +86,15 @@ The `intercept`-method can also be an asynchronous method. The functions specified in the `input` configuration are invoked when a key is _pressed down_ (i.e. the `keydown` event listener). But sometimes you may also want to execute some logic when a key is _released_ (i.e. the `keyup` event listener). -Instead of introducing a separate key on the Component configuration object for key release callbacks, Blits relies on the concept that a `keyup` event is always preceeded by a `keydown` event. +Instead of introducing a separate key on the Component configuration object for key release callbacks, Blits relies on the concept that a `keyup` event is always preceded by a `keydown` event. Following this logic, whenever you return a function in an input (key down) handler, this function will be executed upon release (i.e. the `keyup` event) of that key . -When an input key is being a hold down, it will execute the key down handler multipe times. Upon key release, only the last returned key up callback function will be executed. +When an input key is being a hold down, it will execute the key down handler multiple times. Upon key release, only the last returned key up callback function will be executed. ```javascript -Blits.Component('MyComponemnt', { +Blits.Component('MyComponent', { // input: { enter() { diff --git a/docs/components/utility_methods.md b/docs/components/utility_methods.md index 05a1fb1c..62d61316 100644 --- a/docs/components/utility_methods.md +++ b/docs/components/utility_methods.md @@ -267,13 +267,13 @@ export default Blits.Component('MyComponent', { Timeouts are a great way to execute recurring logic, such as polling for updates or periodically updating an animation. -But simular to timeouts, intervals (more specifically failing to clear them) are a common source of memory leaks - maybe even more than dangling timeouts. +But similar to timeouts, intervals (more specifically failing to clear them) are a common source of memory leaks - maybe even more than dangling timeouts. For this reason Blits has 3 built-in utility methods to help registering and clearing intervals. ### $setInterval -The `this.$setInterval()`-method create an interval, using a thin wrapper around the `window.setInterval()` method. The first argument is the `callback` to be executed after each interval `delay` specified in the second argument. The method returns an `interval id`, which can be used to mannually clear the interval. +The `this.$setInterval()`-method create an interval, using a thin wrapper around the `window.setInterval()` method. The first argument is the `callback` to be executed after each interval `delay` specified in the second argument. The method returns an `interval id`, which can be used to manually clear the interval. ### $clearInterval @@ -287,18 +287,22 @@ The `this.$clearIntervals()`-method is a utility method that is used to clear al ```js export default Blits.Component('MyComponent', { state() { - interval: null, - secondCount: 0, - minuteCount: 0, + return { + interval: null, + secondCount: 0, + minuteCount: 0, + } }, hooks: { init() { this.interval = this.$setInterval(() => { - console.log(`${secondCount} second(s) have passed`) + this.secondCount++ + console.log(`${this.secondCount} second(s) have passed`) }, 1000) this.$setInterval(() => { - console.log(`${minuteCount} minute(s) have passed`) + this.minuteCount++ + console.log(`${this.minuteCount} minute(s) have passed`) }, 60000) }, unfocus() { diff --git a/docs/essentials/displaying_images.md b/docs/essentials/displaying_images.md index e2133671..4ca835f4 100644 --- a/docs/essentials/displaying_images.md +++ b/docs/essentials/displaying_images.md @@ -2,7 +2,7 @@ Now that we've covered the basics of creating Elements, as well as styling and positioning them, it's time to move away from these boring rectangles and explore how you can incorporate _images_ into your App. -In Blits is very easy to display an image. Simply add the `src` attribute to an Element, specifying the image's location. +In Blits, it is very easy to display an image. Simply add the `src` attribute to an Element, specifying the image's location. For local images, make sure to place them in the `public` folder of your App (e.g., `public/assets/background.jpg` or `public/images/logo.png`) and refer to them with a _relative_ path (but omitting the `public` folder as root). @@ -15,7 +15,7 @@ Remote images are also supported and can be linked directly (e.g., `http://mycdn ## Sizing and Scaling -Make sure to give your Element a width (`w` ) and a height (`h`) attribute. Images will _not_ be rendered if they don't have both attributes present. The Lightning renderer will scale the image to fit these exact dimensions +Make sure to give your Element a width (`w` ) and a height (`h`) attribute. Images will _not_ be rendered if they don't have both attributes present. The Lightning renderer will scale the image to fit these exact dimensions. For the best performance, it's important to keep your source images as small as possible. If you're displaying an image at `200px x 200px`, make sure the image is exactly that size or _smaller_. The latter option may lead to some quality loss, but can positively impact the overall performance of your App. @@ -38,7 +38,7 @@ By default, all Elements with a `src` attribute get a solid white background, wi All images are loaded asynchronously (and can possibly fail to load), even those local to your App. Blits allows you to easily hook into the `loaded` and `error` events of image Elements. -You can use this, for example, to only make something visible once an image is fully loaded. Or to display a fallback image when an remote image can't be retrieved. +You can use this, for example, to only make something visible once an image is fully loaded. Or to display a fallback image when a remote image can't be retrieved. ```xml diff --git a/docs/essentials/displaying_text.md b/docs/essentials/displaying_text.md index 353ea472..b6c4a2b3 100644 --- a/docs/essentials/displaying_text.md +++ b/docs/essentials/displaying_text.md @@ -34,7 +34,7 @@ The Text-tag accepts the following attributes: ## 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. +When you want to center your Text element, or properly position other Elements around your text, it is useful to 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. @@ -91,7 +91,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`, `.woff` or `.otf` version of your font in the `public` folder (i.e. `public/fonts/comic-sans.ttf`). +Adding a 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. @@ -117,7 +117,7 @@ From this moment on you'll be able to use the font `ComicSans` anywhere in your ### 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. +For MSDF font, a font atlas is created. By default this atlas includes all printable main ASCII characters. If you know beforehand 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. diff --git a/docs/essentials/element_attributes.md b/docs/essentials/element_attributes.md index 27d685f1..d5108f9c 100644 --- a/docs/essentials/element_attributes.md +++ b/docs/essentials/element_attributes.md @@ -43,9 +43,9 @@ In addition to the absolute positions that Blits and Lightning use, there are a On the `x`-axis the following _placement_ options can be used: `left` (default), `center` and `right`. On the `y`-axis the _placement_ attribute accepts `top` (default), `middle` and `bottom`. -The _placement_ attribute also accepts and object with an `x` and a `y` key, to specify a placement for both axes. +The _placement_ attribute also accepts an object with an `x` and a `y` key, to specify a placement for both axes. -The placement of an Element is calculated based on the dimensions of it's direct parent. This means that the containing Element _must_ have it's own dimensions (i.e. a `w` and a `h` attribute). +The placement of an Element is calculated based on the dimensions of its direct parent. This means that the containing Element _must_ have its own dimensions (i.e. a `w` and a `h` attribute). ```xml @@ -190,6 +190,6 @@ In the case where the `x` and `y` values are the same, you can also just supply By default contents inside an Element (i.e. child Elements) will overflow the boundaries of the parent, even when you give the parent Element fixed dimensions. -In order to contain / cut off the content inside an Elements' `w` and `h`, you can add the `clipping="true"`-attribute. Setting `clipping` to `false` restores the default behaviour of content overflowing. +In order to contain / cut off the content inside an Element's `w` and `h`, you can add the `clipping="true"`-attribute. Setting `clipping` to `false` restores the default behaviour of content overflowing. Alternatively you can also use the `overflow`-attribute (and pass it `true` or `false`), which works similar to clipping just mapped inversly (i.e. `overflow="false"` ensures content that surpasses the parent dimensions is clipped-off). diff --git a/docs/essentials/template_syntax.md b/docs/essentials/template_syntax.md index 98548781..5f0e689a 100644 --- a/docs/essentials/template_syntax.md +++ b/docs/essentials/template_syntax.md @@ -4,7 +4,7 @@ Blits uses an easy-to-read _XML-style_ template syntax. The syntax is inspired b The `template` key in the _Component configuration object_ is used to specify a string with this XML-like template structure. Templates can often span multiple lines. In those cases, it's advisable to use `template literals` (enclosed by backticks). -Similar to HTML you can use arguments and nested tags. Self-closing tags and HTML-style comments are also supported in Blits templates. +Similar to HTML, you can use arguments and nested tags. Self-closing tags and HTML-style comments are also supported in Blits templates. The default tag that can be used in templates is the `` tag. The Element tag corresponds to a node in the Lightning 3 renderer. diff --git a/docs/getting_started/intro.md b/docs/getting_started/intro.md index c828abad..5ca7b856 100644 --- a/docs/getting_started/intro.md +++ b/docs/getting_started/intro.md @@ -14,7 +14,7 @@ You may be wondering where the name Blits comes from. Firstly, it's short, memorable and just has a nice ring to it. -"Blits" is a Dutch word (a significant portion of the Lightning Open Source teams is based in the Netherlands). It means _flashy_ and it's often used for things that are _great_ or _cool_. +"Blits" is a Dutch word (a significant portion of the Lightning Open Source team is based in the Netherlands). It means _flashy_ and it's often used for things that are _great_ or _cool_. Finally, it's a nerdy reference to the computer term "Bit Blits" commonly used in graphics processing, for rapidly moving a block of data into memory - quite similar to what Lightning is doing 🙂 diff --git a/docs/plugins/global_app_state.md b/docs/plugins/global_app_state.md index ee0d370e..f3c30b04 100644 --- a/docs/plugins/global_app_state.md +++ b/docs/plugins/global_app_state.md @@ -44,7 +44,7 @@ Blits.Launch(App, 'app', { ### State object -When registering the Global App State plugin, you pass it a state object as the second argument. This is a plain object literal that will be converted into a _reactive_ object, and is used to keep track the global state variables. +When registering the Global App State plugin, you pass it a state object as the second argument. This is a plain object literal that will be converted into a _reactive_ object, and is used to keep track of the global state variables. The newly created Global App state works exactly the same as an internal Component state. You can read values and you can directly change values. And when you do change a value, it automatically triggers reactive updates. Either via reactive attributes in the template, or in the form of watchers / computed values in the Component logic. @@ -77,7 +77,7 @@ In order to read or update variables on the global app state inside the componen ### Watching global state -Similar to component state, you can watch for changes in the global state as well. You can to refer to global state variables using _dot-notation_ in the watcher function name, and _prefixing_ it with `$appState`. This means that you need to define your watcher as a `String`, matching one of the examples below, depending on your style preference. +Similar to component state, you can watch for changes in the global state as well. You can refer to global state variables using _dot-notation_ in the watcher function name, and _prefixing_ it with `$appState`. This means that you need to define your watcher as a `String`, matching one of the examples below, depending on your style preference. ```js Blits.Component('MyComponent', { diff --git a/docs/plugins/language.md b/docs/plugins/language.md index bf753d47..538cab95 100644 --- a/docs/plugins/language.md +++ b/docs/plugins/language.md @@ -39,7 +39,7 @@ The Language plugin accepts an optional configuration object with 2 keys: - `file` - the JSON file with translations to be loaded at initialization - `language` - the default language to use -After registration of the Language plugin, it will be availabe in each Blits Component as `this.$language`. +After registration of the Language plugin, it will be available in each Blits Component as `this.$language`. ## Translations file @@ -78,7 +78,7 @@ When the JSON file is specified in the Plugin registration method, the language In case you want to load the file with translations manually, you can use the `this.$language.load()`-method anywhere in a Component and pass in the path to the JSON file as the first argument. -## Defining translations manualy +## Defining translations manually As an alternative to a JSON file with translations, you can also define translations directly via an object, using the `translations()`-method. diff --git a/docs/plugins/theme.md b/docs/plugins/theme.md index 294a2b36..ff7a073d 100644 --- a/docs/plugins/theme.md +++ b/docs/plugins/theme.md @@ -112,7 +112,7 @@ Blits.Plugin(theme, { ``` In the definition above we've specified 3 different themes: `base`, `dark` and `large`. The dark and large theme are not complete definitions, -which mean that they will inherit missing values from the base theme. +which means that they will inherit missing values from the base theme. ## Getting theme values diff --git a/docs/router/basics.md b/docs/router/basics.md index 26c1467d..c25279f1 100644 --- a/docs/router/basics.md +++ b/docs/router/basics.md @@ -42,7 +42,7 @@ In this case `id` and `name` won't automatically be made available as props insi Sometimes you may actually want pass custom data into a Blits component, without it being part of the dynamic route path or `data`-object during navigation. For these cases Blits allows you to use query parameters as part of a route (i.e. `#/series/simpsons/5/10?id=100&name=john`). -This URL hash will match the route `/series/:show/:season/:episode` and it will pass `id` and `name` as additional props into the Page component. Note: similar to dynamic path params, route query params should also be be defined in the Page component as _props_ first (i.e. `props: ['id', 'name']`) in order to be accessed on the `this`-scope. +This URL hash will match the route `/series/:show/:season/:episode` and it will pass `id` and `name` as additional props into the Page component. Note: similar to dynamic path params, route query params should also be defined in the Page component as _props_ first (i.e. `props: ['id', 'name']`) in order to be accessed on the `this`-scope. ## Router view @@ -78,7 +78,7 @@ export default Blits.Application({ Each component in a routed Blits app has a `this.$router` object that provides access to the Router instance. It can be used to programmatically navigate to pages, by calling the `to()` method on it. -The `this.$router.to()`-methods accepts 3 arguments: +The `this.$router.to()`-method accepts 3 arguments: - `path` - the path of the route to navigate to - `data` (optional) - an object with data to pass into the page as `props` @@ -147,9 +147,9 @@ The Router API provides several useful methods and properties for managing route The reactive router state (`this.$router.state`) can be useful in situations where you want to hook up reactive changes in your App to Route changes. -The `state` variable on the `this.$router` object returns a reactive object with 2 keys: `path` and `navigating`. The values of these keys will automaticaly update when the router navigates from one page to another. +The `state` variable on the `this.$router` object returns a reactive object with 2 keys: `path` and `navigating`. The values of these keys will automatically update when the router navigates from one page to another. -The router state changes can be used in a Blits template, they can be _watched_ and they can be used in generic busines logic, as demonstrated in the example below. +The router state changes can be used in a Blits template, they can be _watched_ and they can be used in generic business logic, as demonstrated in the example below. ```js export default Blits.Component('MyComponent', { diff --git a/docs/router/hooks.md b/docs/router/hooks.md index 6987a677..0617eafb 100644 --- a/docs/router/hooks.md +++ b/docs/router/hooks.md @@ -33,7 +33,7 @@ export default Blits.Application({ The before hook can optionally return a value, which will influence the behaviour of the route change: - when `false` is returned, the router will fail to finish the routing, and act as if _no matching route was found_ -- when a `string` is returned, the router will interpret this a _new route path to redirect to_ +- when a `string` is returned, the router will interpret this as a _new route path to redirect to_ - when an `object` is returned, the router will interpret this as a route object, allowing to _modify (or completely replace) the route object_ being navigated to Returning an `object` is a simple, yet powerful, mechanism to add advanced runtime configuration to your routes. A common scenario is to overwrite certain parts of the route object provided in the `to`-argument, such as the route options (such as `inHistory` or `stayAlive`) or define conditional page transitions. diff --git a/docs/transitions_animations/transitions.md b/docs/transitions_animations/transitions.md index 0b32ef25..a187b19f 100644 --- a/docs/transitions_animations/transitions.md +++ b/docs/transitions_animations/transitions.md @@ -3,7 +3,7 @@ So far we have explored how to create components and draw elements on the screen. But everything has been rather static so far. -We did learn how to _reactively_ changes values and trigger rerenders based on that. So if you try the example below, you'll see that indeed our golden element changes position. But it just jumps from one place to another: +We did learn how to _reactively_ change values and trigger rerenders based on that. So if you try the example below, you'll see that indeed our golden element changes position. But it just jumps from one place to another: ```js export default Blits.Component('Gold', { @@ -141,7 +141,7 @@ export default Blits.Component('Gold', { `, /// methods: { - transitionprogress(progress, previousProgress) { + transitionProgress(progress, previousProgress) { if(progress >= 0.5 && previousProgress < 0.5) { // halfway through the transition } diff --git a/packages/create-blits/CHANGELOG.md b/packages/create-blits/CHANGELOG.md index 9ef65cdb..10bd4995 100644 --- a/packages/create-blits/CHANGELOG.md +++ b/packages/create-blits/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## v1.4.0 + +_04 Mar 2025_ + +- Added charset meta tag to index.html + ## v1.3.0 _08 Nov 2024_ diff --git a/packages/create-blits/boilerplate/js/default/index.html b/packages/create-blits/boilerplate/js/default/index.html index 7948f70b..a91e327c 100644 --- a/packages/create-blits/boilerplate/js/default/index.html +++ b/packages/create-blits/boilerplate/js/default/index.html @@ -4,6 +4,7 @@ html, body, * { padding: 0; margin: 0} +
diff --git a/packages/create-blits/package-lock.json b/packages/create-blits/package-lock.json index d0129a5b..2cf6e344 100644 --- a/packages/create-blits/package-lock.json +++ b/packages/create-blits/package-lock.json @@ -1,6 +1,6 @@ { "name": "@lightningjs/create-blits", - "version": "1.3.0", + "version": "1.4.0", "lockfileVersion": 3, "requires": true, "packages": { diff --git a/packages/create-blits/package.json b/packages/create-blits/package.json index c7adaf35..6dd2ff6c 100644 --- a/packages/create-blits/package.json +++ b/packages/create-blits/package.json @@ -1,6 +1,6 @@ { "name": "@lightningjs/create-blits", - "version": "1.3.0", + "version": "1.4.0", "description": "Create a new Lightning 3 Blits App", "bin": "bin/index.js", "scripts": {