DEV Community: Islam Naasani

What makes a good dashboard

Islam Naasani — Mon, 08 Apr 2024 19:27:03 +0000

I've worked on a bunch of dashboard applications until now, and I found some aspects that kind of distinguish them from other applications:

Your user probably uses this app a lot, therefore efficiency and good UX matter more here, a small UX annoyance in an application you use casually will be 10x more annoying if use this app daily.
Dashboards are usually desktop-first in design, thus keyboard support should be first-class citizen in your app.
Data is dynamic, and changes very frequently, so you should be very careful with caching.

I have a few tips that address the points above which improves the UX of a dashboard application, and any web app actually, but I think they are more relevant in a dashboard context, where UX is very crucial.

State should be in the URL

I started with this one, because of how much I believe it's important and how often I see that it's not implemented.

Because of the way the web is today, it's not enforced to make your URL hold any state, you can make a whole application with only one route! (please don't), but even if it's easier/less work not to implement it, it shouldn't be skipped over, as it's quite frustrating to be missing in any non-trivial application. Consider a simple search bar:

The user is expecting a new change in the data so they keep refreshing the page, now if your url doesn't look like this https://dashboard.example.com/customers?s=Ahmad, the user will need to retype Ahmad each time... Also they cannot bookmark nor share a filter state, a page's tab, or a data table pagination position.

Sometimes, it's challenging to put complex objects in the URL with the browser's URLSearchParams API, still it's more than enough for a lof of cases, and can help improve the UX with very little work done, if you're using React router or Next.js, you can use useSearchParams hook and you will find something similar in every routing solution, which really won't feel different a lot of a normal useState most of the time.

For more complex use cases, I believe Tanner Linsley's new library: TanStack Router is the way to go, please check it out if you still haven't, it's just as great as TanStack Query!

Keyboard navigation

In general, this is more critical for special needs users, but in a dashboard context, this is mostly needed when filling forms, which is very typical for a dashboard.

In which I mean navigating elements with Tab keyboard's key, this shouldn't be hard to support this if you're using any respectable UI components library, they all come with this built-in, still there's some ways you can mess this up:

Accidentally removing the outline style

This is necessary to indicate what element is currently being focused on, if this isn't visible (or hardly visible), keyboard navigation would be impossible.

Nesting clickables

Common scenario is you want a link that looks like a button, so what you do is:

<Link href="/...">
  <Button>
    A Link Button!
  </Button>
</Link>

First issue of this is that it's semantically incorrect, second is that it will break keyboard navigation, as the first tab you would focus on the link element, the second one you will focus on the button, now consider this for a page full of links that do that, not much fun.

the fix for this is quite easy, just style the link with the button style, the result is exactly the same, all UI component libraries that I know of have this built in, MUI for example:

<Button LinkComponent={Link} href="/Login">
  Login
</Button>

or shadcn/ui:

<Button asChild>
  <Link href="/login">Login</Link>
</Button>

for other situations that you're forced to do this, use tabindex="-1" for elements that shouldn't be navigable.

Buttons should be buttons, links should be links

What is worse than having a link nested in a button? not having the link at all! I yet to find a justifiable reason to do:

<Button onClick={() => navigate("/i-am-a-link-actually")}>
  Button
</Button>

There's a lot of issues with this, the most annoying for me:

I don't know where this button will take me (no url preview).
I can't open the link in a new page (CTRL + Click), which is really common to do (multitasking).

The same goes for buttons you don't want to have a button styling, you should never use <div /> as a button, there's always better alternatives, in MUI, for example, you can either:

Use ButtonBase component.
Or if don't want any styling at all you can use Box component (and remove any unwanted styling):

<Box component="button">Button</Box>

NOTE: you may be thinking why not just use <button/>, we can, but now we won't be able to access the library's styling system and theme.

if you still need to use a div for some reason, at least make sure that it's tabbable (tabindex="0") and there's a visual indication when the button is focused.

Always have fresh data

Dashboards always have in common that the data is dynamic, it would be sensible to make sure that your data is always up-to-date and let the user have trust in your app, and not refresh the page after any action they do.

if you're using Tanstack query, that's a very good start! it comes with pretty good defaults, you won't need to do much to always have fresh data (and still have good caching implemented), but you still need to make good use of its features:

Use a well-designed query keys system

I posted about it before, basically make it easy for yourself to find what queries to invalidate or refetch, if you usually throw your useQuerys around in your components with random query keys... I can assure you that you won't bother to do any invalidation, or if you do, you have to check what the keys for each query and type them manually, which is error-prone (or worse yet, just force a page refresh!), to avoid all that, just keep track of your query keys (or tags if you're using Next.js) in a type-safe way and allow invalidation to be done in a few keystrokes.

One way to do it that I found pleasant to work with:

queries/pet.tsx

import {
  addPet,
  deletePet,
  findPetsByStatus,
  getPetById,
} from "@/services/pet";
import { createQueryKeys } from "@lukemorales/query-key-factory";
import { useMutation, useQuery } from "@tanstack/react-query";

type PetFindByStatus = Parameters<typeof findPetsByStatus>;
type PetDetailsParameters = Parameters<typeof getPetById>;
export const petKeys = createQueryKeys("pet", {
  findByStatus: (...params: PetFindByStatus) => ({
    queryFn: findPetsByStatus(...params),
    queryKey: [params],
  }),
  details: (...params: PetDetailsParameters) => ({
    queryFn: getPetById(...params),
    queryKey: [params],
  }),
});

export const petQueries = {
  useFindByStatus: (...params: PetFindByStatus) =>
    useQuery({ ...petKeys.findByStatus(...params), staleTime: Infinity }),
  useDetails: (...params: PetDetailsParameters) =>
    useQuery(petKeys.details(...params)),

  useAdd: () =>
    useMutation({
      mutationFn: addPet,
    }),
  useDelete: () => useMutation({ mutationFn: deletePet }),
};

A new pet was added and we want to reflect that in our pets data table, we can invalidate the findByStatus query to do that like this:

// for a specific pet status
queryClient.invalidateQueries({
  queryKey: petKeys.findByStatus({ status: ["available"] }).queryKey,
});
// the type of queryKey here is: readonly ["pet",
// "findByStatus", [params: FindPetsByStatusParams, options?: RequestInit | undefined]]

// ...or for all possible status
queryClient.invalidateQueries({ queryKey: petKeys.findByStatus._def });
// the type of queryKey here is: readonly ["pet", "findByStatus"]

Pretty cool right?

NOTE 1: I'm using orval.dev here to generate the API functions from the swagger spec, give it a look.
NOTE 2: You may see the code above a little bit messy (a lot of ... usage), and I kinda agree, I believe it can be better, but for now I think this is a good balance between productivity, readability and maintenance, I'm still in the process of improving this, so I might update this section in the future.

Conclusion

These were a few pain points I found in some dashboard applications I worked on, and a most of them doesn't actually require a lot of effort from you, but still very easy to ignore, and would be hard to reverse after the codebase become large enough, so just be thoughtful from the start, and try to ensure they are addressed from the get-go!

Getting the most out of vscode

Islam Naasani — Wed, 24 Jan 2024 11:17:49 +0000

I've put in this post a few vscode features and how I use them on a daily basis, this isn't a list of vscode tips and shortcuts, I think there is enough of those on the internet, although I did include two shortcuts in the last section that I think a lot of developers are sleeping on.

As this is just a bunch of personal thoughts and usages of popular vscode features, I'll not talk about the available options and how to use them, but I did include the documentation link when needed.

Code Snippets

What I love about code snippets—aside from productivity—is how they make you follow coding conventions without the need of you to be conscious of them, so if you want component functions, for example, to be defined in a specific way, setting a code snippet here would be beneficial.

Let's see how that would work out with some conventions that you may want:

A component should be defined as an arrow function.
types should be used over interfaces.
only named exports should be used.
components are named the same as the file they are in (for the main component in the file).

The following code snippet can do the required:

.vscode/React.code-snippets

{
  "Functional Component by filename": {
    "scope": "typescriptreact",
    "prefix": "fcf",
    "body": [
      "export type ${TM_FILENAME_BASE/(.*)/${1:/pascalcase}/}$1Props = {};",
      "export const ${TM_FILENAME_BASE/(.*)/${1:/pascalcase}/}$1 = ({}: ${TM_FILENAME_BASE/(.*)/${1:/pascalcase}/}$1Props) => {",
      " $2",
      "};"
    ],
    "description": "Create a functional component by the filename"
  }
}

The code generated from the snippet:
drop-down.tsx

export type DropDownProps = {};
export const DropDown = ({}: DropDownProps) => {

};

There is a lot of cool things you can do with code snippets, give the documentation a quick read.

Quick Navigation

By quick navigation I mean when you press Ctrl + P or Ctrl + E and search for files:

I think a lot of developers already use this, nothing new here, but what I want to talk about is using a file structure that will enhance your experience using the quick navigation.

What is great about quick navigation, is that you only need to type some parts of the path but still isn't a fuzzy search, for example if we have a file named drop-down.tsx, drdo would match as they are a correct character sequence in the path drop-down.tsx but dorp won't match as there isn't any character sequence like that.

Therefore, if you structure your files in a hierarchial, consistent way, you would be able to type some sections of the path and get what you're searching for, consider a file tree like this:

src/features
├── comment
│   ├── api
│   │   ├── api.ts
│   │   ├── queries.ts
│   │   └── type.ts
│   ├── components
│   │   ├── CommentCard.tsx
│   │   ├── CommentForm
│   │   │   ├── index.tsx
│   │   │   └── validation.ts
│   │   └── CommentsDrawer.tsx
│   └── index.ts
└── post
    ├── api
    │   ├── api.ts
    │   ├── queries.ts
    │   └── type.ts
    └── components
        ├── Feed
        │   ├── index.tsx
        │   └── PostCard.tsx
        ├── PostAddForm
        │   ├── helpers.ts
        │   ├── index.tsx
        │   ├── type.ts
        │   └── validation.ts
        └── PostEditForm
            ├── helpers.ts
            ├── index.tsx
            ├── type.ts
            └── validation.ts

You want to open the API types for the post feature src/features/post/api/type.ts, just type "posttype" and you get what you want! (nearly)

And that's one of the reasons why I like a feature-based, colocated file structure rather than one by layers (MVC), my reason is that a feature-based approach is more intuitive when trying to find a file, you type post and processed to narrow the search the more you type.

This also works really well with a file-system based routing (Next.js, Expo...), just type a segment or two of the route you want and you would find your file.

If you aren't already using quick navigation, start using it! I hope I was able to convince you to do so, it's quite the game changer, so try to get yourself comfortable with it!

RegEx Search and Replace

This is helpful when you're changing a lot of similar lines of code repeatedly, for example, I use this when I'm changing my imports from static import:

import Page from "src/page";

To React's lazy import:

const Page = lazy(() => import("src/page"));

There is only two parts that are changing, the import name and the import string, easy to automate with regex.

Let's write the search regex:

import (.*) from "(.*)"

And what to replace it with:

const $1 = lazy(() => import("$2"))

And We can do it in reverse too! Lazy to static:

You may be thinking that it's cumbersome to do this every time you need to replace a bunch of lines (who wants to write regex?🫠), and I agree with that, so I save the search and replace strings on my notes app and copy-paste them when needed. If you find yourself doing something similar repeatedly, maybe you can automate it with a regex.

Read this section in the documentation to see another example, and while you are there, read the whole page!

Tasks

Lots of tools exist to automate tasks like linting, building, packaging,
testing, or deploying software systems. Examples include the TypeScript Compiler,
linters like ESLint and TSLint as well as build systems like Make, Ant, Gulp, Jake, Rake, and MSBuild.

⋮

Given their importance in the development life cycle, it is helpful to be able to run tools and analyze their results from within VS Code.

I think the most common usage of vscode tasks is starting a dev server or a build, which is how I use them, but with "runOn": "folderOpen" option in .vscode/tasks.json, which is really cool!

My day to day work always include:

opening the project workspace.
starting the dev server.
opening localhost.

I found it annoying to always run the dev server manually, as usually whenever I open the workspace for the project, I'll also start the dev server, and here where tasks can help, this is a tasks.json I use for one of my projects:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Types generation",
      "type": "shell",
      "command": "pnpm",
      "args": ["swagger"],
      "group": "none",
      "presentation": {
        "reveal": "never",
        "panel": "dedicated",
        "focus": false
      },
      "runOptions": {
        "runOn": "folderOpen"
      }
    },
    {
      "label": "Development",
      "type": "shell",
      "command": "pnpm",
      "args": ["dev"],
      "group": "none",
      "presentation": {
        "reveal": "always",
        "panel": "dedicated",
        "focus": false
      },
      "runOptions": {
        "runOn": "folderOpen"
      }
    }
  ]
}

As for "reveal": "always", this one for opening the terminal panel after running the task, which is nice if you want to click on the localhost link or you want to see some sort of result.

I would use "reveal": "never" if I don't care about the results of the command, for example, I generate swagger types using orval.dev on every folder open, but I want this to run in background as it's not that important, so I use "reveal": "never" for it.

Please checkout the documentation to see all options.

Honorable Mentions

While I said this won't be an exhaustive list for vscode tips and shortcuts, I think the following shortcuts aren't used as much as I think they should be.

Smart code selection

I always use it, and I feel annoyed when I'm typing something outside of vscode and try to use the shortcut out of habit, just look at this:

Select Matches

Ctrl + D for selecting the next Find Match and Ctrl + Shift + L for selecting all occurrences of Find Match.

Okay, that's it!

Till next time 👋

Understanding how let declaration work in for loop

Islam Naasani — Sun, 31 Dec 2023 17:07:53 +0000

The Problem

To start of, you probably come across this before:

for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), i * 100);
}
// 0
// 1
// 2

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), i * 100);
}
// 3
// 3
// 3

And you may just thought that this was some of the quirks of var and why you should only use let, but what is actually happening here?

A Deeper Look

While the code above is asynchronous, this issue isn't related to that, we can recreate it it in plain functions:

let logs = [];
for (var i = 0; i < 3; i++) {
  logs[i] = () => console.log(i);
}
logs[0](); // 3
logs[1](); // 3
logs[2](); // 3

It's all about closure and how let and var behave inside for.

Before continuing, a quick refresh of closure from MDN:

A closure is the combination of a function bundled together (enclosed) with references to its surrounding state (the lexical environment). In other words, a closure gives you access to an outer function's scope from an inner function. In JavaScript, closures are created every time a function is created, at function creation time.

if closure is a new concept to you please read the previous documentation page before continuing this post.

Now back to our example, it looks like let behavior above is intuitive and expected at first look but it's actually the one behaving against what should happen from a closure perspective, because according to how closure works, all those functions (seems to) reference the same variable i (closure is a live link, not a snapshot of variables) which means that after finishing all the iterations i value is 3, and it would make sense for each call after that to also log 3, but that's not the case. To prove that, we are going to declare i outside the for:

let i;
for (i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), i * 100);
}
// 3
// 3
// 3

Hmmm... seems like this is related to the scope of i.

How let declaration works in loops

At first glance, i in for(let i = 0;...) seems to be in an outer scope, not in the scope of the loop, but it's actually in the scope of the loop, it make sense to think about how for work like this:

{
  // a fictional variable for illustration
  let $$i = 0;
  for (; /* nothing */ $$i < 3; $$i++) {
    // here's our actual loop `i`!
    let i = $$i;
    setTimeout(() => console.log(i), i * 100);
  }
  // 0
  // 1
  // 2
}

Because let is block-scoped and it's in the scope of for, the variable i gets a new binding for each iteration, making it behave intuitively rather than what would you think would happen if you thought about i having only one binding.

In contrast, var is function-scoped and using it inside for would still place it in the outer scope (global scope in the example), or placing let declaration outside of the for body, in both cases, we only get one binding and it is to be expected to get the last value of i, as variables from closure are a live link of their values, not a snapshot in time.

Wrapping Up

While I don't think this gotcha would really cause any problems normally, as this what would you expect to happen when using for loops (in every iteration, i hold the same value (same binding) regardless of when it's executed) and nobody uses var anymore, not for loops at least, I still think it's good to understand how let work in and outside for, maybe for some reason you had to declare i outside of the for loop and got stuck on why it' holding the last i value.

This post relied heavily on the incredible book: You Don't Know JS Yet: Scope & Closures by Kyle Simpson, the book goes really deep into scope and closure, what are they, common pitfalls and how to benefit from them.

Using cva (Class Variance Authority) to scale TailwindCSS

Islam Naasani — Sun, 17 Dec 2023 15:41:37 +0000

While TailwindCSS is a great styling solution, it has a scalability issue and it may quickly go out of hand when writing huge components with a lot of different states. Even when using clsx utility it's still hard to maintain and extend, and this is when cva (Class Variance Authority) library shines.

If you are using shadcn/ui—which is a fantastic component library, by the way—then you're already using cva, shadcn/ui uses it for managing different component states and configurations, for example, the button component has multiple variants (default, secondary, outline...), if you try to implement it by doing conditions manually, the code will quickly start to look ugly and hard to extend, but with cva, it's quite simple!

let's try to write the same component with those three ways: no-libraries, with clsx, and with cva.
No-libraries:

export const Button = ({ variant = "default", className, ...props }) => {
  return (
    <button
      {...props}
      className={`inline-flex items-center justify-center ${
        variant === "default" ? " bg-primary text-primary-foreground hover:bg-primary/90" : ""
      }${
        variant === "secondary"
          ? "bg-secondary text-secondary-foreground hover:bg-secondary/80"
          : ""
        // ...
      } ${className}`}
      // 🟥 Hard to maintain and looks ugly.
    />
  );
};

clsx:

export const Button = ({ variant = "default", className, ...props }) => {
  return (
    <button
      {...props}
      className={clsx(
        "inline-flex items-center justify-center",
        variant === "default" && " bg-primary text-primary-foreground hover:bg-primary/90",
        variant === "secondary" && "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        // ...
        className
      )}
      // 🟧 More readable but still not very scalable.
    />
  );
};

And now with cva!:

const buttonVariants = cva("inline-flex items-center justify-center", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground hover:bg-primary/90",
      secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
    },
    size: {
      default: "h-10 px-4 py-2",
      sm: "h-9 rounded-md px-3",
      lg: "h-11 rounded-md px-8",
    },
  },
  defaultVariants: {
    variant: "default",
    size: "default",
  },
  // 🟩 Readable and pretty easy to maintain and scale.
});
export const Button = ({ variant, size, className, ...props }) => {
  return <button {...props} className={buttonVariants({ variant, size, className })} />;
};

Reference

Implementing an iterable linked list in JavaScript (can be used with spread operator (...) or a for...of)

Islam Naasani — Sat, 09 Dec 2023 10:34:46 +0000

In this post we are going to build a linked list in JavaScript that is iterable, which means it can be used in a for...of or with the spread operator (...) or by anything that takes an iterable

Iterable
Iterator
Implementing the linked list
Making the linked list iterable
Conclusion
- Reference

Iterable

To start off, what does iterable mean exactly?
from MDN:

The iterable protocol allows JavaScript objects to define or customize their iteration behavior, such as what values are looped over in a for...of construct.

Meaning anything that can be used by APIs that accepts iterables, e.g., Array.from() or syntaxes that expects iterables, e.g. for...of

So Array is an iterable, so is Map, you can find all the built-in iterables here.

But what makes an object iterable? again from MDN:

In order to be iterable, an object must implement the @@iterator method, meaning that the object (or one of the objects up its prototype chain) must have a property with a @@iterator key which is available via constant Symbol.iterator

So any object that have [Symbol.iterator] method implemented can be called iterable, cool!

Iterator

Okay, we need a method named [Symbol.iterator] in our object to be iterable, but what should this method contain? it must return an object that implements a next() method that also return an object that implements the IteratorResult interface:

interface IteratorResult {
  done?: boolean;
  value?: any;
}

Now that's a lot to take in, let's take a break and start implementing our linked list before making it iterable.

Implementing the linked list

If you aren't familiar with the term, linked list is a data structure that do the same things as arrays——storing a series of values——the difference is, instead of storing the elements in contiguous locations (a[0], a[1], ...) they are stored in different locations and each element (node) point to the address of the next element.

This is a very basic implementation of a linked list:

class Node {
  next = null;
  constructor(value) {
    this.value = value;
  }
}

class LinkedList {
  head = null;
  last = null;
  add(value) {
    var node = new Node(value);
    if (this.head == null) {
      this.head = node;
      this.last = node;
    } else {
      this.last.next = node;
      this.last = this.last.next;
    }
  }
}

const list = new LinkedList();
list.add(1);
list.add(2);
list.add(3);
list.add(4);
// list currently have 4 elements: 1 -> 2 -> 3 -> 4

Of course there is more methods in a linked list (find, remove...), you can read more about linked lists here: Understanding the basics of Linked List

Making the linked list iterable

Now, how to make our list iterable? let's first add the [Symbol.iterator] method:

class LinkedList {
  head = null;
  last = null;
  add(value) {
    var node = new Node(value);
    if (this.head == null) {
      this.head = node;
      this.last = node;
    } else {
      this.last.next = node;
      this.last = this.last.next;
    }
  }
  [Symbol.iterator]() {
    // to implement
  }
}

This syntax may seem weird but you have probably already used it before:

let variable = "key";
const x = {
  [variable]: "value",
};
console.log(x.key);
// value

The method should be an iterator, so it needs to return an object that have a next() method which in turn should return an object that follows the IteratorResult interface:

[Symbol.iterator]() {

  return {
    next: () => {
      return { done: undefined, value: undefined }
    },
  };
}

Now we will add the logic: advance in the list and return the current node value until the current node becomes null then we will return done: true

[Symbol.iterator]() {
  let current = this.head;
  return {
    next: () => {
      if (current != null) {
        let currentValue = current.value;
        current = current.next;
        return {
          value: currentValue,
          done: false,
        };
      } else {
        return { value: undefined, done: true };
      }
    },
  };
}

And now we have an iterable linked list!

full implementation:

class Node {
  next = null;
  constructor(value) {
    this.value = value;
  }
}

class LinkedList {
  head = null;
  last = null;
  add(value) {
    var node = new Node(value);
    if (this.head == null) {
      this.head = node;
      this.last = node;
    } else {
      this.last.next = node;
      this.last = this.last.next;
    }
  }
  [Symbol.iterator]() {
    let current = this.head;
    return {
      next: () => {
        if (current != null) {
          let currentValue = current.value;
          current = current.next;
          return {
            value: currentValue,
            done: false,
          };
        } else {
          return { value: undefined, done: true };
        }
      },
    };
  }
}

const list = new LinkedList();
list.add(1);
list.add(2);
list.add(3);
list.add(4);

console.log(...list);
// 1 2 3 4

console.log(Array.from(list));
// [1, 2, 3, 4]

for (const element of list) {
  console.log(element);
}
// 1
// 2
// 3
// 4

Conclusion

We've seen how iteration protocols aren't something built-in or a syntax from the language, but are just that, protocols, hence we can benefit from them by implementing them in data structures and classes written by us, as we've achieved by modifying the LinkedList class to be able to work with APIs and syntaxes that take iterables (for...of).