Forem: 🤓 Tomek Nieżurawski

Anchors for headings in MDX

🤓 Tomek Nieżurawski — Tue, 09 Feb 2021 20:47:38 +0000

This post was originally published on https://tomekdev.com/posts/anchors-for-headings-in-mdx. What you see as GIF here is interactive there. ✌️

How to add anchors to headings in MDX? It's surprisingly easy to do. I assume you are already familiar with MDX so somewhere in your code you should have a blog page layout component that uses <MDXProvider>, like that:

<MDXProvider>{children}</MDXProvider>

MDX consists of components itself. So if there is a code like this then the interpreter changes the inner value (children) into the same content but wrapped with <code></code>.

The same applies to all the headings, lists, paragraphs, etc. Our job is to override the headings. We can do it by passing components hash and specifying a replacement.

import H2 from './MyCustomMDX/H2';
import H3 from './MyCustomMDX/H3';
import H4 from './MyCustomMDX/H4';

// ...

<MDXProvider
  components={{
    h2: H2,
    h3: H3,
    h4: H4,
  }}
>
  {children}
</MDXProvider>;

Please notice that we are not going to add an anchor to the <h1> tag. It doesn't make sense in my opinion. <h1> is like a summary of the whole page. The URL that links to it is the direct link to the post. Anchors should be used to specific parts of a post (to a section).

Override heading component

The override for <h2> that shows an anchor when the mouse is over the text could look like this:

// ./MyCustomMDX/H2.js

function getAnchor(text) {
  return text
    .toLowerCase()
    .replace(/[^a-z0-9]/g, '')
    .replace(/[]/g, '-');
}

const H2 = ({ children }) => {
  const anchor = getAnchor(children);
  const link = `#${anchor}`;
  return (
    <h2 id={anchor}>
      <a href={link} className="anchor-link">
        §
      </a>
      {children}
    </h2>
  );
};

export default H2;

Below you'll see the demo. Please notice the hover state. On the left you should see § sign that is also a link, representing our anchor:

Let's explain a few bits. The way we use headings in Markdown is by using # sign, for example:

## I'm h2 with an anchor

Everything that goes after ## is passed as a child to the H2 component.

So the next interesting bit is done in the getAnchor function. Take a look at lines 3 to 8. This is what happens:

line 5 - we convert the input to lower case → "i'm h2 with an anchor"
line 6 - we remove all non-alphanumeric characters → "im h2 with an anchor"
line 7 - we replace spaces with a hyphen → "im-h2-with-an-anchor"

... and voilà. We have a URL-friendly anchor 🎉

The styling

Another important thing here is the CSS. We want to show the anchor only on hover and somewhere next to the heading itself:

h2 {
  position: relative;
}

.anchor-link {
  color: #666;
  opacity: 0;
  position: absolute;
  transform: translate(-1em, -2px);
  width: 1em;
}

h2:hover .anchor-link {
  opacity: 1;
}

Of course, you can go crazy with your anchors ;) That one is very basic.

Recommendation

One thing that is easy to overlook here (in my example) is using a character like § inside of <h2> tag. In this approach, the sign will become a part of the document outline. Which is not something we want. It's better to use an icon in SVG format but I didn't want to complicate the example.

If the simple sign is what you want then you should render <a> tag before or after the <h2>.

Highlight text in JavaScript

🤓 Tomek Nieżurawski — Sat, 09 Jan 2021 07:07:05 +0000

This post was originally published on https://tomekdev.com/posts/highlight-text-in-javascript. What you see as GIF here is interactive there. ✌️

In the previous post about search with typo tolerance, I added a few interactive elements to demonstrate the idea of how we can improve search functionality on the page by being more tolerant to typos. You might be curious how I made highlighting of matching text within results. So here it is.

It's not super complicated but I'll give you a very nice hint you might not know :) Here is the demo. Look at the GIF below (or visit my website to play with that) and observe how words are highlighted:

The trick is to replace all occurrences of searched text with the same text but wrapped with a <mark> this time. We will also add a highlight CSS class to that <mark> so we will be able to style it accordingly. You don't need any JS library for that. Here is the code that does the job:

const $box = document.getElementById('box');
const $search = document.getElementById('search');

$search.addEventListener('input', (event) => {
  const searchText = event.target.value;
  const regex = new RegExp(searchText, 'gi');

  let text = $box.innerHTML;
  text = text.replace(/(<mark class="highlight">|<\/mark>)/gim, '');

  const newText = text.replace(regex, '<mark class="highlight">$&</mark>');
  $box.innerHTML = newText;
});

Let's assume the $box is the element that contains text (it could be a whole page) and the $search is the input. In line 8 we get the current HTML in the $box and remove all current highlights in the following line. We do that to clean-up after ourselves. We don't want to keep old searches (or partial searches) on the screen. You can play with that on codepen so you'll see the HTML structure and CSS styles (where only the .highlight is important).

The hint I've mentioned before you could potentially miss is $& in the second argument of the replace method. This is a special replacement pattern that tells the replacer method to insert the matched substring there.

Why we won't simply use something like this? So inserting the searched text?

// ...
const searchText = event.target.value;
// ...
const newText = text.replace(
  regex,
  `<mark class="highlight">${searchText}</mark>`
);

By doing that we will get into trouble with the case of the letters. Most search/find functionality is case insensitive so we don't want to mess with that. Consider the example below, where I simply wrap the searched text with a <mark> with that text inside:

It's strange, isn't it? Fortunately, we don't have to be super clever to keep the case of the matched text. We just need to use $& with the replace method.

React implementation

React seems to be the most popular ~~framework~~ library that people use these days. But no matter what front-end framework you use, you'll probably pass text as an argument to a component with search-and-highlight functionality. It could be also a label of searchable items on a list.

That simplifies things a bit because we don't have to get a raw text from DOM elements. And we don't have to clean up after ourselves. We can focus on the wrapping part and leave the rendering to the rendering engine:

import React, { Component } from 'react';

export default class HighlightText extends Component {
  constructor(props) {
    super(props);
    this.state = { searchText: '' };
    this.search = this.search.bind(this);
  }

  search(event) {
    this.setState({ searchText: event.target.value });
  }

  _getText(text, searchText) {
    return searchText ? this._getTextWithHighlights(text, searchText) : text;
  }

  _getTextWithHighlights(text, searchText) {
    const regex = new RegExp(searchText, 'gi');
    const newText = text.replace(regex, `<mark class="highlight">$&</mark>`);
    return <span dangerouslySetInnerHTML={{ __html: newText }} />;
  }

  render() {
    const { cite, text } = this.props;
    const { searchText } = this.state;
    const textToShow = this._getText(text, searchText);

    return (
      <div className="container">
        <div className="search-container">
          <label htmlFor="search">Search within quoted text</label>
          <input
            id="search"
            placeholder="Type `web` for example"
            type="search"
            autoComplete="off"
            onChange={this.search}
            value={searchText}
          />
        </div>
        <blockquote cite={cite}>{textToShow}</blockquote>
      </div>
    );
  }
}

(link to sandbox if you'd like to play with that)

The most important lines in this implementation are lines 20 and 21. The first one is the heart of highlighting implementation and the second makes sure to set dangerous HTML content within an element.

What's so dangerous about the wrapped searched text?

Every framework has to sanitize raw HTML if you plan to display it on the screen. Here we are sure that the content is ok. It's provided by the user but not displayed anywhere else than their computer so it's safe by definition.

Search for "html safe + framework name" to find a way to force the rendering engine to display a wrapped element.

Good luck!

EDIT: In the original post, I was wrapping highlighted text with <span>. Thanks to the comment below I have changed that to <mark> that is semantically better 🙌

Search with typo tolerance

🤓 Tomek Nieżurawski — Sat, 02 Jan 2021 12:06:43 +0000

This post was originally published on https://tomekdev.com/posts/search-with-typo-tolerance. What you see as GIF here is interactive there. ✌️

Everyone makes mistakes. That's why undo/redo is a must-have for interfaces where you work on something. That's why we add extra padding around clickable elements for touch screens so it's easier to catch touches. That's why Google tries to show some results even if what you typed is far from perfect.

Users absolutely love that and they can't imagine software without ctrl+z and looking at a "No results" page when they mistyped something. It seems that the bar is high... but still, a lot of software does only what is convenient for developers when it comes to searching and showing results.

Examining the problem

Below we have a simple search that's going to work like filtering on the list. The list is short so it's going to be easy to understand what's happening. In other words, we already have all elements on the screen but searching is going to help us in finding that thing.

Please look at the list and watch as I am typing something there, misspelling something, or typing something completely different. You can play with it on my page.

What we've just used here is a simple "contain" query. Or if you are familiar with SQL - we perform %LIKE% here. Is it bad? Well, it's okay. Better than strict comparison for sure. But it's not super friendly because you have to be right.

The hearth of this method is highlighted in the code below. We filter the list by checking if any fruit name contains the searched text. There is a bit of user-friendliness here - the search is case insensitive which is the desired behavior in most text searches done by users:

const FRUITS = ['Apple', 'Banana', 'Blueberry', 'Cherries' /* etc... */];

function searchHandler(event) {
  const searchText = event.target.value.toLowerCase();

  const filteredFruits = FRUITS.filter((fruit) => {
    return fruit.toLowerCase().includes(searchText); // HERE
  });

  // render the list of `filteredFruits`
}

Introducing a tolerance

What about tolerating small mistakes aka typos? Let's try again. I'm searching for fruits on the list but misspell them this time. Maybe aple instead of apple?

Aple, I mean Apple is still on the list, right? Same with bananna, blubery, cheries, peer, and so on. I must admit, the algorithm is not auto-search friendly. The experience is much better with the [Search] button because you won't see false friends here while typing. But it's so much better for understanding how it works...

Let's try pee 🤭 for example. You should see Apple and Pear on the list. Both are pretty close matches according to the algorithm we are using:

The algorithm

The algorithm used here is called Levenshtein distance. I'm going to quote Wikipedia on this:

[...] the Levenshtein distance between two words is the minimum number of single-character edits (insertions, deletions or substitutions) required to change one word into the other.

That's both a huge advantage and a problem sometimes. The shorter the names of searchable items are the worse for the algorithm. Very short words like Pear, are favored when typing because the number of edits needed to "having a match" will be relatively short comparing to a very long word that needs a lot of insertions.

As stated in the definition, in the very heart of this algorithm we calculate the distance. Then we decide if the distance is something we accept - so what's the minimum of edits that we accept? Let's visualize that and see how far words are from your searched text:

Back to our embarrassing pee example 🤭. What you should see on the screen is Apple (3) and Pear (2). How the distance is measured? Please look below:

In the case of Apple we need to perform 3 operations to get there from "pee": add A and p and change the first e into l. When it comes to Pear, there are only 2 operations that have to be taken: change the second e into a and add r at the end. As you see it's easier to get Pear from the given input.

So far we were just keeping the order of items as it was (alphabetical here). But in fact, Pear is closer to what we need than Apple and that option should land as first on the list.

Fear not, we are just going to sort it! Take a look:

Implementation

So how it works? In a nutshell, we've just changed the searching/filtering algorithm (see highlighted lines).

const FRUITS = ['Apple', 'Banana', 'Blueberry', 'Cherries' /* etc... */];
const MIN_DISTANCE = 3;

function searchHandler(event) {
  const searchText = event.target.value.toLowerCase();

  const filteredFruits = FRUITS.filter((fruit) => {
    // HIGHLIGHT STARTS
    const distance = levenshtein(fruit.toLowerCase(), searchText);
    return distance <= MIN_DISTANCE;
    // HIGHLIGHT ENDS
  });

  // render the list of `filteredFruits`
}

function levenshtein(a, b) {
  // The Levenshtein's algorithm calculating the distance
}

We compare distance by using Mr. Levenshtein's method and if the distance is higher than the minimal distance we accept we decide to filter these entries out.

When it comes to the algorithm itself, you may want to implement it on your own based on the definition on Wikipedia. But if there is anything I know about computing, is that there are methods way faster than what comes to your mind first, when you look at the mathematical equation.

It's better to just use what is already there on the Internet. Here's the implementation I used.

Perfect tolerance (distance)

I couldn't find any equation for that but my best guess is that the minimum tolerance (distance) that you should accept should be a bit smaller than the shortest word in your dataset. Otherwise, there is a possibility that this word will appear too often.

Hybrid approach

If you haven't noticed yet, I use a combination of %LIKE% match and Levenshtein's method. So we fall back to the latter method only if we don't have typical matches. That's handy because the "exact" match is probably what users want. They probably don't care about other variants of a searched text that could be considered as a "fixed" typo if they have exactly what they were looking for.

Is that a perfect method?

Well, it's not. Like most solutions, it doesn't have to be perfect. If it adds more value than can bring confusion (because of false friends in results sometimes) then it's useful.

Levenshtein's method is one of many for a given subject. If you'd like to see more experiments like that, let me know.

Bonus: Does Google do the same?

Nope. Their "Did you mean?" functionality in search is very different from this. As far as I know, they based it on us (the users) who correct queries when we can't find anything useful because of typos. This way, with the unbelievable amount of data they possess, they can teach the algorithm what's the best guess for given "typos". It's far more sophisticated but it can be super-efficient for long queries.

Anyway, for our front-end needs and as a first attempt to helping users with typos in search I think we are good enough with the Levenshtein method. What do you think?

Useful setup that I always use when starting a new project

🤓 Tomek Nieżurawski — Mon, 16 Nov 2020 09:23:04 +0000

This post was originally published on https://tomekdev.com/posts/powerful-start. Go there for slightly nicer code snippets. ✌️

I'm not a huge fan of "the art of the start" articles because, after all, starting in a non-optimal way is worth more than not starting at all with a head full of knowledge that wasn't applied.

With that said, I still have a list of useful stuff that was proven to be working extremely well. The setup is meant to remove some worries from your head and focus on the product/project.

1. Use version control - git

We start with an obvious one. Even if you don't work on software, use version control, and commit regularly. It will pay off when you make mistakes (everyone does them). When it comes to my projects, I always have to add .idea to .gitignore because I'm using WebStorm 🙄

2. Use .editorconfig

Tabs vs spaces? Inconsistent indent between different files or between team members? There is a well-established solution for that. Even if you are the only person working on the project, do yourself a favor and share .editorconfig between your projects. Most IDEs will read that file and keep the format of files the way you want.

My personal preference is to apply a consistent style to ALL types of files by setting a small indent, trimming whitespaces, and inserting a new line at the end of the file:

root = true

[*]
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
indent_size = 2

3. Add linters

Linters everywhere! Really.

Linter is a tool (script) that checks if you keep a certain "style" in your files. That is enforced by following the rules. Some rules will try to keep you out of trouble, where the community knows that certain construction can harm you. And some others will enforce visual style. That's good as well because it ends useless discussions about the style of code, removes inconsistency and frustration within the team.

A lot of rules comes with autofixable feature that can modify the code for you. Not only pointing what's wrong.

Linters that I use:

ESLint - for JavaScript
Markdown linter - for .md files
Stylelint - for CSS
eslint-plugin-json - technically it's still ESLint but worth mentioning if you happen to work w .json files (like translations or configuration files)

Remember to update your linter dependencies regularly and check their release notes for new rules!

Note:

TSLint would be something worth mentioning as well (to analyze TypeScript syntax) but it was deprecated in 2019 if someone didn't notice. The proper way of using it now is typescript-eslint.

4. Add Prettier

Prettier is an opinionated code formatter. Linters do affect the way your code looks but prettier is much more in terms of styling the code. It offers support for multiple languages. The reason to use it is similar to linters - the code should look like written by a single person. Consistency is worth aiming for because it makes it easier to read the files.

Believe or not but developers read and think about code more than they actually write.

5. Automate it!

Having linters and prettier running in Continues Integration is a must. If the rules are violated then the build should fail. The bigger the project is the longer it takes to analyze the whole codebase. I am a big fan of linting only the files that were changed. So I am using:

Husky - to manage git hooks,
Lint staged - to run linters only against files that were changed.

How does it work? Husky reacts on git hook before committing files. Lint staged runs linters. Here is an example frompackage.json of one of my projects:

"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
},
"lint-staged": {
  "*.js": [
    "prettier --write",
    "eslint --cache --fix"
  ],
  "*.css": "stylelint \"src/**/*.css\" --fix"
}

In one of the projects I'm working on, linting JS files take more than 50 seconds when run against the whole project. Running it only against files that were modified within a commit takes close to nothing. Here is how it looks when I commit something to my blog:

Lint staged at work

I understand some people like to experiment and don't always have clean commits that will pass linting. Fortunately, you can bypass the checks by adding --no-verify argument. So for example:

git commit -m "Blog Post 005: Powerful start" --no-verify

6. Setup CI to deploy quickly

That's another thing worth investing time in the beginning. The easier it is to deploy the better. Of course, set the pipeline and deploy only when tests are passing and linters are satisfied. I'm not giving any recipe this time because it differs between projects. If you use a service like Netlify then it should be super easy to do it. If you use something else invest the time to set up the process.

For open-source projects, I use Travis CI and for commercial (indie) projects I useCircleCI. I think Travis is completely free for opensource and Circle has a quite generous free plan (2,500 credits/week) that will be enough for a side-project.

In some cases, I have used GitHub Actions, like when I had to deploy a single static file to S3.

7. Dependabot

Updating your dependencies is important because you get security fixes and regular bugs fix. But who has time to remember about it? No-one. So it's better to automate that process. If you happen to have tests in place with decent coverage then ideally you should be able to just merge Pull Requests created by Dependabot.

The tool was acquired by GitHub in May 2019 and since then it is offered free of charge.

Summary

That's it. A few tools, a few configuration files, maybe two services to keep your project great and ready for fast deployment. I found myself adding these ingredients to every project I work on : server-side (in nodejs), React, Ember, Angular, standalone library, Chrome extension, React Native application, and so on. As you see, it's not bounded to any technology so it's hard to come up with a starter pack.

You can set the sails now.

Effective titles and more

🤓 Tomek Nieżurawski — Sat, 07 Nov 2020 07:31:45 +0000

This post was originally published on https://tomekdev.com/posts/effective-titles-and-more. What you see as a GIF here is interactive there. ✌️

This is not an SEO guide on how to write effective titles or (maybe I should say) how to create clickbait.

No. We are going to talk about the technicals. If you want my writing advice on that I'd say a cliché:

title should be short and descriptive

Did mine do a good job? I don't know, but if you are here reading this, maybe it did.

Site name

I believe you should put the site name into the page's title because that's going to land as a name of a bookmark if someone happens to add your page to bookmarks (do people still do that?):

Bookmark added with a clear indication of a site

And will help in fast identification. I see that useful also in the History tool of your browser of choice:

The site name is prominent on a History list

Now, should you put the site name before or after the title for the content of the page?

Well, I believe after is the way to go. Again, easy identification comes into play. If everything starts with "Tomek Dev" then you have to omit it to understand what's this page about. Take a look at this:

Tomek Dev - Effective titles
Tomek Dev - If there is an input, there should be a form
Tomek Dev - Content Curation is going to be a job and how Content Marketing killed the web
Tomek Dev - Dynamic partiallyActive Link in Gatsby

Doesn't look that bad when I have it on a list, right? Right. But consider the real estate of a browser's toolbar:

Tabs are packed. Redundant information doesn't help here

There is no lot of place but it can be even less if you use a lot of tabs. Having a title of your content first and the site name second will help in identification. The content title is more important for a user:

Tabs are still packed but more valuable information gets first

What separator to use

I'm using a pipe - | because my dad is a plumber and I spend a lot of my life in the terminal. What else could I use? 😉

Jokes aside, that could be a branding thing. Go crazy if that's your thing:

Here ♣ separates content title and the site name

Legal advice page with § as a separator? Why not

After all, the worst you can do is to have a single title for your entire application. Don't do that.

Even if your app is just a tool, think for a while if you don't have some logical modules there. Because know what? 👇

Title can be changed dynamically

That's good news (not only) for Single Page Applications. Use it to bring users' attention to something. Consider Facebook for example:

🤔 Something happened, right?

They encourage you to read the message you've just received. All you have to do to change the title of a page is setting it this way:

document.title = 'A new title! | Tomek Dev';

Here is a small GIF presenting how it works:

Of course, if a user is already on our page we should not distract them with a flashing title. Maybe change it only if the tab is not active?

Consider this example, you work on a Video Editing application and people export their movie. The file has to be prepared and it takes time. You can show the progress on the title if they go to a different tab and announce a success. It could look like this:

First things first. How to detect the change of tab's visibility? (I've just used the right keywords there).

document.addEventListener('visibilitychange', function () {
  console.log(document.hidden);
});

document.hidden will tell you what's the status and you can modify the behavior accordingly to your needs. When it comes to the example above it was done this way:

const originalTitle = document.title;
let isTabHidden = false;
let percentage = 0;

function changeTitle(title) {
  if (isTabHidden) {
    document.title = title;
  } else {
    document.title = originalTitle;
  }
}

const interval = setInterval(() => {
  percentage += 1;

  if (percentage < 100) {
    changeTitle(`${percentage}% Preparing video | Tomek Dev`);
  } else {
    changeTitle('⚬ Your file is ready! | Tomek Dev');
    clearInterval(interval);
  }
}, 100);

document.addEventListener('visibilitychange', function () {
  isTabHidden = document.hidden;
});

It's obviously a trick to show how it could work. In this place, you'd put your code that updates the percentage value. That can come from a backend endpoint that is preparing the video. No matter if that's a WebSocket or regular XHR request.

Note

Did you notice how progress slows down when I go to a different tab? It's because I'm faking the export progress via setInterval. The tab is in the background so Chrome executes the timing function (setTimeout/setInterval) once per second at maximum.

Eagle-eyed folks may notice that visibilitychange listener is not needed in that example. We can use document.hidden directly in our changeTitle function. I added it here only to show that such a listener exists ;) It might be useful in some implementations.

And do you know who (probably) uses that event? Github. Open two tabs, leave an unsaved comment in a PR, and go to another tab. You should see this:

Dynamic === fun

Let me give you a few more examples of how you can make your title cool.

These days, you should see a speaker icon 🔊 if the audio is played in a tab. But it wasn't always like that. You can animate an audio playing in various ways:

Let's show a listener

Or a dancer

Equalizer?

Song title floating

But be careful

Of course, like with every superpower, there is one thing you need to remember. Don't overuse it. Effects like this could be a very nice addition to your page. It can extend the experience and make it better. But it can also be annoying. Like a close button running away from your cursor.

Summary

Maybe we've just scratched the surface of what we can do with <title> but here are some takeaways for you:

Use a short descriptive title.
Put your site name after the title describing the page's content.
Add a separator between the title's parts. You can go crazy.
Use the title's dynamic nature to extend the user experience.
Bring users' attention to a tab if something important happened.
Don't overuse dynamic techniques to avoid annoying users.

The real estate of the browser's top bar is yours now.

If there is an input, there should be a form

🤓 Tomek Nieżurawski — Sat, 17 Oct 2020 15:53:58 +0000

This post was originally published on https://tomekdev.com/posts/input-and-form. Go there to read a bit more interactive and style richer version ✌️

I often see in Single Page apps a situation where someone uses just an <input> field. Sometimes in the accompaniment of <label> if you happen to work with a pro 🌟. It feels that when we gained control of inputs with two-way binding and we started handling onclick events on buttons with our fancy frameworks, we forgot the old way of doing things.

The old way, and the right way

The headline of this section may suggest that the old way and the right way are two different things. Where in fact, it's the opposite. If you come back with your memory before the frameworks (or ajax) era you see that people were using a <form> element when dealing with inputs and buttons.

In the past we were extensively using <form method=""> to process the input. I encourage you to still use a form element. It comes with benefits.

Common mistake

I use the keyboard to navigate and interact with pages. That speeds up everything. So for me one of the biggest pitfalls of using <input> without a <form> is that the input is not auto-submittable, so to say.

When you hit ENTER in the field that is inside the form then the form is submitted. That's very convenient for solo-input interfaces like a modal below:

You don't have to touch your mouse or touchpad and click Save button 🎉. That would be a waste of time!

Solution

It's a common mistake to bind your action to a <button> where in fact all you have to do is wrap your<input> with a <form> and assign submit event to a form:

<form id="my-form">
  <input name="example" type="text" />
  <button type="submit">Submit</button>
</form>

const form = document.getElementById('my-form');

form.addEventListener('submit', function handleSubmit(event) {
  alert('Submit clicked');
  event.preventDefault();
});

Don't forget to prevent default behavior from firing and run your custom behavior. It could be running validation and actually sending the data.

One more thing that you should consider is always specifying button's type. It's submit by default in most browsers but Internet Explorer is different in this case and has button as a default type.