Merge branch 'stage'

README.md

@@ -1,7 +1,7 @@
 <div align="center">
 <h1>SCSS Typewriter</h1>
 The SCSS Typewriter is a fully functional typewriter mixin for SCSS.<br><a href="https://codepen.io/brandonmcconnell/live/0aad0deb0d0a6f308b434309b9b6b93c" target="_blank">Live Demo</a> | Follow me on Twitter <a href="https://twitter.com/branmcconnell" target="_blank">@branmcconnell</a><br><br>
-<img alt="demonstration of SCSS typewriter in action" src="https://assets.codepen.io/1580009/typewriter-scss-bg.gif" style="mix-blend-mode: screen;">
+<img alt="demonstration of SCSS typewriter in action" src="https://assets.codepen.io/1580009/typewriter-scss-bg.png" style="mix-blend-mode: screen;">
 </div>
 
 #### Table of Contents
@@ -72,14 +72,16 @@ $options: (
 
 Properties of the `$options` map can only be overwridden using another object of the map type, with matching keys. This argument and all its properties are entirely optional. The permitted properties for the `$options` map—along with their definitions—are:
  - `name`: **(string)** A preferred name for the animation created. If you do not supply an animation name, or when an empty string is the value (as is the default), a generic one is used in the format `typewriter-0` where the `0` increments with each use of the mixin to avoid naming conflicts.
+ - `iterations`: **(number)** This value determines how many times to loop the animation. This defaults to `infinite` to loop continuously. If a finite number is provided (e.g. `1`, `15`, etc.), the animation will repeat that many times and then type the first string again, at which point the typing animation will conclude, but the caret animation will continue if `caret` is enabled. The final typing animation of the first string is rendered via a separate animation that runs once the first full animation has completed all iterations.
  - `caret`: **(bool)** This boolean value determines whether to show a blinking text (insertion) cursor/caret at the end of the dynamically typed/deleted text where the caret would naturally be. This value defaults to `true`, but changing it to `false` will disable the blinking caret. The color of the caret defaults to match the same color as the text by making use of `currentColor`. To adjust the styles of the caret, add styles to the `::after` pseudo-element of the style which you apply the mixin `@include` to, conversely to the typed text itself, which makes use of the `::before` pseudo-element.
  - `caret-speed`: **(number)** This is the duration of one "blink" animation (in seconds) of the insertion cursor/caret when it has been enabled using the `caret` property. Like the `$speed` object values, these number values do not accept units.
  - `caret-width`: **(number)** This is the width of the caret. By default, it is set to a value of `1ch` (or the width of the character "0" in the current font). By their nature, `ch` units are ideal for this use-case, but any non-percent numeric units may be used (e.g. `ch`, `ex`, `px`, `em`, `rem`, `vw`, `vh`, etc.).
  - `caret-color`: **(number)** This is the color of the caret. By default this color is inherited from the current text color of the parent element using `currentColor`, but this can be set to any valid color value (e.g. `hex`, `rgb`, `rgba`, `hsl`, `hsla`, `lab`, `lch`, etc.).
  - `caret-space`: **(number)** This is the width of the caret. By default, it is set to a value of `.1ch` (or 10% of the width of the character "0" in the current font). By their nature, `ch` units are ideal for this use-case, but any non-percent numeric units may be used (e.g. `ch`, `ex`, `px`, `em`, `rem`, `vw`, `vh`, etc.).
+ - `styles`: **(map)** Any styles added to this map are displayed across all strings including the `end-on` string.
+ - `end-styles`: **(map)** Any styles added to this map are displayed at the end of the animation once all iterations including the `end-on` string have completed their animations. These styles will not be rendered if the animation is set to loop continuously.
  - `delay`: **(number)** This is the duration of the delay (in seconds) before the animation initially begins. This property has a default value of `1`, as this delay helps to emphasize the animative nature of the mixin. Similarly to `caret-speed` and the `$speed` object values, this value also does not except units.
  - `type-pausing`: **(boolean)** This boolean value determines whether the current typewriter will replace any/all instances of the special "pause" syntax within its strings with a pause for the duration of however long it would take to type the number of characters indicated by its contained value. This property is set to true by default. The type-pause syntax is `<[INTEGER]>`. When enabled, a given string `Be right <[3]>there.` the total time it would take to animate the string forward would be the current `type` speed duration * 18. The 18 character-durations is comprised of three parts: `Be right ` (9 chars), `<[3]>` (same time as 3 chars), and `there.` (6 chars). 9+3+6=18
- - `iterations`: **(number)** This value determines how many times to loop the animation. This defaults to `infinite` to loop continuously. If a finite number is provided (e.g. `1`, `15`, etc.), the animation will repeat that many times and then type the first string again, at which point the typing animation will conclude, but the caret animation will continue if `caret` is enabled. The final typing animation of the first string is rendered via a separate animation that runs once the first full animation has completed all iterations.
  - `prefix`: **(string)** This string will displays at the beginning of each typed string and will NOT be included in the animation of the text itself. It's important to note that if you set per-string styles, they cause undesirable effects to the prefix, causing its style to change instantly between strings. In this case, opt to place any prefix/suffix strings outside the animated text element altogether.
  - `end-on`: **(string/number)** This string value will ONLY be rendered when `iterations` is set to a finite number. Once the final iteration completes, the animation will type one final string and keep that string present, thereby concluding the animation. This property can be passed either any custom non-empty string or the nth-index of the string from the `$strings` list to use. By default, if using a finite list of `iterations`, the first string from the list will be re-typed if none is provided using the `end-on` property.
  - `alt-text`: **(string)** This string will be used to add alt text to the pseudo `::before` element for accessibility. When unset, this property will—by default—fall back to the value stored in `end-on`. If `end-on` is also unset, both values will default to the value of the first string passed to the typewriter mixin.