\r\n\r\n```\r\n\r\n```js\r\nwriter.queueWrite('#phrases', queueInterval, loop)\r\n```\r\n\r\n### Pausing & Playing\r\n\r\nYou can pause and resume playing at any time.\r\n\r\n```js\r\nWriter.write('Some very cool header.').then(({ status, message }) => {\r\n\t// this will run when the writing stops.\r\n\tconsole.log(`${status}: ${message}`)\r\n})\r\n\r\nsetTimeout(\r\n\t() => Writer.pause(), // will stop writing\r\n\t1000,\r\n)\r\n\r\nsetTimeout(async () => {\r\n\tconst { string } = await Writer.play() // continue writing\r\n\tconsole.log('Completed:', string) // will log after finished writing\r\n}, 2000)\r\n```\r\n\r\n### One-Time-Use\r\n\r\nFor quick one-time writing.\r\n\r\n```js\r\nimport { write, queueWrite } from 'glitched-writer'\r\n\r\nwrite('Write this and BEGONE!', htmlElement, options, stepCB, finishCB)\r\n\r\nqueueWrite(texts, htmlElement, options, interval, loop, stepCB, finishCB)\r\n```\r\n\r\n### On Text Input\r\n\r\nDon't be afraid to call write method on top of each oder.\r\nNew will stop the ongoing. But, it's good to `debounce` the event handler.\r\n\r\n```js\r\nimport debounce from 'lodash.debounce'\r\n\r\nconst onInput = debounce(() => writer.write(inputEl.value), 500)\r\n\r\ninputEl.addEventListener('input', onInput)\r\n```\r\n\r\n### Callbacks | Events\r\n\r\n```js\r\n// your html element:\r\ntextHtmlElement.addEventListener('gw-finished', e =>\r\n\tconsole.log('finished writing:', e.detail.string),\r\n)\r\n\r\n/**\r\n * Adding callbacks: writer.addCallback(type, callback)\r\n *\r\n * @param type \"start\" | \"step\" | \"finish\"\r\n * @param callback your callback function: (string, writerData) => {}\r\n */\r\n\r\nconst startCB = string => console.log('Started writing:', string)\r\n// add\r\nwriter.addCallback('start', startCB)\r\n// remove\r\nwriter.removeCallback('start', startCB)\r\n```\r\n\r\n### Add & Remove\r\n\r\n`.add(string)` & `.remove(number)` are methods usefull for quick changes to the previous text.\r\n\r\n```js\r\n// Let's say current text content is: \"Hello World\"\r\n\r\nWriter.add('!!!')\r\n// -> Hello World!!!\r\n\r\nWriter.remove(9)\r\n// -> Hello\r\n```\r\n\r\n### Writing HTML\r\n\r\n(**! Potentially dangerous !**) Let's you write text with html tags in it. Don't use on user-generated content.\r\n\r\n```js\r\n// You need to enable html option.\r\nconst Writer = new GlitchedWriter(htmlElement, { html: true })\r\n\r\nWriter.write('Be sure to click this!')\r\n```\r\n\r\n### Letterize\r\n\r\nSplits written text into series of `` elements. Then writing letters seperately into these child-elements.\r\n\r\n```js\r\n// You need to enable html option.\r\nconst Writer = new GlitchedWriter(htmlElement, { letterize: true })\r\n\r\nWriter.write('Hello there!')\r\n/**\r\n * The shape of one Char:\r\n * span.gw-char (+ .gw-finished when compleated | .gw-changed with each change)\r\n * \tspan.gw-ghosts\r\n * \tspan.gw-letter (+ .gw-glitched when is a glitched letter)\r\n * \tspan.gw-ghosts\r\n */\r\n```\r\n\r\n### Endless animation\r\n\r\nOption `endless` let's you run the text animation until you disable that function.\r\n\r\nThis opens the door for some additional effects, like: **Show on hover** (e.g. on secret fields) or **refreshing text** to give it user attention.\r\n\r\nHere is a [live example](https://codepen.io/thetarnav/pen/oNBLpxb).\r\n\r\n```js\r\n// SHOW ON HOVER\r\n// First make the password scramble forever\r\nwriter.endless(true)\r\nwriter.write('PASSWORD')\r\n\r\n// And disable endless option on hover\r\npassEl.addEventListener('mouseover', () => writer.endless(false))\r\n```\r\n\r\n### Changing options post initialization\r\n\r\nOptions can be changed in 2 ways after instance creation.\r\n\r\n```js\r\n// Extending current options\r\nwriter.options.extend({\r\n\thtml: true,\r\n\tmaxGhosts: 10,\r\n\t// the rest will stay the same\r\n})\r\n\r\n// Reseting options\r\nwriter.options.set({\r\n\tletterize: true,\r\n\toneAtATime: 4,\r\n\t// the rest will be set to default\r\n})\r\n```\r\n\r\n### Optimizing CSS - Preventing Layour Shifts\r\n\r\nChanging text rapidly can cause a lot of layout shift. These are few css tricks worth considering when using this package:\r\n\r\n```css\r\n// 1. \"Warn\" the browser that the text-content\r\n// will be changing\r\n.gw {\r\n\twill-change: contents;\r\n}\r\n\r\n// 2. It's good to make the element position absolute or fixed\r\n// so it wont influence the rest of the layout\r\n.gw {\r\n\tposition: fixed;\r\n}\r\n\r\n// 3. Make the width and height constant,\r\n// so it doesn't shift while writing\r\n.gw {\r\n\twidth: 80ch;\r\n\theight: 6rem;\r\n}\r\n\r\n// 4. If you can't or don't want to,\r\n// then you should tell css that it will change,\r\n// so it can prepare resources to handle it\r\n.gw {\r\n\twill-change: contents, height, width;\r\n}\r\n```\r\n\r\n### Available imports\r\n\r\nList of all things that can be imported from `glitched-writer` module.\r\n\r\n```ts\r\nimport GlitchedWriter, { // <-- GlitchedWriter class\r\n\tCustomOptions, // <-- Options type\r\n\tCallback, // <-- Callbacks type\r\n\tWriterDataResponse, // <-- Type of a data response in callbacks\r\n\twrite, // <-- One time, standalone write function\r\n\tqueueWrite, // <-- Standalone queue write function\r\n\tpresets, // <-- Object with all prepared presets of options\r\n\tglyphs, // <-- Some glyph sets\r\n\twait, // <-- Ulitity promise function, that can be used to wait some time\r\n\tcreate, // <-- Function serving as an alternative way to create GlitchedWriter instance.\r\n} from 'glitched-writer'\r\n```\r\n\r\n---\r\n\r\n## Presets\r\n\r\nTo use one of the available presets, You can simply write it's name when creating writer, in the place of options.\r\nAvailable presets, as for now:\r\n\r\n- **[default](https://codepen.io/thetarnav/pen/MWWyPzY)** - Loaded automatically, featured on the GIF up top.\r\n\r\n- **[nier](https://codepen.io/thetarnav/pen/OJWNRor)** - Imitating the way text was appearing in the _NieR: Automata's UI_.\r\n\r\n- **[typewriter](https://codepen.io/thetarnav/pen/qBRpQpQ)** - Simple but feels like being written by a human: one letter at a time, with erasing enabled by default.\r\n\r\n- **[terminal](https://codepen.io/thetarnav/pen/mdRyqga)** - Similar to the typewriter preset but more \"robotic\". Characters flow smoothly (with stable interval), but with little \"stutering\" here and there.\r\n\r\n- **zalgo** - Inspired by the _\"zalgo\"_ or _\"cursed text\"_, Ghost characters mostly includes the unicode combining characters, which makes the text glitch vertically. Requires high \"maxGhosts\" to look good.\r\n\r\n- **[neo](https://codepen.io/thetarnav/pen/vYgYWbb)** - Recreated: _Justin Windle's [\"Text Scramble Effect\"](https://codepen.io/soulwire/pen/mErPAK)_\r\n\r\n- **[encrypted](https://codepen.io/thetarnav/pen/oNBLpxb)** - Simple Text Scramble effect, suits well displaying secret data, like passwords or card numbers. And generally looks good for more \"casual\" usecases - where you don't want too much \"layout shifting\", caused by rapid characters number changing.\r\n\r\n- **bitbybit** - Writes text word by word, in rhythmic but stattering manner.\r\n\r\n- **[cosmic](https://codepen.io/thetarnav/pen/ExWgYer)** - Text slowly appears from and vanishes to the hollowness of space. Use with preserved sequences of white space _(white-space: pre-wrap;)_\r\n\r\n```js\r\nnew GlitchedWriter(htmlElement, 'terminal')\r\n```\r\n\r\n### Importing preset objects\r\n\r\nYou can import the option object of mentioned presets and tweak them, as well as some glyph sets.\r\n\r\n```js\r\nimport { presets, glyphs } from 'glitched-writer'\r\n\r\n// Extend preset for your needs:\r\nnew GlitchedWriter(htmlElement, {\r\n\t...presets.typewriter,\r\n\tletterize: true,\r\n})\r\n```\r\n\r\n---\r\n\r\n## Customizing behavior\r\n\r\nThere are many options you can tweak to customize the writting effect. Check out the [playground website](https://glitched-writer.site/) I've made, where you can test both presets and options.\r\n\r\n**Range** values will result in random values for each step for every letter.\r\n\r\n**Ghost** are \"glitched letters\" that gets rendered randomly in the time of writing, but aren't part of final string.\r\n\r\n### Stylistic Options:\r\n\r\n> \\- options that set the visual effect.\r\n\r\n```ts\r\nsteps?: [number, number] | number, // [1, 8]\r\ninterval?: [number, number] | number, // [60, 170]\r\ndelay?: [number, number] | number, // [0, 2000]\r\nchangeChance?: number, // 0.6\r\nghostChance?: number, // 0.2\r\nmaxGhosts?: number, // '0.2'\r\noneAtATime?: boolean | number | 'word', // 0 | false\r\nglyphs?: string | string[] | Set, // glyphs.full + glyphs.zalgo\r\nglyphsFromText?: boolean, // false\r\nfillSpace?: boolean, // true\r\nmode?: 'normal' | 'matching' | 'erase' | 'clear', // 'matching'\r\n```\r\n\r\n- **steps** - Number of **minimum** steps it takes one letter to reach it's goal one. Set to 0 if you want them to change to right letter in one step. (int)\r\n\r\n- **interval** - Interval between each step, for every letter. (int: ms)\r\n\r\n- **delay** - first delay each letter must wait before it starts working (int: ms)\r\n\r\n- **changeChance** - Chance of letter being replaced by a glitched character (p: 0-1)\r\n\r\n- **ghostChance** - Chance for ghost letter to appear (p: 0-1)\r\n\r\n- **maxGhosts** - Maximal number of ghosts to occur\r\n\r\n - **int** - _(eg. 15) -> this will be the limit._\r\n - **float** - _(eg. 0.25) -> Limit = maxGhosts \\* goalString.length_\r\n\r\n- **oneAtATime** - Without this option enabled, letters in your string will animate all at once. Enabling this option, by setting it to **true** or any **intiger larger than 0**, will cause the string to be written from letter by letter, left to right. Number value, signifies how many letters will be typed at once.\r\n\r\n - **\"word\"** - _now you can also set is to \"word\". Instead of writing letter by letter, or couple of letters, writer will divide goal text by words._\r\n\r\n- **glyphs** - A set of characters that can appear as ghosts or letters can change into them\r\n\r\n- **glyphsFromText** - If you want to add letters from written text to the glyph charset\r\n\r\n- **fillSpace** - With this **enabled** if letter gets erased ny replacing with space - to keep the same \"width\" of previous string, and to make letters _\"disappear in space\"_. If **disabled**, every letter will \"stick\" to the rest. To make it more clear (hopefully), here is an example \"frame\" of writing: **\"Something farely long\"** -> **\"Short String\"**.\r\n\r\n - false - \"XOSh8rt S3rinFv\"\r\n - true - \" X OSh8rt S3rinF v \"\r\n\r\n- **mode** - Writing mode - decides on how to prepare the Char Table.\r\n\r\n - 'matching' - _Will scan starting and goal string for matching characters and will try to build character map from that. Requires ghosts enabled (>0) to take effect_\r\n - 'normal' - _Wont do any matching, just converts starting string into character map._\r\n - 'erase' - _First Erases entire string and then writes your text._\r\n - 'erase_smart' - _Same as erase, but saves the matching begginging letters_\r\n - 'clear' - _Instantly deletes entire textContent and then writes your text._\r\n\r\n### Control Options:\r\n\r\n> \\- options that control writer behavior.\r\n\r\n```ts\r\nhtml?: boolean, // false\r\nletterize?: boolean, // false\r\nendless?: boolean // false\r\nfps?: number, // 60\r\n```\r\n\r\n- **html** - _Potentially dangerous option._ If true, written string will be injected as html, not text content. It provides advanced text formating with html tags and more. But be sure to NOT enable it on user-provided content.\r\n\r\n- **letterize** - Instead of injecting written text to \"textContent\" or \"innerHTML\", it appends every letter of that text as a child span element. Then changing textContent of that span to current letter. It gives a lot of styling possibilities, as you can style ghosts, letters, and whole chars seperately, depending on current writer and char state.\r\n\r\n- **endless** - It will make the animation endless. _But why?_ Well, you can disable this option while the animation is running _( writer.endless(false) )_ and finish the animation when you want.\r\n\r\n- **fps** - Animation loop is done using requestAnimationFrame, with fps you can controll the maximum framerate of writing animation. Only actually matters for high refresh monitors. _(! wont have an effect with letterize enabled !_)\r\n\r\n### Generator Options:\r\n\r\n> \\- custom functions used to generate variables contextually, for use in writing.\r\n\r\n```ts\r\n/**\r\n * @param char - Char for which to generate value\r\n * @param base - default function generating that value\r\n */\r\n\r\n// generaing ghost/glitched char\r\ngenGlyph?: (char: Char, base: Function) => string\r\n\r\ngenDelay?: (char: Char, base: Function) => number // [ms]\r\n\r\ngenInterval?: (char: Char, base: Function) => number // [ms]\r\n```\r\n\r\n## The End - couple of final words\r\n\r\nThanks for checking out the Glitched Writer. Let me know, if you are using it somewhere - would love to see it working out there.\r\n\r\nIf you have any questions, just create new [discusion](https://github.com/thetarnav/glitched-writer/discussions) or [issue](https://github.com/thetarnav/glitched-writer/issues). Or just send me an email at gthetarnav@gmail.com, if you want.\r\n\r\nPresets or feature ideas are also welcome :)\r\n","readmeFilename":"README.md","homepage":"https://glitched-writer.site/","repository":{"type":"git","url":"git+https://github.com/thetarnav/glitched-writer.git"},"bugs":{"url":"https://github.com/thetarnav/glitched-writer/issues"}}