DEV Community: Gohomewho

Improve User Experience with a Minimal Loading State: A Vue Composable for Making Delay Ref

Gohomewho — Sun, 26 Feb 2023 03:55:26 +0000

Fetching resources and displaying a loading UI is a common task when building Vue applications. One simple approach is to use v-if="data" and v-else to toggle the UI, but this can become problematic if the APIs you're working with respond too quickly. In such cases, the loading UI may flash briefly and distract users, creating a poor user experience.

While working recently, I encountered a situation where the APIs I was using became extremely fast after a colleague moved them to AWS. As a result, the flashing of the loading UI became too noticeable and disruptive for users. To solve this problem, I created a composable.

What is a composable

In the context of Vue applications, a "composable" is a function that leverages Vue's Composition API to encapsulate and reuse stateful logic.

My implementation

My initial plan was to create a ref exclusively for tracking the loading state. However, I thought that it would be more versatile if we could manipulate its value instead of merely using a boolean.

export function refMinDelay(
  sourceRef,
  delay,
  conditionToDoSomethingImmediate = newValue => newValue === true,
  doImmediate = newValue => true,
  doAfterDelay = newValue => false,
) {
  let timeId = 123
  const delayRef = ref(sourceRef.value)

  watch(sourceRef, () => {
    if (conditionToDoSomethingImmediate(sourceRef.value) === true) {
      clearTimeout(timeId)

      delayRef.value = doImmediate(sourceRef.value)

      timeId = setTimeout(() => {
        timeId = null

        if (conditionToDoSomethingImmediate(sourceRef.value) === true)
          return

        delayRef.value = doAfterDelay(sourceRef.value)
      }, delay)
    }
    else {
      if (timeId)
        return

      delayRef.value = doAfterDelay(sourceRef.value)
    }
  }, {
    immediate: true,
  })

  return delayRef
}

The refMinDelay function takes in a sourceRef, a delay time in milliseconds, and optional parameters conditionToDoSomethingImmediate, doImmediate, and doAfterDelay. It returns a reactive delayRef that is updated based on the sourceRef updates and the specified delay.

If the sourceRef updates and the conditionToDoSomethingImmediate function evaluates to true, the delayRef will be immediately updated to the return value of the doImmediate function. If conditionToDoSomethingImmediate evaluates to false, the delayRef will only update to the return value of the doAfterDelay function if the specified delay has passed. if the delay has not yet passed, the update will be deferred until the minimal delay is up.

If sourceRef is a boolean loading state, the default values for conditionToDoSomethingImmediate, doImmediate, and doAfterDelay are provided to create a delay loading state. For example, refMinDelay(loading, 500) will create a delay loading state with a 500ms delay.

When to use

When fetching data and displaying a loading UI, frequent switches between the loading UI and the data display can cause the screen to flash, which can disrupt the user's experience. To create a smoother transition, a minimal loading state can be used to delay the switch from the loading UI to the data display until a minimal delay has passed, ensuring that the loading state is visible for at least that duration.

How to use

Create a delay loading state from an existing loading state.

const loading = ref(false)
const delayLoading = refMinDelay(loading, 500)

Create a delay loading state from a prop.

const data = computed(() => props.data)
const delayLoading = refMinDelay(data, 500, (value) => value == null)

Create a delay state of the source.

const source = ref({ id: 1})
const delay = refMinDelay(
  source,
  500,
  (v) => v == null, /* condition to set value immediately */
  (v) => v, /* set value immediately  */
  (v) => v /* set value once minimal delay is up*/
);

Example

You can play the example on stackblitz or use the embedded version below. Click the +1 button at different speeds and adjust the delay values for both delayLoading and responseTime to see different results.

To learn how refMinDelay works, right-click an element and select "inspect", go to the console tab, and check what's logged from refMinDelay.js.

If the API is very fast, the loading UI will still be shown until the minimum delay time has elapsed. For example, responseTime takes 100ms and delayLoading is set to 300ms.

If the API takes longer than the delay to respond, there will be no additional delay. For example, responseTime takes 500ms and delayLoading is set to 300ms.

table: make columns resizable

Gohomewho — Sun, 22 Jan 2023 09:18:29 +0000

In this series, we will make our table columns resizable. This time I won't show everything step by step. You can take this as an challenge to do on your own, and watch my solution if you get stuck. Maybe you'll come up with better solution!

The code before and after

How to add a feature

We've been making column swappable. Now, we want to add another feature "resizable". Can they work together? Do we need to change other code to adopt this feature? We probably don't have straight answers until really implement it. But asking these questions to ourselves can help us make better decisions.

To resize a column, we need to add a handle for user to interact with. So besides column name, there should be a resize handler. This means the structure of the column will be different than createTableHead which only render column name. we will need to make a new function to create this structure.



function createResizableTableHead(columns, options = {}) {
  const {
    // settings for individual column's min width
    columnsMinWidth,

    // settings for individual column's label 
    // e.g. the column key from database is firstName
    // but we won't show that directly to end user
    // so we make a mapping like 'firstName' -> 'first name'
    columnsLabel = {}
  } = options

  const thead = document.createElement('thead')
  const tr = document.createElement('tr')

  columns.forEach(columnKey => {
    const th = document.createElement('th')
    // save column name on the element,
    // so we know which column a element represents
    th.dataset.columnKey = columnKey

    // set display: flex; on `th` would break
    // the table layout algorithm
    // so we need a wrapper `div` to do that
    const wrapper = document.createElement('div')
    wrapper.classList.add('resizable-column-wrapper')
    th.appendChild(wrapper)

    const content = document.createElement('div')
    const resizeHandle = document.createElement('div')
    content.classList.add('resizable-column-content')
    resizeHandle.classList.add('resizable-column-handle')
    // here we simply add text to a div
    // but we can also make a column formatter
    // similar to what we did for `createTableRow`
    // if we need more complex markup
    content.textContent = columnsLabel[columnKey] || columnKey

    wrapper.append(content, resizeHandle)
    tr.appendChild(th)
  });

  makeColumnsResizable(tr, { columnsMinWidth })

  thead.appendChild(tr)
  return thead
}

The overall structure of makeColumnsResizable is very similar to makeColumnsSwappable. We would want them to work together. We would also want to make the logic consistent.



function makeColumnsResizable(columnsContainer, options = {}) {
  const {
    // elements to resize together with the target column
    elementsToPatch = [],
    // setting of each column min width
    columnsMinWidth = {},
    // default value of each column min width
    DEFAULT_MIN_COLUMN_WIDTH = 100
  } = options

  columnsContainer.classList.add('resizable-columns-container')
  const _elementsToPatch = [columnsContainer, ...elementsToPatch]

  const columnElements = [...columnsContainer.children]
  columnElements.forEach((column) => {
    column.classList.add('resizable-column')
    const minWidthSetting = columnsMinWidth[column.dataset.columnKey]
    if (minWidthSetting) {
      // set width does not work on table because
      // it has built-in layout algorithm
      column.style.minWidth = minWidthSetting + 'px'
      // we are still setting width because
      // `makeColumnsResizable` is not made specifically for table
      column.style.width = minWidthSetting + 'px'
    }
  })

  columnsContainer.addEventListener('pointerdown', e => {
    // because we use event delegation pattern,
    // `e.target` could be other irrelevant elements
    // so we need to make sure that the event
    // is triggered by a resize handle
    const resizeHandle = e.target.closest('.resizable-column-handle')
    if (!resizeHandle)
      return

    // stop event propagation so we don't trigger resize
    // and swap at the same time. this is used with
    // { capture: true } to make sure this event handler has 
    // higher priority and don't propagate to others.
    // it is also possible to use e.stopImmediatePropagation()
    // in this case because this event listener of 'pointerdown'
    // is added before the one from `makeColumnsSwappable`
    e.stopPropagation()

    const column = e.target.closest('.resizable-column')
    const indexOfColumn = [...columnsContainer.children].indexOf(column)
    const minColumnWidth = 
columnsMinWidth[column.dataset.columnKey] || DEFAULT_MIN_COLUMN_WIDTH

    // prevent text selection when moving columns
    document.addEventListener('selectstart', preventDefault)

    const initialColumnWidth = parseFloat(getComputedStyle(column).width)
    const initialCursorX = e.clientX

    // elements that are in the same column
    const elementsToResize = _elementsToPatch.map((columnsContainer) => {
      return columnsContainer.children[indexOfColumn]
    })

    // calculate how much to resize
    function handleMove(e) {
      const newCursorX = e.clientX
      const moveDistance = newCursorX - initialCursorX
      let newColumnWidth = initialColumnWidth + moveDistance

      // we don't want to resize column width below its
      // minimal value so if `newColumnWidth` is lower than
      // `minColumnWidth` we want to use `minColumnWidth`, which 
      // value would be the "bigger" one of Math.max()
      newColumnWidth = Math.max(newColumnWidth, minColumnWidth)

      // if we need to frequently update UI, use
      // `requestAnimationFrame` to make it optimal
      requestAnimationFrame(() => {
        elementsToResize.forEach((element) => {
          element.style.minWidth = newColumnWidth + 'px'
          element.style.width = newColumnWidth + 'px'
        })
      })
    }

    document.addEventListener('pointermove', handleMove)

    // clean up event listeners
    document.addEventListener('pointerup', e => {
      document.removeEventListener('pointermove', handleMove)
      document.removeEventListener('selectstart', preventDefault)

      // this clean up listener only needs to run once
      // after 'pointerdown'
    }, { once: true })

    // capture of 'pointerdown' is used with e.preventDefault()
    // as mentioned above
  }, { capture: true })
}

If you don't know what is event propagation and event delegation, and what e.stopPropagation() and { capture: true } do. Check out my addEventListener tutorial may help.

Some CSS for resizable column.



.resizable-column-wrapper {
  /* make its content layout horizontally */
  display: flex;
}

.resizable-column-content {
  /* makes this element can grow and shrink 
     within the free space of flexbox */
  flex: 1;

  text-align: left;
  padding: 8px;
}

.resizable-column-handle {
  width: 20px;
  background: rgba(255, 0, 0, 0.154);
  cursor: col-resize;

  /* makes this element not to shrink */
  flex-shrink: 0;
}

Update createTable to be able to create a table of resizable and swappable columns through options.



import { makeColumnsResizable } from "./makeColumnsResizable.js"
import { makeColumnsSwappable } from "./makeColumnsSwappable.js"

export function createTable(columns, dataList, options = {}) {
  const {
    columnFormatter = {},
    resizeOptions = {},
    swapOptions = {},
  } = options

  const table = document.createElement('table')

  // create resizable structure if resize option is enable
  const thead = resizeOptions.enable
    ? createResizableTableHead(columns, resizeOptions)
    : createTableHead(columns)
  const tbody = createTableBody(columns, dataList, columnFormatter)
  table.append(thead, tbody)

  // make columns swappable if swap option is enable
  if (swapOptions.enable) {
    const columnsContainer = table.querySelector('thead').firstElementChild
    const elementsToPatch = table.querySelectorAll('tbody > tr')
    makeColumnsSwappable(columnsContainer, elementsToPatch)
  }

  return table
}

We can create a table like this.



// const users = [...]
// const nameOfDefaultColumns = [...]
// const columnFormatter = [...]

createTable(nameOfDefaultColumns, users, {
  columnFormatter,
  resizeOptions: {
    enable: true,
    columnsMinWidth: {
      id: 50
    }
  },
  swapOptions: {
    enable: true,
  },
})

There are more to consider

The code above should already work, but it doesn't work well. We can resize columns. What happens if total columns width is larger than the container. We need to make some changes to makeColumnsSwappable.

We would want ghost to stay within the container.



function getGhostBoundary() {...}

What about scroll? We need a way to scroll the container.



function getScrollContainerFunc() {...}

And decide when to scroll. moveGhost handles the logic that ghost touches the edges, so we can also make it start the scroll.



function moveGhost() {...}

Then, how to swap after auto scrolling? Some code from handleMove is doing that job. We need to extract it out to reuse it.



function handleSwap() {...}

Do we want to pass handleSwap all the way down to getScrollContainerFunc from createGhostColumn? Or there is other way to do it? I think handleSwap is more reasonable to be called directly inside makeColumnsSwappable. So I use a custom event to notify the universe that I just auto scroll.



// inside `startScroll` 
const event = new CustomEvent('custom:autoscroll', {
  detail: {
    direction,
    predicateGhostEdgeX
  }
})
ghost.dispatchEvent(event)

We can addEventListener to ghost on that custom event inside makeColumnsSwappable to handleSwap. This flow is more clear to me.



// inside `makeColumnsSwappable`
ghost.element.addEventListener('custom:autoscroll', (e) => {
  const { direction, predicateGhostEdgeX } = e.detail

  handleSwap({
    isMoveToLeft: direction === 'left',
    isMoveToRight: direction === 'right',
    ghostLeft: predicateGhostEdgeX.left,
    ghostRight: predicateGhostEdgeX.right
  })
})

There are other pieces to consider, but these are the big picture.

The result of my solution. The ghost should stay within the content box area of the container. Auto scroll should swap as well.

Note that we don't need to pass elementsToPatch to makeColumnsResizable in this case, because browser will adjust columns width with its table algorithm. Another thing to note is that the table algorithm prevent the content to overflow. Resizing to a width that is too small won't take effect. To make makeColumnsResizable also work on other tags e.g. a bunch of div, The content of columns should be aware of potential overflow and handled with line clamp.

I have added as much as possible comments to the source code for this section. If you are still confused, feel free to leave a comment below.

table: animate swapping columns

Gohomewho — Sat, 31 Dec 2022 17:34:32 +0000

Currently, when columns swap, they swap instantly.

In this series, we are going to add animation to make it look nicer. First, let's think about how we are going to implement it. When we swap columns, we can't update them immediately. We need to calculate how to animate them and update their DOM orders once the animation ends. It seems to work, but does it work in all situations? What if we swap very fast before the previous swapping ends? Since their DOM orders don't update until animation ends and we heavily rely on their indexes to swap columns, it is hard to tell if this will work without really testing it out.

We can give it a try when we have a thought, but it seems a lot of work to do and doesn't guarantee to work. We can think if there are other solutions before jumping right into it.

Let's think an alternative. What if we update columns immediately just like we've done but add animation to them later? This way, their DOM orders will be correct. Their indexes will be correct. Which means that swapping will still be correct. But how do we apply animation? We are no longer animating columns "TO" their new positions. We will need to animate columns "FROM" their old positions. This solution seems to be easier, so we will go this route. We can apply the animation by using a technique called FLIP.

To do FLIP, we need to calculate the amount to invert from new position to old position, so the element will look like it is moving from old position to new position. We can use .getBoundingClientRect() before and after swap to help us calculate how much to invert.

The code we have so far.

makeColumnsSwappable.js

// already got `firstTargetRect` somewhere
const firstTargetRect = firstTarget.getBoundingClientRect()

// ...

function handleMove(e) {
  // ...

  const secondTarget = document.elementFromPoint(newCursorX, lockedY)
  const secondTargetIndex = columnElements.indexOf(secondTarget)
  // when we get `secondTarget ` on "pointermove"
  // save its rect infomation
  const secondTargetRect = secondTarget.getBoundingClientRect()

  // ...

  swapColumns(columnsContainer, swapColumnInfo)

  elementsToPatch.forEach((columnsContainer) => {
    swapColumns(columnsContainer, swapColumnInfo)
  })

  // after swapColumns(columnsContainer, swapColumnInfo)
  // `firstTarget` and `secondTarget` will be on new position
  // so we use `.getBoundingClientRect()` again to get the 
  // newest rect information
  const newFirstTargetRect = firstTarget.getBoundingClientRect()
  const newSecondTargetRect = secondTarget.getBoundingClientRect()

  // old position subtract new position will be 
  // the amount to invert
  const firstTargetInvert = firstTargetRect.x - newFirstTargetRect.x
  const secondTargetInvert = secondTargetRect.x - newSecondTargetRect.x
}

After having firstTargetInvert and secondTargetInvert, we can FLIP columns with Element.animate()

// follow right after the code above

// animate firstTarget
firstTarget.animate([
  // from old position
  { transform: `translateX(${firstTargetInvert}px)` },
  // to new position
  { transform: `translateX(0px)` },
], {
  easing: 'ease-in-out',
  duration: 1000
})

// animate secondTarget
secondTarget.animate([
  // from old position
  { transform: `translateX(${secondTargetInvert}px)` },
  // to new position
  { transform: `translateX(0px)` },
], {
  easing: 'ease-in-out',
  duration: 1000
})

The animation doesn't look right. The columns flash like the bug we fixed in series 3.

This is because that we only checked how to swap column inside swapColumns function. We didn't check if we need to call swapColumns at all. Then we animate columns right after calling swapColumns without confirming do we really need to animate columns. The flashes tell us that some code is being run unnecessary frequently. So, we should add more check points before the code can reach swapColumns and animation.

function handleMove(e) {
  // ...

  // we checked if we got a correct `secondTarget`
  if (secondTargetIndex === -1)
    return

  // we checked if `firstTarget` and `secondTarget` are the same
  if (firstTarget === secondTarget)
    return

  // sometimes we only shift cursor vertically a little
  // that would also trigger "pointermove"
  // since we only care about moving left or right
  // we can make a condition to stop this unnecessary reaction
  if (newCursorX === lastCursorX)
    return

  const isMoveToLeft = newCursorX < lastCursorX
  const isMoveToRight = newCursorX > lastCursorX
  lastCursorX = newCursorX

  // add another check that we don't need to do anything 
  // if cursor is moving towards left but `secondTarget` is 
  // already on the right side of `firstTarget` or if cursor is 
  // moving towards right but `secondTarget` is already on the 
  // left side of `firstTarget`
  if (isMoveToLeft && secondTargetIndex > firstTargetIndex
    || isMoveToRight && secondTargetIndex < firstTargetIndex)
    return

  // ...
}

The flash is gone. But there is another problem revealed. The firstTarget column always animates from its initial position.

Let's use the latest firstTargetRect from handleMove.

function handleMove(e) {
  // ...

  // get `firstTargetRect` inside `handleMove`
  const firstTargetRect = firstTarget.getBoundingClientRect()
  const secondTargetRect = secondTarget.getBoundingClientRect()

  // ...
}

This fix the problem.

There is still an issue if you watch closely. If we swap firstTarget with another column before the previous animation ends, the firstTarget will take a leap. There are good news and bad news to this. The bad news is that I don't think there is a simple solution to this. Luckily, the good news is that we don't need that much animation duration. This is just a nice to have feature, so let's cut down the animation duration to 150ms.

I don't know you but this looks pretty amazing to me :D

If someone moves cursor really fast, there will still have leaps. But it will be neglectable because if someone moves cursor too fast, they won't notice the leaps because their eyes can't keep up with the speed. I think this is the situation where we can compromise rather than adding more complexity.

Currently, we only animate the columns of the header section. Let's animate the elements in the same columns all together.

// we can put this function at the bottom of
// makeColumnsSwappable.js because it doesn't rely other states 
// created inside `makeColumnsSwappable`
function animateSwap({
  columnsContainers,
  firstTargetIndex,
  secondTargetIndex,
  firstTargetInvert,
  secondTargetInvert
}) {
  // create a function to animate columns
  function animate(element, invert) {
    element.animate([
      { transform: `translateX(${invert}px)` },
      { transform: `translateX(0px)` },
    ], {
      easing: 'ease-in-out',
      duration: 150
    })
  }

  // this is similar to how `swapColumns` works
  // we use indexes to get `firstTarget` and `secondTarget`
  // from the list of columns
  columnsContainers.forEach((columnsContainer) => {
    const columns = columnsContainer.children
    const firstTarget = columns[firstTargetIndex]
    const secondTarget = columns[secondTargetIndex]

    animate(firstTarget, firstTargetInvert)
    animate(secondTarget, secondTargetInvert)
  })
}

Use animateSwap inside handleMove.

function handleMove(e) {
  const newCursorX = e.clientX
  let newGhostX = newCursorX + pointerOffset.x

  if (newGhostX < ghostXBoundary.min)
    newGhostX = ghostXBoundary.min
  else if (newGhostX > ghostXBoundary.max) {
    newGhostX = ghostXBoundary.max
  }

  ghost.style.left = newGhostX + 'px'

  const secondTarget = document.elementFromPoint(newCursorX, lockedY)
  // change `const` to `let`
  let secondTargetIndex = columnElements.indexOf(secondTarget)

  if (secondTargetIndex === -1)
    return

  if (firstTarget === secondTarget)
    return

  if (newCursorX === lastCursorX)
    return

  const isMoveToLeft = newCursorX < lastCursorX
  const isMoveToRight = newCursorX > lastCursorX
  lastCursorX = newCursorX

  if (isMoveToLeft && secondTargetIndex > firstTargetIndex
    || isMoveToRight && secondTargetIndex < firstTargetIndex)
    return

  const firstTargetRect = firstTarget.getBoundingClientRect()
  const secondTargetRect = secondTarget.getBoundingClientRect()

  const swapColumnInfo = {
    firstTargetIndex,
    secondTargetIndex,
    isMoveToLeft,
    isMoveToRight,
  }

  swapColumns(columnsContainer, swapColumnInfo)

  elementsToPatch.forEach((columnsContainer) => {
    swapColumns(columnsContainer, swapColumnInfo)
  })

  // we want to use indexes to get elements for animation
  // so we need to update `firstTargetIndex` and `secondTargetIndex`
  // after columns swap
  columnElements = [...columnsContainer.children]
  firstTargetIndex = columnElements.indexOf(firstTarget)
  secondTargetIndex = columnElements.indexOf(secondTarget)

  // calculate invert
  const newFirstTargetRect = firstTarget.getBoundingClientRect()
  const newSecondTargetRect = secondTarget.getBoundingClientRect()
  const firstTargetInvert = firstTargetRect.x - newFirstTargetRect.x
  const secondTargetInvert = secondTargetRect.x - newSecondTargetRect.x

  // we can use the information we get from `firstTarget` 
  // and `secondTarget` of header section, because the elements in 
  // the same column have the same structure.
  animateSwap({
    columnsContainers: [columnsContainer, ...elementsToPatch],
    firstTargetIndex,
    secondTargetIndex,
    firstTargetInvert,
    secondTargetInvert,
  })
}

Awesome!

We can add a little style to the firstTarget column to make it feel less prominent because we have a ghost column representing it.

makeColumnsSwappable.css

/* hide text */
.column.moving.hide-content {
  color: transparent;
}

/* hide child elements */
.column.moving.hide-content * {
  opacity: 0;
}

We need to add .hide-content class to firstTarget after we have created ghost. Otherwise, the style from .hide-content would also be cloned to the ghost, thus we won't be able to see the content inside ghost.

makeColumnsSwappable.js

const ghost = createGhost()
// add style to hide `firstTarget` content after we have created ghost
firstTarget.classList.add('hide-content')

Clean up .hide-content class after we've done moving.

document.addEventListener('pointerup', () => {
  // ...
  firstTarget.classList.remove('moving')
  // clean up `.hide-content`
  firstTarget.classList.remove('hide-content')
}, { once: true })

Now we get rid of duplicate column names and the UI becomes more cleaner.

One thing you might notice is that the borders don't respect our animation, they flip instantly. I found that it's again a problem caused by setting border-collapse: collapse. We can walk around like this.

Use box-shadow to act like a border. We use inset because I found that the box-shadow will disappear during animation.

my-table {
  border-collapse: collapse;
}

.my-table th,
.my-table td {
  padding: 8px;
  box-shadow: inset 0px 0px 0px 1px lightgray;
}

We can confirm that this is a problem caused by border-collapse: collapse by removing its declaration.

/* .my-table {
  border-collapse: collapse;
} */

.my-table th,
.my-table td {
  padding: 8px;
  border: 1px solid lightgray;
}

After removing border-collapse, there are small gaps between table cells, and the borders are animated.

This is only an issue that we use table and directly insert data to th and td as an example. Remember that makeColumnsSwappable(columnsContainer, elementsToPatch) should work on any columns structured element. In a real world scenario, we would have more complex markup inside columnsContainer and elementsToPatch. If we are dealing with table, we can move the border style from th and td to their descendants. If we are not dealing with table, we don't need to worry about this.

Here is the code after I made some refactor. One thing to note is that I change the logic to calculate pointerOffset because its logic was reversed and not so intuitive.

table: improve moving column UI & UX (2)

Gohomewho — Sat, 24 Dec 2022 09:49:49 +0000

We added a ghost column representing the moving column previously. It always follows our cursor in the entire window although the swapping functionality only happens in the header section.

While there is nothing wrong about it, we can still improve this feature to make it easier for use.

The code we have so far.

We can limit the ghost within the header area which tells users that the boundary of moving. In the meantime, we don't want to force users to control their pointers to stay within the header area. It might sound complicated to do this, but in fact we already did most of the job. We just need to modify something.

Currently, we set ghost initial position to overlap the column inside createGhost function, and we update ghost position in handleMove function on pointer move.

makeColumnsSwappable.js

columnsContainer.addEventListener('pointerdown', e => {]
  // ...

  function createGhost() {
    const ghost = firstTarget.cloneNode(true)
    copyElementStyleToAnother(firstTarget, ghost)
    ghost.style.position = 'fixed'
    ghost.style.pointerEvents = 'none'

    // we set ghost initial position to overlap the column
    ghost.style.left = e.clientX + pointerOffset.x + 'px'
    ghost.style.top = e.clientY + pointerOffset.y + 'px'

    document.body.appendChild(ghost)
    return ghost
  }

  const ghost = createGhost()

  function handleMove(e) {
    // we update ghost position on pointer move
    ghost.style.left = e.clientX + pointerOffset.x + 'px'
    ghost.style.top = e.clientY + pointerOffset.y + 'px'
    // ...
  } 

 // ...
}

Now we only want ghost column to stay in the header section. It should be able to move horizontally but not vertically. We have set ghost column initial x and y position correctly, which means that we only need to update its x on pointer move. Let's remove the code that change its y.

function handleMove(e) {
  ghost.style.left = e.clientX + pointerOffset.x + 'px'

  // this line change ghost vertical position
  // ghost.style.top = e.clientY + pointerOffset.y + 'px'

  // ...
}

Notice that now ghost column only moves within the header section even though our cursor doesn't stay precisely in the header section.

After this change, we would expect columns to swap when ghost column moves over another column. Currently, columns only swap if our cursor is in the header section. Because we use e.target from "pointermove" to get the secondTarget and we made sure we only swap columns if secondTarget is one of the columnElements. So we need to change how we get the secondTarget.

The logic is similar to how we move ghost column. We want to be able to move our cursor freely, but we use new x with a locked y to get the secondTarget. This means that we need a way to use x and y to get an element, and there is an API for it, which is Document.elementFromPoint(). If you have never seen Document.elementFromPoint(), I would encourage you to try to google what keywords you need to search to find this API. It is a good exercise that when you kind of know what to do but not exactly how to do.

We can get the locked y from "pointerdown".

columnsContainer.addEventListener('pointerdown', e => {
  // If `e.target` is able to get the correct `firstTarget`
  // `lockedY` should be able to get `secondTarget` 
  // because the columns stay on the same horizontal level
  const lockedY = e.clientY

  // ...

  // we a check here for `firstTarget`
  if (firstTargetIndex === -1)
    return

  // ...
}

Change how we get secondTarget from directly using e.target from "pointermove" to using the new e.clientX with locked y to get the target on that position.

function handleMove(e) {
  // ...

  const secondTarget = document.elementFromPoint(e.clientX, lockedY)

  // ...

It should work like this. We can swap columns without making cursor stay in the header section.

To quickly recap, We successfully make this change by removing the code that update ghost column y position, so ghost column stays on the same horizontal level.

// remove from `handleMove` function
ghost.style.top = e.clientY + pointerOffset.y + 'px'

We get lockedY on "pointerdown", so we can use elementFromPoint with this value to get a element from a point.

// added at the top of   
// columnsContainer.addEventListener('pointerdown', e => {
const lockedY = e.clientY

Lastly, we change how we get secondTarget.

// it was secondTarget = e.target
const secondTarget = document.elementFromPoint(e.clientX, lockedY)

It's not a surprise that with this small amount of change can make a huge difference. Because we have designed pretty clear how to swap columns by getting firstTarget and secondTarget. In this exmaple, we only change how we get the secondTarget. The value of secondTarget doesn't change, so everything should still work.

Currently, ghost column can move out of header section. It makes more sense to make ghost column only move within the area. To do that, we need to calculate the boundary that ghost column can move.

columnsContainer.addEventListener('pointerdown', e => {
  // get the position information of columns container
  const columnsContainerRect = columnsContainer.getBoundingClientRect()

  // ...

  function handleMove(e) {
    const newCursorX = e.clientX

    // new ghost `x` value
    let newGhostX = newCursorX + pointerOffset.x

    // if new `x` is over the left boundary of `columnsContainerRect`
    if (newGhostX < columnsContainerRect.x) {
      // we want to use the `x` value of `columnsContainerRect`
      // so ghost column doesn't move pass the left boundary
      newGhostX = columnsContainerRect.x
    }

    ghost.style.left = newGhostX + 'px'

    // ...
  }
}

Ghost column can no longer move pass the left boundary.

Next, let's deal with the right boundary. At first glance, we might want to calculate if the right edge of ghost column is over the right edge of columnsContainerRect. It's intuitive to think that way, but that will require more work. Since we use ghost.style.left to update ghost position, we can instead calculate a max value for left which can represents the limit that ghost column can move toward right.

Create a variable ghostXBoundary to store the information of ghost x boundary and use it to conditionally limit ghost position in handleMove.

const ghostXBoundary = {
  // the min value that ghost.style.left can set
  min: columnsContainerRect.x,

  // the max value that ghost.style.left can set
  // ghost column's width equals to `firstTargetRect.width` 
  // if you don't know how this work
  // try removing `- firstTargetRect.width` to see the difference
  max: columnsContainerRect.right - firstTargetRect.width
}

function handleMove(e) {
  const newCursorX = e.clientX
  let newGhostX = newCursorX + pointerOffset.x

  // conditions to change `newGhostX`
  // to limit ghost to stay in the boundary
  if (newGhostX < ghostXBoundary.min)
    newGhostX = ghostXBoundary.min
  else if (newGhostX > ghostXBoundary.max) {
    newGhostX = ghostXBoundary.max
  }

  ghost.style.left = newGhostX + 'px'

  // ...
}

Now ghost stays in the boundary.

One thing you might have noticed is that the ghost column position is slightly off. It's not perfectly stay in the header section.

When we see something like this, we can try to exaggerate the problem to help us inspect it. First, I want to enlarge the border size from 1px to 10px.

myTables.css

.my-table,
.my-table th,
.my-table td {
  border: 10px solid lightgray;
  border-collapse: collapse;
  padding: 8px;
}

We can see that the bug is exaggerated a little bit. Although it is not obviously what's going on, we can guess that border has some impact to this bug.

So next we can keep modifying other stuff related to borders. Let's comment out border-collapse: collapse;.

It seems like when we clone the styles from a column to ghost. It doesn't take that border collapse into account. We need to do that ourselves.

function createGhost() {
  const ghost = firstTarget.cloneNode(true)
  copyElementStyleToAnother(firstTarget, ghost)

  // cut borderWidth to half when ghost has border collapse style
  if (ghost.style.borderCollapse === 'collapse') {
    const halfBorderWidth = (parseFloat(ghost.style.borderWidth) / 2)
    ghost.style.borderWidth = halfBorderWidth + 'px'
  }

  ghost.style.position = 'fixed'
  ghost.style.pointerEvents = 'none'
  ghost.style.left = e.clientX + pointerOffset.x + 'px'
  ghost.style.top = e.clientY + pointerOffset.y + 'px'
  document.body.appendChild(ghost)
  return ghost
}

Note that we cannot directly set borderWidth to half without making that condition check, because it will break other situations. It's an edge case so we should handle it separately.

Nice! Ghost column now fits in the container.

Finally, don't forget to clean up what we did for exaggerating the bug! Depend on devices, You might still see that bug if the border width is set to 1px, but I experienced that as a hardware issue related to how pixel are drawn on screen which we have no control. It will be safer to set a value to 2px or above if possible.

table: refactor our code

Gohomewho — Mon, 19 Dec 2022 15:13:04 +0000

We have been developing everything inside a single file main.js through four series. Two main features we developed are createTable and makeColumnsSwappable. In the last three series, we almost never touch the code we wrote in the first series. Although our code is not clutter, it is still a good time to refactor, so we can separate the concern.

The code we have so far.

Review our code

Before we start refactoring, let's quickly review what we have done.

// we created `helpers.js` in the last series 
// and put `copyElementStyleToAnother` there
import { copyElementStyleToAnother } from "./helpers.js"

// dummy data copied from https://jsonplaceholder.typicode.com/
const users = [/*...*/]

// the columns of `users` we want to show in the table
const nameOfDefaultColumns = [/*...*/]

// a mapper to process complex data of columns
const columnFormatter = {/*...*/}

// use information above to create our table
const table = createTable(nameOfDefaultColumns, users, columnFormatter)

// add a class to table for styling
table.classList.add('my-table')

// add table into DOM, so it can show up in the page
document.body.appendChild(table)

// get the column elements and make them swappable
const columnsContainer = table.querySelector('thead').firstElementChild
const elementsToPatch = table.querySelectorAll('tbody > tr')
makeColumnsSwappable(columnsContainer, elementsToPatch)

// the main function to create a table
function createTable(columns, dataList, columnFormatter) { /**/ }

// part of `createTable`
function createTableHead(columns) { /**/ }

// part of `createTable`
function createTableBody(columns, dataList, columnFormatter) { /**/ }

// part of `createTableBody`
function createTableRow(columns, dataOfTheRow, columnFormatter) { /**/ }

// the main function to make columns swappable
function makeColumnsSwappable(columnsContainer, elementsToPatch = []) { /**/ }

Start with the easiest

There are many places related to createTable. It might be scary to refactor it first. So let's first work on makeColumnsSwappable which only appears twice in our code. One is where we define the function, and the other one is where we use that function.

Create a file makeColumnsSwappable.js and move makeColumnsSwappable to there.

// add a export statement, so we can import it in other file
export function makeColumnsSwappable(columnsContainer, elementsToPatch = []) { 
  // ...
}

import makeColumnsSwappable in main.js

import { makeColumnsSwappable } from "./makeColumnsSwappable.js"
// ...

// function makeColumnsSwappable is removed from main.js

I thought this would instantly work. Test it and got an error.

Uncaught ReferenceError: copyElementStyleToAnother is not defined.

That's because copyElementStyleToAnother is used inside makeColumnsSwappable, and currently there is no copyElementStyleToAnother in makeColumnsSwappable.js.

Since copyElementStyleToAnother is only used inside makeColumnsSwappable, we can move its import statement from main.js to makeColumnsSwappable.js

// move from `main.js` to `makeColumnsSwappable.js`
import { copyElementStyleToAnother } from "./helpers.js"

The code should work again.

Have confident to refactor more

Nice! We have done a warm up, let's move on to the table's code. createTable is the main function to create table. Similar to makeColumnsSwappable, it is a standalone feature that can be moved to a dedicated file. Create a createTable.js and move the code related to createTable to there.

// move these from `main.js` to `createTable.js`

// the main function to create a table
// add a export statement, so we can import it in other file
export function createTable(columns, dataList, columnFormatter) { /**/ }

// part of `createTable`
function createTableHead(columns) { /**/ }

// part of `createTable`
function createTableBody(columns, dataList, columnFormatter) { /**/ }

// part of `createTableBody`
function createTableRow(columns, dataOfTheRow, columnFormatter) { /**/ }

Import createTable in main.js.

import { createTable } from "./createTable.js"
import { makeColumnsSwappable } from "./makeColumnsSwappable.js"
// ...

The code should still work.

The reason that we can simply move these code to separate files without breaking anything is because our functions don't rely on global variables or say external states. The variables that createTable or makeColumnsSwappable need are either created within them or passed through function's parameters.

Let's refactor the rest of the code in main.js. Here are what we left.

import { createTable } from "./createTable.js"
import { makeColumnsSwappable } from "./makeColumnsSwappable.js"

// dummy data copied from https://jsonplaceholder.typicode.com/
const users = [/*...*/]

// the columns of `users` we want to show in the table
const nameOfDefaultColumns = [/*...*/]

// a mapper to process complex data of columns
const columnFormatter = {/*...*/}

// use information above to create our table
const table = createTable(nameOfDefaultColumns, users, columnFormatter)

// add a class to table for styling
table.classList.add('my-table')

// add table into DOM, so it can show up in the page
document.body.appendChild(table)

// get the column elements and make them swappable
const columnsContainer = table.querySelector('thead').firstElementChild
const elementsToPatch = table.querySelectorAll('tbody > tr')
makeColumnsSwappable(columnsContainer, elementsToPatch)

As we can see, the rest of the code are all related to create a table that uses the dummy data from JSONPlaceholder. We can also refactor it. Move everything related to create table into createJSONPlaceholderTable function.

import { createTable } from "./createTable.js"
import { makeColumnsSwappable } from "./makeColumnsSwappable.js"

const jsonPlaceholderTable = createJSONPlaceholderTable()
document.body.appendChild(jsonPlaceholderTable)

function createJSONPlaceholderTable() {
  const users = [/*...*/]
  const nameOfDefaultColumns = [/*...*/]
  const columnFormatter = {/*...*/}

  const table = createTable(nameOfDefaultColumns, users, columnFormatter)
  table.classList.add('my-table')

  const columnsContainer = table.querySelector('thead').firstElementChild
  const elementsToPatch = table.querySelectorAll('tbody > tr')
  makeColumnsSwappable(columnsContainer, elementsToPatch)

  return table
}

Maybe no need to refactor

It might seem unnecessary to refactor createJSONPlaceholderTable. That's true because this table is the only thing in our application. It make more sense when we plan to add more tables, we can refactor like this and put them together.

Since this tutorial is about refactoring, let's keep going. Create a file myTables.js and move everything related to createJSONPlaceholderTable to there.

// move these from `main.js` to `myTables.js`
import { createTable } from "./createTable.js"
import { makeColumnsSwappable } from "./makeColumnsSwappable.js"

// add a export statement, so we can import it in other file
export function createJSONPlaceholderTable() {
  // ...
}

This is what we left in main.js.

// don't forget to add .js at the end of "./myTables.js"
import { createJSONPlaceholderTable } from "./myTables.js"

const jsonPlaceholderTable = createJSONPlaceholderTable()
document.body.appendChild(jsonPlaceholderTable)

Test again the code should still work.

Let's refactor createJSONPlaceholderTable a little more. We can move the code that creates a swappable columns table to a function. So later when we have new data to create another table, we don't need to worry about how to put createTable and makeColumnsSwappable together.

// myTables.js
import { createTable } from "./createTable.js"
import { makeColumnsSwappable } from "./makeColumnsSwappable.js"

// make a function that composite `createTable` and `makeColumnsSwappable`
// so we don't need to worry what elements to select
// and what to pass to `makeColumnsSwappable` when
// we want to create a new swappable columns table
function createColumnsSwappableTable(nameOfDefaultColumns, users, columnFormatter) {
  const table = createTable(nameOfDefaultColumns, users, columnFormatter)

  const columnsContainer = table.querySelector('thead').firstElementChild
  const elementsToPatch = table.querySelectorAll('tbody > tr')
  makeColumnsSwappable(columnsContainer, elementsToPatch)

  return table
}

export function createJSONPlaceholderTable() {
  const users = [/*...*/]
  const nameOfDefaultColumns = [/*...*/]
  const columnFormatter = {/*...*/}

  // change `createTable` to `createColumnsSwappableTable`
  // the arguments are the same as before
  const table = createColumnsSwappableTable(nameOfDefaultColumns, users, columnFormatter)
  // add things to this specific table
  table.classList.add('my-table')

  return table
}

We can also refactor CSS into files.
makeColumnsSwappable.css

.column {
  cursor: move;
}

.columns-container:not(.moving) .column:hover {
  background-color: hsla(0, 0%, 77%, 0.5);
}

.column.moving {
  background-color: hsla(0, 0%, 60%, 0.5);
}

myTables.css

.my-table,
.my-table th,
.my-table td {
  border: 1px solid lightgray;
  border-collapse: collapse;
  padding: 8px;
}

.my-table thead {
  transition: background-color .4s ease;
}

.my-table:hover thead {
  background-color: hsla(0, 0%, 87%, 0.5);
}

main.css

@import './makeColumnsSwappable.css';
@import './myTables.css';

index.html
change style.css to main.css

<link rel="stylesheet" href="./main.css">

Don't forget to test again that everything should still work.

After refactoring, if we want to create a new table, we go to myTables.js. If we want to add features to tables, we go to createTable.js. If we want to add features to swappable columns, we go to makeColumnsSwappable.js. We successfully separate the concern. If we want to develop new things, we can go to main.js, and refactor later like this.

One thing I want to point out is that if you are a beginner, don't worry about refactoring at all. Don't try to make code shorter. Don't ruin your logic. It something works, just let it be!

table: improve moving column UI & UX

Gohomewho — Sat, 17 Dec 2022 03:50:07 +0000

We have made a table component and make the columns swappable. It works pretty well. But currently, we don't have any style for them. Someone who looks at the table probably won't know the columns can be moved. In this tutorial, we are going to improve the UI of our table, and we'll also improve some UX to make moving columns more natural.

The code we have so far.

First of all, let's add some style to make the table look more like a traditional table. Add a class to the table so we can add style to .my-table instead of every table.

main.js

const table = createTable(nameOfDefaultColumns, users, columnFormatter)
table.classList.add('my-table')

style.css

.my-table,
.my-table th,
.my-table td {
  border: 1px solid lightgray;
  border-collapse: collapse;
  padding: 8px;
}

The table looks much better.

Let's add some hints to users that columns can be interactive.
style.css

.my-table thead {
  transition: background-color .4s ease;
}

.my-table:hover thead {
  background-color: hsla(0, 0%, 87%, 0.5);
}

.my-table th {
  cursor: move;
}

A subtle change on background-color tells users that there is something special in columns without drawing too much attention. We change cursor style when users hover on a column to give them a further hint.

We can emphasize more on which column is being moved.

.my-table th:hover {
  background-color: hsla(0, 0%, 77%, 0.5);
}

This doesn't look right. We are moving "website" column, but the "company" column sometimes got that emphasized style.
This is similar to an issue we had before. It's because the cursor is on top of the "company" column, so the hover style applies.

We don't need that hover style when we are moving columns. To do that, we need to change the selector. Because makeColumnsSwappable is a more specific feature, we can add classes to style it directly. That way when we use makeColumnsSwappable on something else, we will have a default style.

function makeColumnsSwappable(columnsContainer, elementsToPatch = []) {
  // add class to columnsContainer 
  columnsContainer.classList.add('columns-container')

  // remember that element.children is a HTMLCollection?
  // it does not have forEach method on it
  // so we use Array.from() to transform it to an array 
  // in order to use forEach to add class on each column
  Array.from(columnsContainer.children).forEach((column) => {
    column.classList.add('column')
  })

  // moving columns starts from here
  columnsContainer.addEventListener('pointerdown', e => {
    let lastCursorX = e.clientX
    let columnElements = [...columnsContainer.children]
    const firstTarget = e.target
    let firstTargetIndex = columnElements.indexOf(firstTarget)

    function preventDefault(e) {
      e.preventDefault()
    }

    document.addEventListener('selectstart', preventDefault)

    if (firstTargetIndex === -1)
      return

    // add a class on `columnsContainer` and `firstTarget`
    // that indicates we are moving columns
    columnsContainer.classList.add('moving')
    firstTarget.classList.add('moving')

    // function handleMove ... 

    // function swapColumns ... 

    // I planned to show the difference between adding 'pointermove'
    // on `document` or `columnsContainer` , but I changed the 
    // target to `document` and write the rest of the article 
    // without noticing it. You can still try toggling between them 
    // throughout this tutorial to see what's the difference.
    document.addEventListener('pointermove', handleMove)

    document.addEventListener('pointerup', () => {
      document.removeEventListener('pointermove', handleMove)
      document.removeEventListener('selectstart', preventDefault)

      // clean up `moving` class after we stop moving columns
      columnsContainer.classList.remove('moving')
      firstTarget.classList.remove('moving')
    }, { once: true })
  })
}

We remove the selector that style all columns hover state. We make a new selector that styles columns hover state when we are not moving. We make another selector that emphasizes the column that we are moving.

/* remove .my-table th:hover */

/* add these */
.columns-container:not(.moving) .column:hover {
  background-color: hsla(0, 0%, 77%, 0.5);
}

.column.moving {
  background-color: hsla(0, 0%, 60%, 0.5);
}

Now we don't have that weird hover style when we are moving columns.

Using selectors to style like this is a neat trick that when we have a list of items and they have different hover style and selected style. Instead of writing a common selector that styles all hover state and use another selector to overwrite the styles like this.

.item:hover {
  background-color: hsla(0, 0%, 77%, 0.5);
}

.item.selected {
  background-color: hsla(0, 0%, 60%, 0.5);
}

We can use what we have just learned to make selectors that style specific things. This way we don't need to worry about specificity and the order of the selectors. Like in this example, if we flip the order of these two .item selectors, the result will be different. Because they both have (0, 2, 0) specificity, the one defined later wins.

Next, let's make moving column more interactive. We can make a ghost column to follow our cursor.

// columnsContainer.addEventListener('pointerdown', e => {
// ...
columnsContainer.classList.add('moving')
firstTarget.classList.add('moving')

function createGhost() {
  // clone the moving column
  const ghost = firstTarget.cloneNode(true)
  // make ghost appear at the cursor position
  ghost.style.position = 'fixed'
  ghost.style.left = e.clientX + 'px'
  ghost.style.top = e.clientY + 'px'
  document.body.appendChild(ghost)
  return ghost
}

const ghost = createGhost()

function handleMove(e) {
  // update ghost position when moving
  // so it follows our cursor
  ghost.style.left = e.clientX + 'px'
  ghost.style.top = e.clientY + 'px'
  // ...
}

This looks more like we are really moving something. But the ghost doesn't look nice. It doesn't look like the column we clone!

It is because that we don't have style any other than .column.moving that styles a column directly. The table columns styles are from .my-table. And the width of columns are automatically controlled by the browser. Apparently, .cloneNode(true) doesn't clone the style as what we would expect.

We can change selector and add styles to make column and ghost column look exactly the same, but this approach is only possible because we are authoring createTable and makeColumnsSwappable at the same time. We could make things work for this situation, but later when we use makeColumnsSwappable alone somewhere else. We will run into this problem again. So we need to think in a broader picture, a future proof solution.

At the moment writing, I don't know how to clone all styles from one element to another, so I google "clone all style" and find this excellent article written by Borislav Hadzhiev.

Let's use it in our code. Create a helpers.js.

// helpers.js
export function copyElementStyleToAnother(aElement, bElement) {
  const styles = window.getComputedStyle(aElement);

  let cssText = styles.cssText;

  if (!cssText) {
    cssText = Array.from(styles).reduce((str, property) => {
      return `${str}${property}:${styles.getPropertyValue(property)};`;
    }, '');
  }

  // 👇️ Assign css styles to element
  bElement.style.cssText = cssText;
}

I already made our script type to module in index.html so we can use import, export statements.

<script src="main.js" type="module"></script>

Import copyElementStyleToAnother at the top of main.js.

import { copyElementStyleToAnother } from "./helpers.js"

Note that if you are following this tutorial using VSCode and its extension live server, typing "copyElementStyleToAnother" and chose to autocomplete will add that import statement for you, which is very convenient. But it doesn't include ".js" at the end, which break everything without showing any error!!! Again, I solve this by google. Just like every developer would do.

main.js

function createGhost() {
  const ghost = firstTarget.cloneNode(true)

  // copy `firstTarget` styles to `ghost`
  copyElementStyleToAnother(firstTarget, ghost)

  // overwrite these styles
  ghost.style.position = 'fixed'
  ghost.style.left = e.clientX + 'px'
  ghost.style.top = e.clientY + 'px'

  document.body.appendChild(ghost)
  return ghost
}

Nice! Now ghost column looks exactly like the column we are moving.

But ghost column position is weird. It should overlap with the column when we just start moving. This is because how we set ghost column's position. We use cursor position e.clientX and e.clientY to set its left and top directly. We should also calculate the offset between cursor initial position and the column's edge, and take that into account.

To do that, we can use .getBoundingClientRect() to get an element 's position and use it to calculate the initial "pointerdown" offset.

// ...
columnsContainer.classList.add('moving')
firstTarget.classList.add('moving')

// calculate initial pointerdown offset to the column's edge
const firstTargetRect = firstTarget.getBoundingClientRect()
const pointerOffset = {
  x: firstTargetRect.x - e.clientX,
  y: firstTargetRect.y - e.clientY
}

function createGhost() {
  const ghost = firstTarget.cloneNode(true)
  copyElementStyleToAnother(firstTarget, ghost)
  ghost.style.position = 'fixed'

  // take that offset to calculate ghost column initial position
  ghost.style.left = e.clientX + pointerOffset.x + 'px'
  ghost.style.top = e.clientY + pointerOffset.y + 'px'

  document.body.appendChild(ghost)
  return ghost
}

const ghost = createGhost()

function handleMove(e) {
  // take that offset to calculate ghost column moving position
  ghost.style.left = e.clientX + pointerOffset.x + 'px'
  ghost.style.top = e.clientY + pointerOffset.y + 'px'
  //...
}

This is looking much natural.

Now we have a bug. Actually, it has been there sine we add ghost column, but the bug was not obvious previously. Swapping columns don't work properly. Can you guess why?

If not, I recommend you check out my addEventListener tutorial later. I don't have a straight answer to this in that tutorial, but I think it will help you understand how events work.

So the problem here is that after we add the ghost column. The "pointermove" event always happens on the ghost column. Our handleMove logic only allow the event target to be one of the columnElements, and ghost column is not one of the columnElements.

function handleMove(e) {
  // ...
  // after ghost column appears
  // e.target will always be the ghost column
  const secondTarget = e.target
  // since ghost column is not one of the `columnElements`
  const secondTargetIndex = columnElements.indexOf(secondTarget)

  // it can't pass this condition
  if (secondTargetIndex === -1)
    return

  // ...
}

I'd like to add some explanation in case someone is confused why ghost column is not one of the columnElements. Ghost column is cloned from one column element. We only clone a element. We didn't add it to columnsContainer. columnElements are the children of columnsContainer. Ghost column is not a child of columnsContainer. So ghost column is not one of the columnElements.

Luckily, there is a very simple but powerful solution to this. There is a CSS property called pointer-events that can remove a element from pointer events mechanism.

function createGhost() {
  const ghost = firstTarget.cloneNode(true)
  copyElementStyleToAnother(firstTarget, ghost)
  ghost.style.position = 'fixed'

  // setting `pointer-events` to 'none '
  // is like removing this element from pointer events mechanism
  ghost.style.pointerEvents = 'none'

  ghost.style.left = e.clientX + pointerOffset.x + 'px'
  ghost.style.top = e.clientY + pointerOffset.y + 'px'

  document.body.appendChild(ghost)
  return ghost
}

Setting pointer-events also works on "click" and "touch" events because they are both considered part of the pointer events.

Voilà! Swapping column works again.

Exercise

I encourage you to google everything you don't know in this tutorial. For example, how to google to get a result that tells you getBoundingClientRect can get an element position? You don't have to process all the information you find. Knowing how to find something you need is enough. And You can reference them later when you find yourselves need more information.

table: fix moving columns bug

Gohomewho — Sun, 04 Dec 2022 15:44:30 +0000

In the previous tutorial, we make columns swappable. I mentioned that in some cases two columns can swap really fast and flash. There is a flaw in our code. In this tutorial, we are going to fix it.

What

First of all, when we spot a bug, we need to identify what the bug is and try limiting the factors.

This one is working as expected.

This one flashes.

So what's the bug? When we move "website" column to the right, we expect it to swap with "company" column. The "website" column does swap with "company" column, but they somehow swap again and again when we keep moving towards right.

Let's try another column. This works as expected. When moving "company" column to left or right, "company" column only swap once with the "address" column .

It's not obvious where the bug occurs, but we know that "website" column has bug and "company" column does not. We can inspect on them further more. We move our cursor much slower this time. We can see that sometimes the columns swap correctly, but as soon as we move our cursor again. Even we are still moving "website" towards right, "website" column swaps back with its left column "company", which is not correct.

So the bug occurs when we move a column to right, it should only swap with its right column, but it sometimes swaps with its left column. When we constantly moving our cursor, the columns swap repeatedly and fast. That's why they flash.

We have identified the bug. Next, we want to collect as much information as possible. Does this bug also occurs when we move a column to left? Let's test it out.

Moving "company" column to left works fine.

Moving "website" column to left has bugs.

Why

After we identified the bug, we want to figure out why it occurs. We tested "company" column and "website" column. The bug only occurs when we move "website" column but not "company" column. What's the difference between them? The only difference I can tell is their sizes. The "company" column is much wider than the "website" column, but this information doesn't seem to be helpful. So we look for next clue. How do we swap the columns?

function makeColumnsSwappable(columnsContainer, elementsToPatch = []) {
  columnsContainer.addEventListener('pointerdown', e => {
    let columnElements = [...columnsContainer.children]
    const firstTarget = e.target
    let firstTargetIndex = columnElements.indexOf(firstTarget)

    function preventDefault(e) {
      e.preventDefault()
    }

    document.addEventListener('selectstart', preventDefault)

    if (firstTargetIndex === -1)
      return

    function handleMove(e) {
      const secondTarget = e.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      if (firstTarget === secondTarget)
        return

      // (2) this is where we want to swap columns
      swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)

      elementsToPatch.forEach((columnsContainer) => {
        swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)
      })

      columnElements = [...columnsContainer.children]
      firstTargetIndex = columnElements.indexOf(firstTarget)
    }

    function swapColumns(container, firstTargetIndex, secondTargetIndex) {
      const columns = container.children
      const firstTarget = columns[firstTargetIndex]
      const secondTarget = columns[secondTargetIndex]
      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      // (3) this is where we actually swap the column elements
      if (isMoveToLeft) {
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }
    }

    // (1) this is where we handle 'pointermove' event
    columnsContainer.addEventListener('pointermove', handleMove)

    document.addEventListener('pointerup', () => {
      columnsContainer.removeEventListener('pointermove', handleMove)
      document.removeEventListener('selectstart', preventDefault)
    }, { once: true })
  })
}

We swap two column elements by getting two targets, the first target is the one on 'pointerdown', and the second target is the one on 'pointermove'. We assume that we are moving first column to left if firstTargetIndex > secondTargetIndex, and moving first column to right if firstTargetIndex < secondTargetIndex. We use that information to move elements with insertAdjacentElement.

function swapColumns(container, firstTargetIndex, secondTargetIndex) {
  const columns = container.children
  const firstTarget = columns[firstTargetIndex]
  const secondTarget = columns[secondTargetIndex]
  const isMoveToLeft = firstTargetIndex > secondTargetIndex
  const isMoveToRight = firstTargetIndex < secondTargetIndex

  if (isMoveToLeft) {
    secondTarget.insertAdjacentElement('beforebegin', firstTarget)
  } else if (isMoveToRight) {
    secondTarget.insertAdjacentElement('afterend', firstTarget)
  }
}

We can probably tell that using firstTargetIndex and secondTargetIndex to get moving direction is not ideal. But the logic works sometimes. So what goes wrong? Let's look closely to the cases that works and that doesn't this time.

When we are moving "company" column, it looks like the cursor is always on top of it.

When we are moving "website" column, as soon as it swap with "company" column, the cursor is on top of the "company" column.

In our swapping columns logic, we do nothing if first target and second target are the same, and we swap two columns if first target and second target are different. This reflects in the result. The reason that swapping "website" column with "company" column has bug is because "company" column is much wider than "website" column. After "website" column swaps with "company" column, the cursor becomes on top of "company" column. As soon as we move cursor again, they swap. After they swap, the cursor is still on top of "company" column. This repeats again and again on 'pointermove'. That's why they flash.

How

After we find out the reason of the bug, we can start thinking how to fix it. If you'd like to follow along, here is the code from the previous tutorial.

When we are moving a column to right, we only want it to swap with the column on its right. To do that, we need to check if cursor is moving towards right. The same logic applies to moving a column to left.

function makeColumnsSwappable(columnsContainer, elementsToPatch = []) {
  columnsContainer.addEventListener('pointerdown', e => {
    // save first cursor x position on 'pointerdown'
    // e.clientX is the horizontal distance
    // from the left edge of browser window
    // to where the event is triggered
    let lastCursorX = e.clientX
    let columnElements = [...columnsContainer.children]
    const firstTarget = e.target
    let firstTargetIndex = columnElements.indexOf(firstTarget)

    function preventDefault(e) {
      e.preventDefault()
    }

    document.addEventListener('selectstart', preventDefault)

    if (firstTargetIndex === -1)
      return

    function handleMove(e) {
      // save new cursor x position on 'pointermove'
      const newCursorX = e.clientX
      const secondTarget = e.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      if (firstTarget === secondTarget)
        return

      // compare `newCursorX` and `lastCursorX` to check 
      // which direction the cursor is moving towards
      const isMoveToLeft = newCursorX < lastCursorX
      const isMoveToRight = newCursorX > lastCursorX
      // update `lastCursorX` for next comparison 
      lastCursorX = newCursorX

      swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)

      elementsToPatch.forEach((columnsContainer) => {
        swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)
      })

      columnElements = [...columnsContainer.children]
      firstTargetIndex = columnElements.indexOf(firstTarget)
    }

    function swapColumns(container, firstTargetIndex, secondTargetIndex) {
      const columns = container.children
      const firstTarget = columns[firstTargetIndex]
      const secondTarget = columns[secondTargetIndex]
      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      if (isMoveToLeft) {
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }
    }

    columnsContainer.addEventListener('pointermove', handleMove)

    document.addEventListener('pointerup', () => {
      columnsContainer.removeEventListener('pointermove', handleMove)
      document.removeEventListener('selectstart', preventDefault)
    }, { once: true })
  })
}

Update logic with new isMoveToLeft and isMoveToRight

function handleMove(e) {
  //...
  // pass `isMoveToLeft` and `isMoveToRight`
  swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex, isMoveToLeft, isMoveToRight)

  elementsToPatch.forEach((columnsContainer) => {
    // pass `isMoveToLeft` and `isMoveToRight`
    swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex, isMoveToLeft, isMoveToRight)
  })
  // ...
}

// update to take two more parameter 
// `isMoveToLeft` and `isMoveToRight`
function swapColumns(container, firstTargetIndex, secondTargetIndex, isMoveToLeft, isMoveToRight) {
  const columns = container.children
  const firstTarget = columns[firstTargetIndex]
  const secondTarget = columns[secondTargetIndex]
  // no longer using `firstTargetIndex` and `secondTargetIndex`
  // to calculate `isMoveToLeft` and `isMoveToRight` from here

  if (isMoveToLeft) {
    secondTarget.insertAdjacentElement('beforebegin', firstTarget)
  } else if (isMoveToRight) {
    secondTarget.insertAdjacentElement('afterend', firstTarget)
  }
}

Great! By making the logic correct, the bug is fixed!

One last thing to do is to refactor our code a little bit. function swapColumns now takes 5 parameters in order, if we accidently pass the arguments in a wrong order, the function won't work. The parameters are all required, so what can we do? Well, we can use object to make those parameters as a group, so the order won't matter.

// `swapColumns` now only have two parameters
// the second one is an object
function swapColumns(container, {
  firstTargetIndex,
  secondTargetIndex,
  isMoveToLeft,
  isMoveToRight
}) { //...

Group the arguments to an object

function handleMove(e) {
  //...
  swapColumns(columnsContainer, {
    // as long as we provide these in this object
    // the order of them doesn't matter at all
    firstTargetIndex,
    secondTargetIndex,
    isMoveToLeft,
    isMoveToRight
  })

  elementsToPatch.forEach((columnsContainer) => {
    swapColumns(columnsContainer, {
      // the order is different than above
      isMoveToLeft,
      isMoveToRight,
      secondTargetIndex,
      firstTargetIndex
    })
  })
  // ...
}

Since the two objects we pass to swapColumns have the exact same properties, We can also group it like this.

  const swapColumnInfo = {
    firstTargetIndex,
    secondTargetIndex,
    isMoveToLeft,
    isMoveToRight
  }

  swapColumns(columnsContainer, swapColumnInfo)

  elementsToPatch.forEach((columnsContainer) => {
    swapColumns(columnsContainer, swapColumnInfo)
  })

The code should still work. Note that grouping all swapColumns parameters to one object is also possible. It will require slightly more change. You can try it out as an exercise. Just to be clear, this refactor is not necessary as we probably won't use swapColumns elsewhere. I merely want to show that how to modify parameters to make a function easier to use.

table: make the columns swappable

Gohomewho — Sat, 26 Nov 2022 12:23:31 +0000

In the previous tutorial, we make a table that can take any kind of data and display them. Displaying information is the most important thing. But the order of the columns is fixed. It won't be a problem until our audiences grow and their opinions conflict where we can't just change the order manually.

In this tutorial, we will use addEventListener to make the columns swappable. So people can move the columns to any order they want. If you are not familiar with addEventListener, you can checkout out my verbose article on the topic.

Here is the code from the previous tutorial.

To make the columns swappable, we need to know which two targets to swap. It's not complex if you think about it. Every time we move a column, we are swapping its position with either its closest left or right column. The first target will be the column element we want to move, and the second target will be either its left or right element. With this approach, we could move columns around.

To get the first target, we can addEventListener to each column elements. we can also use the event delegation and addEventListener to their parent. We are going to use event delegation.

We created column elements inside createTableHead function, we can addEventListener to their parent tr. We choose 'pointerdown' over 'click' event so our code will work well with both touch and mouse devices. You can learn more about pointer events on JavaScript.info.

function createTableHead(columns) {
  const thead = document.createElement('thead')
  const tr = document.createElement('tr')

  columns.forEach(columnName => {
    const th = document.createElement('th')
    th.textContent = columnName
    tr.appendChild(th)
  });

  // `addEventListener` to column elements' parent 
  tr.addEventListener('pointerdown', e => {
    const firstTarget = e.target
    console.log(firstTarget)
  })

  thead.appendChild(tr)
  return thead
}

Because of event propagation, e.target can be any element inside tr. It's not quite obvious because currently we don't have any style and other elements columns, so clicking on a column always gives us a column element. Since we want to move column elements, we need to make sure we get the correct column elements but not their descendants. We can check if e.target is in the tr.children.

// ...

  tr.addEventListener('pointerdown', e => {
    // `tr.children` gives us a HTMLCollection not an array
    // but we can convert it to an array like this `[...tr.children]`
    // so we can use `.indexOf()`
    const columnElements = [...tr.children]
    const firstTarget = e.target
    // `.indexOf()` returns `-1` if it can't find the item
    const firstTargetIndex = columnElements.indexOf(firstTarget)

    // if `e.target` is not a column element
    // we want to early return and do nothing
    if (firstTargetIndex === -1)
      return

  })

// ...

We have the first target. Now we want to get the second target when moving. Add a 'pointermove' event listener to tr and get the second target. It's similar as the steps above.

  tr.addEventListener('pointerdown', e => {
    const columnElements = [...tr.children]
    const firstTarget = e.target
    const firstTargetIndex = columnElements.indexOf(firstTarget)

    if (firstTargetIndex === -1)
      return

    // add a pointermove event listener here 
    tr.addEventListener('pointermove', e2 => {
      const secondTarget = e2.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return
    })
  })

After we have both first target and second target, We can start writing the logic to move them. We can use their indexes as a clue to indicate we are moving a column to left or right.

// this is inside tr.addEventListener('pointerdown', e => {
// ...

    tr.addEventListener('pointermove', e2 => {
      const secondTarget = e2.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      // if `firstTarget` and `secondTarget` are the same element
      // we want to early return and do nothing
      if (firstTarget === secondTarget)
        return

      // if firstTargetIndex > secondTargetIndex
      // it means the second target is on the left side of first target
      // it also means that we want to move the first target to left
      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      // same logic apply to moving to right
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      if (isMoveToLeft) {
        // insert `firstTarget` before `secondTarget`
        // which moves `firstTarget` to the left side of `secondTarget`
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        // insert `firstTarget` after `secondTarget`
        // which moves `firstTarget` to the right side of `secondTarget`
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }
//...

We can move columns now, but it never stops. We need to stop it at some point. We can do that by adding a 'pointerup' event listener to tr and remove the 'pointermove'.

  tr.addEventListener('pointerdown', e => {
    //...
    tr.addEventListener('pointermove', e2 => {
      //...
    })

    // We want to stop the 'pointermove' when 'pointerup'
    tr.addEventListener('pointerup', e3 => {

    })
  })

The callback function inside 'pointermove' is inline. We have to extract the function out in order to reference it at removeEventListener.

  tr.addEventListener('pointerdown', e => {
    //...

    // extract the inline function from 'pointermove' to here
    function handleMove(e) {
      const secondTarget = e.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      if (firstTarget === secondTarget)
        return

      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      if (isMoveToLeft) {
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }
    }

    // use the extracted function `handleMove` on 'pointermove'
    tr.addEventListener('pointermove', handleMove)

    // stop moving on 'pointerup'
    tr.addEventListener('pointerup', () => {
      // remove the 'pointermove' event listener on `tr`
      // which references the function `handleMove`
      tr.removeEventListener('pointermove', handleMove)
    })
  })

We add other event listeners 'pointermove' and 'pointerup' to tr on 'pointerdown'. We clean up 'pointermove' on 'pointerup', but we didn't clean up 'pointerup'. This means that every time we 'pointerdown', we add an extra 'pointerup' event listener. We can make 'pointerup' only fire once.

//...
    tr.addEventListener('pointerup', () => {
      tr.removeEventListener('pointermove', handleMove)
      // add configuration { once: true }
    }, { once: true })
//...

You can add a console.log('hi') to 'pointerup' and click on a column many times to see what's the difference without { once: true }.

Now we can start moving and stop moving. If you've followed the tutorial, you might notice that the moving isn't quite right. You are correct! And we are going to fix it.

The problem is that we didn't update some variables after a move.

  tr.addEventListener('pointerdown', e => {
    // `tr.children` is a HTMLCollection, it can automatically update
    // but we convert it to an array, it becomes a fix order
    // we need to update this array after a move
    // to get the correct index of elements
    const columnElements = [...tr.children]
    // the `firstTarget` is always the 'pointerdown' one
    const firstTarget = e.target
    // `firstTargetIndex` will change after a move
    // so we should update this
    const firstTargetIndex = columnElements.indexOf(firstTarget)

    if (firstTargetIndex === -1)
      return

    function handleMove(e) {
      // secondTarget will change
      // but we always get the latest secondTarget on `'pointermove'`
      // so this won't be a problem
      const secondTarget = e.target
      // getting `secondTargetIndex` has a problem
      // because we don't update `columnElements` after a move
      // so the index would be incorrect
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      if (firstTarget === secondTarget)
        return

      // indexes become incorrect
      // so `isMoveToLeft` and `isMoveToRight ` become incorrect
      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      // These also become incorrect
      if (isMoveToLeft) {
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }

      // so after a move
      // we need to update columnElements and firstTargetIndex 
    }

    tr.addEventListener('pointermove', handleMove)

    tr.addEventListener('pointerup', () => {
      tr.removeEventListener('pointermove', handleMove)
    }, { once: true })
  })

Fix the problem.

  tr.addEventListener('pointerdown', e => {
    // change this to let
    let columnElements = [...tr.children]
    const firstTarget = e.target
    // change this to let
    let firstTargetIndex = columnElements.indexOf(firstTarget)

    if (firstTargetIndex === -1)
      return

    function handleMove(e) {
      const secondTarget = e.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      if (firstTarget === secondTarget)
        return

      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      if (isMoveToLeft) {
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }

      // update `columnElements` and `firstTargetIndex` after a move
      columnElements = [...tr.children]
      firstTargetIndex = columnElements.indexOf(firstTarget)
    }

    tr.addEventListener('pointermove', handleMove)

    tr.addEventListener('pointerup', () => {
      tr.removeEventListener('pointermove', handleMove)
    }, { once: true })
  })

We should be able to move columns like this.

Great! Now we can move the columns in the table header, we should also apply that change to the table body, otherwise columns won't match the data!

How do we do that? If you think about it, the structure of the table header and a table row is very similar. They both have a container that wraps the column elements. So the logic to move the elements might be the same. Let's try it out. First, extract the logic of moving columns to a function.

    function handleMove(e) {
      const secondTarget = e.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      if (firstTarget === secondTarget)
        return

      // use the function
      swapColumns(tr, firstTargetIndex, secondTargetIndex)

      columnElements = [...tr.children]
      firstTargetIndex = columnElements.indexOf(firstTarget)
    }

    // make a function that can swap two columns
    function swapColumns(container, firstTargetIndex, secondTargetIndex) {
      // get column elements of the container
      const columns = container.children

      // get `firstTarget` and `secondTarget` with the indexes
      const firstTarget = columns[firstTargetIndex]
      const secondTarget = columns[secondTargetIndex]

      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      if (isMoveToLeft) {
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }
    }

Note that we don't pass firstTarget and secondTarget directly to swapColumns. First, we can get them through container, firstTargetIndex, secondTargetIndex. Second, container, firstTargetIndex, secondTargetIndex is the common point between the table header and a table row.

Next, we can use the function swapColumns to update the table body rows.

function handleMove(e) {
  const secondTarget = e.target
  const secondTargetIndex = columnElements.indexOf(secondTarget)

  if (secondTargetIndex === -1)
    return

  if (firstTarget === secondTarget)
    return

  swapColumns(tr, firstTargetIndex, secondTargetIndex)

  // we don't have access to the rows 
  // so we get them here
  const rows = [...table.querySelectorAll('tbody > tr')]

  // update the rows
  rows.forEach((columnsContainer) => {
    swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)
  })

  columnElements = [...tr.children]
  firstTargetIndex = columnElements.indexOf(firstTarget)
}

Move table columns altogether.

When we are moving columns, we don't intent to select text. I found that selection quite annoying, so let's disable it.

tr.addEventListener('pointerdown', e => {
  let columnElements = [...tr.children]
  const firstTarget = e.target
  let firstTargetIndex = columnElements.indexOf(firstTarget)

  // create a function so we can reference it
  function preventDefault(e) {
    e.preventDefault()
  }

  // disable text selection
  document.addEventListener('selectstart', preventDefault)

  if (firstTargetIndex === -1)
    return

  function handleMove(e) { 
    //...
  }

  function swapColumns(container, firstTargetIndex, secondTargetIndex) { 
    // ...
  }

  tr.addEventListener('pointermove', handleMove)

  tr.addEventListener('pointerup', () => {
    tr.removeEventListener('pointermove', handleMove)

    // remove the text selection disable
    // so we can still select text and copy the data 
    document.removeEventListener('selectstart', preventDefault)
  }, { once: true })
})

We can still select text when we are not moving columns.

We also want to change the target we add 'pointerup' from tr to document, so we don't have to 'pointerup' in the tr.

//...
    // change `tr.addEventListener` to `document.addEventListener`
    document.addEventListener('pointerup', () => {
      tr.removeEventListener('pointermove', handleMove)
      document.removeEventListener('selectstart', preventDefault)
    }, { once: true })
//...

Throughout this tutorial, we add the logic directly to tr in the createTableHead function. We extract the logic that moves columns to the function swapColumns, so we can update any other columns which is the most important part. This means that we can extract the whole logic, so it can work on any container that follows this structure.

Let's create a function makeColumnsSwappable to the bottom of the file and copy everything from 'pointerdown'. Rseplace all references from tr to columnsContainer, so it can work on any container.

function makeColumnsSwappable(columnsContainer) {
  // tr -> columnsContainer
  columnsContainer.addEventListener('pointerdown', e => {
    // tr -> columnsContainer
    let columnElements = [...columnsContainer.children]
    const firstTarget = e.target
    let firstTargetIndex = columnElements.indexOf(firstTarget)

    function preventDefault(e) {
      e.preventDefault()
    }

    document.addEventListener('selectstart', preventDefault)

    if (firstTargetIndex === -1)
      return

    function handleMove(e) {
      const secondTarget = e.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      if (firstTarget === secondTarget)
        return

      // tr -> columnsContainer
      swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)

      const rows = [...table.querySelectorAll('tbody > tr')]
      rows.forEach((columnsContainer) => {
        swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)
      })

      // tr -> columnsContainer
      columnElements = [...columnsContainer.children]
      firstTargetIndex = columnElements.indexOf(firstTarget)
    }

    function swapColumns(container, firstTargetIndex, secondTargetIndex) {
      const columns = container.children
      const firstTarget = columns[firstTargetIndex]
      const secondTarget = columns[secondTargetIndex]
      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      if (isMoveToLeft) {
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }
    }

    // tr -> columnsContainer
    columnsContainer.addEventListener('pointermove', handleMove)

    document.addEventListener('pointerup', () => {
      // tr -> columnsContainer
      columnsContainer.removeEventListener('pointermove', handleMove)
      document.removeEventListener('selectstart', preventDefault)
    }, { once: true })
  })
}

Use the makeColumnsSwappable function. It should works as before.

function createTableHead(columns) {
  const thead = document.createElement('thead')
  const tr = document.createElement('tr')

  columns.forEach(columnName => {
    const th = document.createElement('th')
    th.textContent = columnName
    tr.appendChild(th)
  });

  // use it here
  makeColumnsSwappable(tr)

  thead.appendChild(tr)
  return thead
}

Since we extract the logic, makeColumnsSwappable doesn't have to be called inside createTableHead. Maybe we don't want every table to have the moving feature. We can use it as a plugin. Remove makeColumnsSwappable(tr) inside createTableHead and use it at where we created the table.

// This is where we created the table.
const table = createTable(nameOfDefaultColumns, users, columnFormatter)
document.body.appendChild(table)
// remember that the container of table header columns 
// is structured as thead > tr 
const columnsContainer = table.querySelector('thead').firstElementChild
// only make this table header columns to be swappable
makeColumnsSwappable(columnsContainer)

There is one last thing we haven't handled in the makeColumnsSwappable function. We used to get the table body rows and update them. Now we can't do that anymore. We can't assume there are other columns to update. We need that information to be passed from outside.

// add a paremeter `elementsToPatch` and defaults to empty array
// so we can call .forEach() directly
function makeColumnsSwappable(columnsContainer, elementsToPatch = []) {
  // ...
    function handleMove(e) {
      // ...
      // change these
        const rows = [...table.querySelectorAll('tbody > tr')]
        rows.forEach((columnsContainer) => {
          swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)
        })

      // to this 
      elementsToPatch.forEach((columnsContainer) => {
        swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)
      })

      // ...
    }
}

makeColumnsSwappable by default only update the columnsContainer that it takes directly, unless elementsToPatch is specified.

Lastly, we need to pass elementsToPatch to makeColumnsSwappable to make the columns in the table body rows swap again.

const table = createTable(nameOfDefaultColumns, users, columnFormatter)
document.body.appendChild(table)
const columnsContainer = table.querySelector('thead').firstElementChild
// get `elementsToPatch`
const elementsToPatch = table.querySelectorAll('tbody > tr')
// pass `elementsToPatch` 
// if we comment out this line
// the table will remain the same as the previous tutorial
makeColumnsSwappable(columnsContainer, elementsToPatch)

Our result

If you have noticed that sometimes two columns swap really fast and flash, that's a flaw in our current logic. I'll give you a clue if you want to fix it. We need to actually check the pointer is moving left or right rather than using the elements' indexes.

The code we make in this tutorial.

function makeColumnsSwappable(columnsContainer, elementsToPatch = []) {
  columnsContainer.addEventListener('pointerdown', e => {
    let columnElements = [...columnsContainer.children]
    const firstTarget = e.target
    let firstTargetIndex = columnElements.indexOf(firstTarget)

    function preventDefault(e) {
      e.preventDefault()
    }

    document.addEventListener('selectstart', preventDefault)

    if (firstTargetIndex === -1)
      return

    function handleMove(e) {
      const secondTarget = e.target
      const secondTargetIndex = columnElements.indexOf(secondTarget)

      if (secondTargetIndex === -1)
        return

      if (firstTarget === secondTarget)
        return

      swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)

      elementsToPatch.forEach((columnsContainer) => {
        swapColumns(columnsContainer, firstTargetIndex, secondTargetIndex)
      })

      columnElements = [...columnsContainer.children]
      firstTargetIndex = columnElements.indexOf(firstTarget)
    }

    function swapColumns(container, firstTargetIndex, secondTargetIndex) {
      const columns = container.children
      const firstTarget = columns[firstTargetIndex]
      const secondTarget = columns[secondTargetIndex]
      const isMoveToLeft = firstTargetIndex > secondTargetIndex
      const isMoveToRight = firstTargetIndex < secondTargetIndex

      if (isMoveToLeft) {
        secondTarget.insertAdjacentElement('beforebegin', firstTarget)
      } else if (isMoveToRight) {
        secondTarget.insertAdjacentElement('afterend', firstTarget)
      }
    }

    columnsContainer.addEventListener('pointermove', handleMove)

    document.addEventListener('pointerup', () => {
      columnsContainer.removeEventListener('pointermove', handleMove)
      document.removeEventListener('selectstart', preventDefault)
    }, { once: true })
  })
}

Let's make a table component with JavaScript

Gohomewho — Sat, 19 Nov 2022 09:40:42 +0000

In this tutorial, we'll make a table component with JavaScript. We'll make it can be populated with any data and add more features to it in the following series.

This is how a table is structured.

Let's write the overall structure.

// Create a `table` element and add `thead` and `tbody` to it.
function createTable() {
  const table = document.createElement('table')
  const thead = createTableHead()
  const tbody = createTableBody()
  table.appendChild(thead)
  table.appendChild(tbody)
  return table
}

// create a thead element
function createTableHead() {
  const thead = document.createElement('thead')
  const tr = document.createElement('tr')

  // add th of each column to tr

  thead.appendChild(tr)
  return thead
}

// create a tbody element
function createTableBody() {
  const tbody = document.createElement('tbody')

  // add tr of each row of data to tbody

  return tbody
}

Grab the dummy data from https://jsonplaceholder.typicode.com/users and store it in a variable.

const users = [ 
  //...
]

Define the default columns we want to display. we'll make the columns can be toggled on and off in later series.

const nameOfDefaultColumns = [
  'id',
  'name',
  'username',
  'email',
  'phone',
  'website',
]

Add a parameter columns to createTableHead so it can make each th element according to columns.

function createTableHead(columns) {
  const thead = document.createElement('thead')
  const tr = document.createElement('tr')

  // create th element for each column
  columns.forEach(name => {
    const th = document.createElement('th')
    th.textContent = name
    tr.appendChild(th)
  });

  thead.appendChild(tr)
  return thead
}

Add two parameter columns and dataList to createTableBody so it can make tr for each row of dataList and columns of each row.

function createTableBody(columns, dataList) {
  const tbody = document.createElement('tbody')

  // create rows for each item of dataList
  dataList.forEach(eachDataObject => {
    const tr = document.createElement('tr')

    // create cells of each column for the row
    columns.forEach((columnName) => {
      const td = document.createElement('td')
      // display the data of that column
      td.textContent = eachDataObject[columnName]
      tr.appendChild(td)
    })

    tbody.appendChild(tr)
  });

  return tbody
}

Note that we use columns.forEach() to create column headers in createTableHead and create each column data of each row in createTableBody. This guarantees that the data of each column would match.

This is the code at this point.

const user = [ /* https://jsonplaceholder.typicode.com/users */ ]

const nameOfDefaultColumns = [
  'id',
  'name',
  'username',
  'email',
  'phone',
  'website',
]

const table = createTable(nameOfDefaultColumns, users)
document.body.appendChild(table)

function createTable(columns, dataList) {
  const table = document.createElement('table')
  const thead = createTableHead(columns)
  const tbody = createTableBody(columns, dataList)
  table.appendChild(thead)
  table.appendChild(tbody)
  return table
}

function createTableHead(columns) {
  const thead = document.createElement('thead')
  const tr = document.createElement('tr')

  columns.forEach(columnName => {
    const th = document.createElement('th')
    th.textContent = columnName
    tr.appendChild(th)
  });

  thead.appendChild(tr)
  return thead
}

function createTableBody(columns, dataList) {
  const tbody = document.createElement('tbody')

  dataList.forEach(eachDataObject => {
    const tr = document.createElement('tr')

    columns.forEach((columnName) => {
      const td = document.createElement('td')
      td.textContent = eachDataObject[columnName]
      tr.appendChild(td)
    })

    tbody.appendChild(tr)
  });

  return tbody
}

Our result.

We can easily change the columns we want to display.

const nameOfDefaultColumns = [
  'id',
  'name',
  'username',
  'email',
  'phone',
  'website',
  'company' // add this
]

The column appears! But the data is definitely not correct.

Because the data was converted to string before assigning to td.textContent, the toString() was called implicitly. When we call toString() on an object, it will return '[object Object]', This is also the reason why sometimes we try to console.log an object but we see '[object Object]', because it is implicitly converted to a string.

// a number
const id = 1
id.toString()
// '1'

// an object
const obj = {}
obj.toString()
// '[object Object]'

This means we need to process the data before assigning to td.textContent. This also means that if we want to display something more complex, we can't use td.textContent because it will only display string.

We need a way to process the data inside createTableBody. But we can't directly process the data because the data from dataList is dynamic. So how do we process the data inside createTableBody but in the meantime control the actual process from outside? It is like how we pass data to createTableBody. This time we want to pass a formatter.

// add new parameter `columnFormatter`
function createTableBody(columns, dataList, columnFormatter) {
  const tbody = document.createElement('tbody')

  dataList.forEach(eachDataObject => {
    const tr = document.createElement('tr')

    columns.forEach((columnName) => {
      const td = document.createElement('td')
      const columnValue = eachDataObject[columnName]
      // if we have a custom formatter for this column
      // we want to use it
      if (columnFormatter && columnFormatter[columnName]) {
        const formatterOfColumn = columnFormatter[columnName]
        if (formatterOfColumn) {
          const formatted = formatterOfColumn(columnValue)
          // `appendChild` only accept node (element)
          // `append` accept both string and node (element)
          td.append(formatted)
        }
      }
      else {
        // otherwise we simply display the "string version" value
        td.textContent = columnValue
      }

      tr.appendChild(td)
    })

    tbody.appendChild(tr)
  });

  return tbody
}

We call createTableBody from createTable, so we also need to add the columnFormatter parameter to createTable in order to pass it.

// add columnFormatter parameter
function createTable(columns, dataList, columnFormatter) {
  const table = document.createElement('table')
  const thead = createTableHead(columns)
  // call createTableBody with columnFormatter
  const tbody = createTableBody(columns, dataList, columnFormatter)
  table.appendChild(thead)
  table.appendChild(tbody)
  return table
}

Define column formatter. An object that each key is the column name and maps to a function that process the column value.

const columnFormatter = {
  'company': (data) => {
    const p = document.createElement('p')
    const strong = document.createElement('strong')
    strong.textContent = ` (${data.catchPhrase})`
    p.append(data.name, strong)
    return p
  },
  'address': (data) => {
    const {
      street,
      suite,
      city,
      zipcode,
    } = data
    // I don't know how people format address in US.
    // Sorry if this is incorrect
    return `${street} ${suite} ${city} ${zipcode}`
  }
}

const table = createTable(nameOfDefaultColumns, users, columnFormatter)
document.body.appendChild(table)

Display all columns with processed values.

This is great! We've already done what we need. It should be able to populate any data. There is one last thing I want to do before closing. Let's refactor the code a little bit.

Move the logic that makes table row from createTableBody to a new function createTableRow so the code can be more readable.

function createTableBody(columns, dataList, columnFormatter) {
  const tbody = document.createElement('tbody')

  dataList.forEach(eachDataObject => {
    const tr = createTableRow(columns, eachDataObject, columnFormatter)
    tbody.appendChild(tr)
  });

  return tbody
}

function createTableRow(columns, dataOfTheRow, columnFormatter) {
  const tr = document.createElement('tr')
  columns.forEach((columnName) => {
    const td = document.createElement('td')
    const columnValue = dataOfTheRow[columnName]

    const formatterOfColumn = columnFormatter && columnFormatter[columnName]
    if (formatterOfColumn) {
      const formatted = formatterOfColumn(columnValue)
      td.append(formatted)
    }
    else {
      td.textContent = columnValue
    }

    tr.appendChild(td)
  })

  return tr
}

addEventListener

Gohomewho — Sun, 06 Nov 2022 15:08:26 +0000

addEventListener is an easy way to start making our page interactive. In this article, we will learn how to addEventListener and what you should know. You can follow this article with your favorite code editor or on stackblitz. You can use this template that I crated on stackblitz.

Introduction

Events happen all the time in the browser. When we call addEventListener on a target, we are telling the browser that "Hey, from now on when that event is triggered by this target, I want to do something". Later when the event is triggered by the target, browser will run our instruction with the latest information from that event.

How to add event listener

We can add event listener on DOM elements (The things you see on the page). Let's create an element in HTML and select it with JavaScript first.

index.html



<body>
  <div>hello</div>
</body>

main.js



const div = document.querySelector('div');
console.log(div);

Open stackblitz console

If you want to use the browser console, you need to select an element with devtools(press F12 to open) and switch to the console tab as shown below.

We need to do this step every time we refresh the page. By the way, pressing Ctrl + S to save the file will auto refresh the page.

Now we have an element, we can add event listener on it. addEventListener is a function available on DOM elements. In other words, we have an object that has a method addEventListener, we can use it like this div.addEventListener(). addEventListener first parameter is a string represents the event type we want to listen. The second parameter is a callback function which is the instruction for browser to do when the event is triggered.

main.js



div.addEventListener('click', () => {
  console.log('Yay!');
});

Each time we click on the element, the callback function will be run.

addEventListener accept a third parameter to configure its behavior. For example, we can make a event listener that will only be run once like this.

main.js



// configure this event listener with { once: true }
div.addEventListener(
  'click',
  () => {
    console.log('Yay!');
  },
  {
    once: true,
  }
);

Now no matter how hard you press, The callback function will only be run once.

We can add many event listeners on the same element.

main.js



// add different event listeners to a div
div.addEventListener('click', () => console.log('click'));
div.addEventListener('mousemove', () => console.log('mousemove'));
div.addEventListener('mouseover', () => console.log('mouseover'));
div.addEventListener('mouseout', () => console.log('mouseout'));

We can add many event listeners of the same event type.
main.js



// add three 'click' event listeners to a div
div.addEventListener('click', () => console.log('a'));
div.addEventListener('click', () => console.log('b'));
div.addEventListener('click', () => console.log('c'));

Whenever click event is triggered, callback functions are run in the order we add them.

Event information

Our callback functions are actually called with one argument, an object which contains the information of the event. If we need to use those information, we should make our function accept a parameter, otherwise we can omit it.

main.js



// provide a callback that accepts a parameter
div.addEventListener('click', (e) => console.log(e));

You can briefly read what it logs.

Event propagation

When we click on an element, it is not only one click event trigged by the element. There are actually three phrases occur during a click action that can trigger many more click events than you expected.

1.Capturing phrase

The event is being propagated through the target's ancestor objects. This process starts with the Window, then Document, then the HTMLHtmlElement, and so on through the elements until the target's parent is reached.

2.At target

The event has arrived at the event's target. Event listeners registered for this phase are called at this time. If Event.bubbles is false, processing the event is finished after this phase is complete.

3.Bubbling phrase

The event is propagating back up through the target's ancestors in reverse order, starting with the parent, and eventually reaching the containing Window. This is known as bubbling, and occurs only if Event.bubbles is true.

To simply put, the target that we click on might not be the element that we add listener on, it can also be one of the element's descendant because of bubbling. One thing to remember is that events are not created by the addEventListener. What it does is that we want to listen to a small part of all events that happening behind the scene.

Let's see some examples.

index.html



<div class="a">
  a
  <div class="b">
    b
    <div class="c">
     c
    </div>
  </div>
</div>

Add some CSS for visualization.

styles.css



div {
  padding: 16px;
  margin: 8px;
  border: 1px solid;
}

Add a click event listener on a element.

main.js



const a = document.querySelector('.a');
const b = document.querySelector('.b');
const c = document.querySelector('.c');

a.addEventListener('click', () => {
  console.log('click');
});

We can see that click on a or b or c, all trigger the click event on a. Clicking outside of a doesn't trigger the click event, which is quite reasonable.

Let's add a click event listener on c element which is a descendant of a.

main.js



c.addEventListener('click', () => {
  console.log('c');
});

In modern browsers, by default, all event handlers are registered for the bubbling phase. That's why we see 'c' -> 'a' instead of 'a' -> 'c' when we click on c element.

We can configure addEventListener to register event handlers for capturing phrase. We can provide a third argument to addEventListener. It can be a boolean value true or an object that has capture: true. This doesn't mean that the event handlers will only be run in the capturing phrase. It is saying that run the event handlers during capturing phrase whenever possible.

main.js



a.addEventListener(
  'click',
  () => {
    console.log('a');
  },
  true // a boolean
);

c.addEventListener(
  'click',
  () => {
    console.log('c');
  },
  { capture: true } // an object
);

We click on c, it runs the a event handler first because it is registered for capturing phrase.

We can read eventPhrase from the event information to see during which phrase that the event handler is triggered. Capturing phrase is 1. At target is 2. Bubbling phrase is 3.

main.js



// a will run in target phrase or capturing phrase if possible.
a.addEventListener(
  'click',
  (e) => {
    console.log('a', e.eventPhase);
  },
  true
);

// b will run in target phrase or bubbling phrase if possible.
b.addEventListener('click', (e) => {
  console.log('b', e.eventPhase);
});

// c will run in target phrase or capturing phrase if possible.
c.addEventListener(
  'click',
  (e) => {
    console.log('c', e.eventPhase);
  },
  { capture: true }
);

Some events don't bubble. For example, focus and blur.

All JavaScript events go through the capturing and target phases. Whether an event enters the bubbling phase can be checked by the read-only bubbles property.

Sometimes we don't want this event propagation behavior. We can prevent it by calling e.stopPropagation() or e.stopImmediatePropagation() on the event object.

e.stopPropagation() stops event from propagating to other elements.

main.js



a.addEventListener(
  'click',
  (e) => {
    e.stopPropagation(); // stops propagating 
    console.log('a');
  },
  true // capture 
);

b.addEventListener('click', (e) => {
  console.log('b');
});

c.addEventListener('click', (e) => {
  console.log('c1');
});

c.addEventListener('click', (e) => {
  console.log('c2');
});

c.addEventListener('click', (e) => {
  console.log('c3');
});

Click on a or b or c all trigger the event handler on a first. We call e.stopPropagation() in the event handler, so event handlers on b and c will not run because event propagation is stopped.

e.stopImmediatePropagation() does what e.stopPropagation() does but also stops other event handlers on the target element. Let's see an example with e.stopPropagation() first and then replace it with e.stopImmediatePropagation() next.

main.js



a.addEventListener(
  'click',
  (e) => {
    console.log('a');
  },
  true // capture
);

b.addEventListener('click', (e) => {
  console.log('b');
});

c.addEventListener('click', (e) => {
  console.log('c1');
  e.stopPropagation(); // stops propagation here
});

c.addEventListener('click', (e) => {
  console.log('c2');
});

c.addEventListener('click', (e) => {
  console.log('c3');
});

Click on c, the event handlers on a run first because it captures, the event reach the target c and all c event handlers are called. b event handler doesn't run because event doesn't bubble to it by calling e.stopPropagation() in one of the c event handlers

Let's simply replace e.stopPropagation() in the example with e.stopImmediatePropagation()



c.addEventListener('click', (e) => {
  console.log('c1');
  // e.stopPropagation(); change this
  e.stopImmediatePropagation(); // to this
});

This time only one event handler of c that is before e.stopImmediatePropagation() is called, others are stopped. So e.stopImmediatePropagation() not only stops the event propagation, it also stops the rest of the event handlers of the target from running.

Event delegation

Event delegation is a pattern that utilizes event propagation. We know that event can propagate to ancestor elements. If we have 1000 list items that behave in a similar way, we can add event listeners on their common ancestor rather than add event listeners on each item.

Let's see how it works with examples.

styles.css



div {
  margin: 4px;
  padding: 4px;
  border: 1px solid;
}

main.js



function createItems() {
  // make items HTML
  const divsHTML = Array.from({ length: 10 })
    .map((a, index) => {
      return `<div class="item">${index}</div>`;
    })
    .join('');

  // wrap items in an element and add them to body
  document.body.innerHTML = `
    <div class="list">
      ${divsHTML}
    </div>`;
}

createItems();

Add event listener to each item. When each item are clicked, doSomething(item) will be called with the item.

main.js



function doSomething(item) {
  console.log('do something with this item', item);
}

const items = document.querySelectorAll('.item');
items.forEach((item) => {
  item.addEventListener('click', () => {
    doSomething(item);
  });
});

When we click on each item, doSomething() is called with the item that was clicked.

Let's use event delegation to add a event listener on items' common ancestor .list, so we can add only one event listener instead of 10.

main.js



function doSomething(item) {
  console.log('do something with this item', item);
}

const list = document.querySelector('.list');
list.addEventListener('click', (e) => {
  // We can tell which element trigger the event by accessing `e.target`
  doSomething(e.target);
});

This would work, but it has a problem. doSomething expect to be called with an item. In this example, we call doSomething() with e.target, but e.target doesn't guarantee to be the item. It can be anything that can trigger the event handler. It can be the .list element itself or other elements inside .list.

Update the createItems function



function createItems() {
  const divsHTML = Array.from({ length: 10 })
    .map((a, index) => {
      return `
      <div class="item">
        ${index}
        <button>a feature</button> // add a button here
      </div>`;
    })
    .join('');

  document.body.innerHTML = `
    <div class="list">
      ${divsHTML}
    </div>`;
}

When we click on the .list itself, an item, and a button inside the item, They all trigger the event handler on .list. But the e.target are different. This means that we can't simply pass e.target without any check to a function that expects an item. That would break our app.

Luckily, there are two methods we can call on an element to check if we get the correct target, element.matches() and element.closest(). Their parameter is the same as element.querySelector(). element.matches(selector) will return true if it matches the selector.

main.js



list.addEventListener('click', (e) => {
  // if e.target does not match .item
  // we don't want to run the rest of the code
  if (!e.target.matches('.item')) return;

  doSomething(e.target);
});

Now only click on '.item' will trigger the event listener on .list.

Clicking on .list and the button doesn't trigger the event handler, since they are not relevant to doSomething(item). This is what we want. What if we have other elements inside an .item but clicking on them should be consider clicking on the item.

Update createItems function again



function createItems() {
  // ...
      <div class="item">
        ${index}
        <button>a feature</button>
        <span>lorem</span> // add this line
      </div>`;
 // ...
}
```

Let's say we have some description about the item. So clicking on them can be perceived as clicking on the item. But `span` doesn't match `.item`, the event handler won't run.
![click on lorem doesn't run event handler](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m5hvmyxb0zg4rk7iqhz5.gif)

styles.css
```css
/* making all descendants inside item non clickable */
.item * {
  pointer-events: none;
}

/* we can use this on an element inside .item to revert the above declaration. */
.pointer-events-auto {
  pointer-events: auto;
}
```

Add the class to the button inside `createItems` function.

main.js
```js
<button class="pointer-events-auto">a feature</button>
```

Now clicking on the `span` element can trigger the event handler on `.list` that runs doSomething(item). In fact, we are not clicking on the span, we are clicking the `.item`. The span is not clickable because of the CSS rule we set. 
![click on span works](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/n5vf96saeapp4agcckwk.gif)

Let's try another solution with `element.closest()`. First, remove the CSS we did.

`element.closest(selector)` will return the closest element that matches the selector, including the element itself. This means if we click on any element inside `.item` or `.item` itself, `e.target.closest('.item')` will return the `.item` element.


main.js
```js
list.addEventListener('click', (e) => {
  // find the closest item element from e.target
  const item = e.target.closest('.item');
  // if we don't have an item
  // we don't want to run rest of the code
  if (!item) return;

  doSomething(item);
});
```

Now clicking on every element in `.item` works. But clicking the button shouldn't trigger the doSomething(item), because we have other things for it to do.
![use closest](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tamjxzmrnnki9kfrdsgp.gif)

We can use `element.matches()` and `element.closest()` together.

main.js
```js
function createItems() {
  //...
    // add a class to button so we can filter this element with its selector more precisely
    <button class="item-feature-btn">a feature</button> 
  //...
}

list.addEventListener('click', (e) => {
  // we don't want this handler to run when it is clicked on the button
  if (e.target.matches('.item-feature-btn')) return;
  const item = e.target.closest('.item');
  if (!item) return;
  doSomething(item);
});

// do something when the button is clicked
list.addEventListener('click', (e) => {
  if (!e.target.matches('.item-feature-btn')) return;
  console.log('handle button click');
});
```

Events are handled properly.
![nice](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/l20t3297qvie6inbq4av.gif)


We can also stop the propagation on button. But in this scenario we use event delegation one the same target. We'll need to consider the order of `addEventListener` and call `e.stopImmediatePropagation()` at the right place. It will be much simpler to do so when we `addEventListener` directly on the button and call `e.stopPropagation()`. 

---


## Wrap up
`addEventListener` is easy to use, but it has a lot of detail that we should be aware of. I hope this article can help you start using `addEventListener` with confidence and be able to identify the problem when something doesn't work as expected.

Promise and async await

Gohomewho — Sun, 31 Jul 2022 18:22:00 +0000

Probably most of us learn Promise for the first time is when we start learning how to call an API with fetch to get recourses on the web. They are two complex topics. It is difficult to learn them at once. In this article, we will learn how to use Promise and its syntax sugar async await. So later when you learn fetch, you don't need to worry about Promise.

By the way, if you don't know what API means or you have been confused by the term, I like to think it as anything that people make it easy for us to use. In web, people usually refers API to an URL that you can simply call it, and it will give you data or do some stuff on the server side. API can mean different things in different context. Promise is a browser API, which means that it is not a built in feature in JavaScript. If we run JavaScript in Browsers, we can easily use those browser API, because people have made them easy for us.

If you'd like to follow along, you can open the console of devtools and code right there. It would be better to open the console on a new browser tab, because sometimes there are errors that you need to refresh to get rid of, but you don't want to refresh the page you currently reading.

Understand how to use promise

I think there are two keys to understand how to use Promise, callback and the order of code execution.

Callback

Callback is essentially a function, it is passed to another function as an argument. How callback is called and used is decided inside the function that we pass the callback to. Let's look at an example.

// make a function that accept a callback
function myFunc(callback) {
  const state = {
    status: 'pending',
    value: undefined
  } 

  // callback is just a variable name that you can name it whatever you like
  // but since we call it like a function, it has to be a function
  // here, we just simply call it
  callback()

  return state 
}

Calling myFunc without passing a function as an argument. That callback parameter inside myFunc will be undefined, so this will error.

myFunc() 
// Uncaught TypeError: callback is not a function

Passing a function as a callback to myFunc. We can define inline function as an argument directly when we are calling a function.

myFunc(() => {
  console.log('hello')
})
// hello
// {status: 'pending', value: undefined}

'hello' is logged by the callback and the object is returned by myFunc.

Generally when you see a function that accept a callback, that callback will be called with some variables that lives inside the function.

function myFunc(callback) {
  const state = {
    status: 'pending',
    value: undefined
  } 

  // add a function
  function resolve() {
    state.status = 'fulfilled'
  }

  // add another function
  function reject() {
    state.status = 'rejected'
  }

  // pass new added function as arguments
  callback(resolve, reject)

  return state
}

Now our callback is called with two arguments, so we can define the callback with two parameters.

const result = myFunc((res, rej) => {})
result // {status: 'pending', value: undefined}

I name the parameters of the callback res and rej on purpose. We can name parameters whatever we want. But if we don't call the callback in myFunc with those two arguments resolve and reject, then res and rej will be undefined. Just like what we saw earlier why we call myFunc() without passing a callback will show error. res and rej do not magically appear. It can be confused because normally we would define a function before we use it. On the other hand, callback is like it is used before we define it. Because it is already used somehow and somewhere inside a function, we'll need to follow the rules.

We can call the resolve function passed from myFunc in our callback.

const result = myFunc((res, rej) => {
  res() // res is the resolve function passed from myFunc
})
// status becomes 'fulfilled'
result // {status: 'fulfilled', value: undefined}

Modify resolve and reject function so they can take value and change the state.

function myFunc(callback) {
  const state = {
    status: 'pending',
    value: undefined
  } 

  // accept a parameter
  function resolve(v) {
    state.status = 'fulfilled'
    // modify state.value with that parameter
    state.value = v
  }

  // add a parameter
  function reject(v) {
    state.status = 'rejected'
    // modify state.value with that parameter
    state.value = v
  }

  callback(resolve, reject)

  return state
}

Calling resolve with a value in the callback.

// we only want to call resolve
// so we can omit defining a second parameter on the callback
const result = myFunc((res) => {
  res('nice')
})
result // {status: 'fulfilled', value: 'nice'}

Calling reject with a value in the callback.

const result = myFunc((res, rej) => {
  rej('bad')
})
result // {status: 'rejected', value: 'bad'}

We can use a condition to determine whether we call resolve or reject.

const result = myFunc((res, rej) => {
  // a lots of logic
  // ...
  const someCondition = true // imagine it could be true or false

  if(someCondition === true) {
    res('nice')
  } else {
    rej('bad')
  }
})

Generally, a function that accepts callbacks is more generic, and the callbacks are for us to control the state that created from the function. In our example, myFunc accept a callback and call that callback with two functions resolve and reject. In that callback, we can do some computation and use resolve and reject as we want to modify the state created from myFunc.

We could also call res and rej "callbacks". Personally, I often get confused by the word, so I just call them "functions" and focus on the code rather than a term.

Now we know how things get passed around with callback, we can move on to the next part.

The order of code execution

JavaScript runs synchronous code immediately. Synchronous code can schedule something to run asynchronously. When an asynchronous task is done and ready to do something else, it will be run after the current synchronous code is finished.

What is synchronous code

Synchronous code are run one by one. console.log() is synchronous code, we run it and it finishes instantly.

console.log(1) // run after previous code
console.log(2) // run after console.log(1)
console.log(3) // run after console.log(2)
// 1
// 2
// 3

What is asynchronous code

setTimeout() is a browser API that can schedule something to run asychronously. In this example, setTimeout() is called immediately after console.log(1) and right before the console.log(3). The callback we pass to setTimeout(), however, is run asynchronously. That's why we'll see 3 being logged before 2.

console.log(1) // run after previous code
// setTimeout is run immediately after console.log(1)
setTimeout(() => {
  console.log(2) // the callback is scheduled to run asynchronously after 1000ms   
}, 1000)
console.log(3) // run after setTimeout
// 1
// 3 
// 2

The second argument of setTimout() schedules how much time to run the callback later. 1000ms doesn't guarantee to be exactly 1000ms. It has to wait current synchronous code to be finished. For example, if the timer is count to 999ms, and there is an user interaction that triggers a for loop that takes 500ms to run, the callback of the setTimout() will need to wait that for loop, asynchronous code won't interrupt the order of current synchronous code.

Asynchronous code are always run after current synchronous code. Although we set the second argument of setTimeout() to 0ms, the callback of setTimeout() is still scheduled as an asynchronous code, it has to wait current synchronous code to be finished.

console.log(1)
setTimeout(() => {
  console.log(2) 
}, 0) // set delay to 0ms
console.log(3) 
// 1
// 3 
// 2

We can imagine that JavaScript has a list of current synchronous code waiting to be executed. When asynchronous code is ready, it will be added at the end of that list and becomes part of the synchronous code.

If you are interested in learning more about how JavaScript run our code, I would recommend watching this series on YouTube created by Akshay Saini

Promise

Promise is a way to schedule asynchronous code. Unlike setTimeout that only schedules asynchronous code to run later. We can run synchronous code when we create a Promise and schedule other things to run asynchronously. Let's first learn how promise work on its own, and then we'll learn how it works with other code.

How promise works on its own

This is how we create a Promise. new Promise() with a callback () => {}. new is a JavaScript keyword used to create a new object. We can create an array like this new Array(), but usually we simply write the literal form []. Promise doesn't have a literal form, so we need to create one like new Promise(callback).

new Promise(() => {})
// Promise {<pending>}

Notice that there is an callback that does nothing. If we don't provide a callback to new Promise(), it will error. If you don't know why, you probably should go back to previous section where we break down callback.

Inside Promise, it calls our callback with two arguments, resolve and reject. They are two functions provided from the promise to our callback. They are used to control the state of Promise.

new Promise((resolve, reject) => {})
// Promise {<pending>}

When we call resolve(), the state of the promise becomes "fulfilled".

new Promise((resolve, reject) => {
  resolve()
})
// Promise {<fulfilled>: undefined}

We didn't pass argument to resolve(), so the result of this promise is undefined. it's like when we call a function that doesn't not explicitly return anything, the function will always return undefined.

This time we resolve() the promise with a value 'nice'. The state of the promise becomes "fulfilled" and the result is "nice".

new Promise((resolve, reject) => {
  resolve('nice')
})
// Promise {<fulfilled>: 'nice'}

A promise could be resolved or rejected. reject works similar to resolve, it changes the state of the promise and provides a result.

new Promise((resolve, reject) => {
  reject('bad')
})
// Promise {<rejected>: 'bad'}

If you run this code, you will see Uncaught (in promise) bad. We'll deal with it later, so let's ignore it for now.

At this point, we only make synchronous code.

console.log(1)
new Promise((resolve, reject) => {
  console.log(2)
  resolve('nice')
  console.log(3)
})
console.log(4)

// this result shows that everything runs in order, synchronously.
// 1
// 2
// 3
// 4

Keep one thing in mind, when we construct a promise, it schedules something to run asynchronously immediately. The action of starting a task is synchronous. It is the action of handling the result of resolve or reject being asynchronous.

So, how do we handle the result?
Promise object has a .then method that we can use to handle the result of a "fulfilled" state promise which has been resolved with resolve().

.then() also accept a callback, it will pass the result of the previous Promise to the callback.

new Promise((resolve, reject) => {
  resolve('nice')
}).then((result) => {
  console.log(result)
})

// nice

If you run this code in the console, you probably have noticed one thing. After "nice" is logged, there is a promise logged.

// Promise {<fulfilled>: undefined}

Before we learn where this promise comes from, we need to know why it is logged.

When we call a function in the console, it will automatically log the result of the function. If a function doesn't explicitly return anything, it returns undefined.

console.log(1)
// 1 
// console.log() doesn't explicitly return anything, so it returns undefined.
// undefined

I am using chrome and I am not sure if this happens in other browsers.

Alright, so where does that promise come from? In fact, what we return from .then() will be a new "fulfilled" state promise with the result of the returned value. We only console.log(result) in .then() and didn't return anything explicitly, so the result is undefined.

new Promise((resolve, reject) => {
  resolve('nice')
}).then((result) => {
  console.log(result)
})

// nice
// Promise {<fulfilled>: undefined}

This means that we can chain .then on and on.

new Promise((resolve, reject) => {
  resolve('nice')
}).then((result) => {
  console.log(result) // 'nice'
}).then((result) => {
  console.log(result) // undefined
})

We can use .catch() to handle the result of a "rejected" state promise which has been rejected with reject(). We can schedule something to run like promise1.then().then().catch(). if one of the promises in the chain is rejected, .then() will be skipped and .catch() will take the rejected result.

new Promise((resolve, reject) => {
  reject('bad')
}).then((result) => {
  // previous promise is rejected, so the code inside .then() is skipped
  console.log(result)
}).catch((error) => {
  console.log(error) // bad is logged from here
})

// bad

We handle the rejected promise, so we won't see Uncaught (in promise) bad error this time. You probably have noticed Promise {<fulfilled>: undefined} appear in the console again. This is something you'd like to keep in mind. What we return from .catch() is also a "fulfilled" state promise.

We can return a rejected promise in .then() or .catch() with throw new Error('some message').

new Promise((resolve, reject) => {
  resolve('nice')
}).then((result) => {
  if(result !== 'great') {
    // throw error inside .then will return a rejected promise
    throw new Error('not good enough') 
  }
}).catch((error) => {
  console.log(error) 
})

// Error: not good enough

Throwing an error inside .catch().

new Promise((resolve, reject) => {
  reject('bad')
}).then((result) => {
  console.log(result) 
}).catch((error) => {
  if(error === 'bad') {
    throw new Error('this is really bad')
  }
})

// Uncaught (in promise) Error: this is really bad

The error we see in the console proves that we returns a rejected promise.

Promise.reject() is an another way to return a rejected promise. This is useful when we want to return a more complex data like an object.

// return a rejected promise in .then
new Promise((resolve, reject) => {
  resolve('nice')
}).then((result) => {
  return Promise.reject({reason: 'something went wrong'})
})
// Promise {<rejected>: {…}}

// return a rejected promise in .catch
new Promise((resolve, reject) => {
  reject('bad')
}).catch((error) => {
  return Promise.reject({reason: 'something went wrong'})
})
// Promise {<rejected>: {…}}

Notice that we didn't add new keyword to Promise.reject(). It is a method available on the Promise object. It's similar to how we call Array.isArray(), using the Array object.

Returning another rejected promise from .catch() seems to be redundant. The idea is that sometimes we would handle in different ways. Returning a rejected promise means that we can .catch() it in other places.

How promise work with other code

So far we only make Promise and resolve or reject it immediately. In real world, we usually don't know how much time doing something can take, but we want to react to it as soon as something is done. That's the value of scheduling asynchronous code with Promise. Let's see an example to help understand how asynchronous code run.

// define a variable 
let promiseResolver = null

new Promise((resolve, reject) => {
  // store the resolve of this promise to the variable
  promiseResolver = resolve
}).then((result) => {
  console.log(1, result)
}).then((result) => {
  console.log(2, result)
})

// This is the first promise we created with new Promise(callback)
// Promise {<pending>}

We don't see 1 and 2 being logged from those two .then() because .then() is only called when the previous promise is resolved.

Now we can call the resolve function stored in promiseResolver to resolve the first promise.

promiseResolver('hello')
// 1 'hello'
// 2 undefined

As soon as we call promiseResolver('hello'), first .then() can run and 1 is logged as expect. second .then() also runs because the first .then() implicitly return a "fulfilled" promise with a value undefined. That's why the second log is 2 undefined. Although we see the results from .then() right after we resolve the first promise, asynchronous code has to wait the current synchronous code to be finished, which means that if a promise is resolved or rejected during some synchronous code running, .then() or .catch() will be queued and run after those synchronous code already in the list are finished.

A promise can only be "fulfilled" or "rejected" once. Let's modify the example and explicitly return a new promise in the first .then().

let promiseResolver = null

new Promise((resolve, reject) => {
  promiseResolver = resolve
}).then((result) => {
  console.log(1, result)
  // explicitly return a new promise
  return new Promise(() => {})
}).then((result) => {
  console.log(2, result)
})

promiseResolver only stores the resolve function of the first promise, so calling it multiple times will only work for the first time.

// resolve first promise
promiseResolver('hello')
// 1 'hello'

// no effect
promiseResolver('hello')
promiseResolver('hello')
promiseResolver('hello')

The second .then() will never be triggered because we didn't store the resolve function of the promise returned from the first promise, which means that the state of the promise will always stay "pending".

This time we also store the resolve function of the promise returned from first .then().

let promiseResolver = null

new Promise((resolve, reject) => {
  // store resolve function of this promise
  promiseResolver = resolve
})
.then((result) => {
  console.log(1, result)
  // explicitly return a new promise 
  return new Promise((resolve, reject) => {
    // store resolve function of this promise
    promiseResolver = resolve
  })
})
.then((result) => {
  console.log(2, result)
})

Resolving the first and the second promise with the resolve functions that were assigned to promiseResolver.

// resolve first promise created by new Promise()
promiseResolver('hello')
// run first .then
// 1 'hello' 

// resolve second promise returned by first .then
promiseResolver('hi')
// run second .then
// 2 'hi'

Again, .then only runs after the previous promise is resolved.

Let's see how promise work with more synchronous code.

console.log(1)
new Promise((resolve, reject) => {
  console.log(2)
  resolve()
  console.log(3)
}).then(() => {
  console.log(4) // 4 is here
})
console.log(5)

// 1
// 2
// 3
// 5
// 4 is here

This is a promise that resolves immediately. The code inside new Promise()'s callback is synchronous. Promise can schedule asynchronous code with .then(). We want to console.log(4) after the promise is resolved as soon as possible, but asynchronous code has to wait until all synchronous code are finished. When JavaScript see asynchronous code, it will put asynchronous code aside and read next statement. if next statement is synchronous, JavaScript runs that code immediately. if next statement is asynchronous, JavaScript puts that code aside again and read the next statement. When asynchronous code is ready to be run, it will be queued to the end of the synchronous code. That's why 4 is logged after 5.

Challenge:

Can you reason about the result of this snippet?

console.log(1)

new Promise((resolve, reject) => {
  console.log(2)
  resolve()  
}).then(() => {
  console.log(3) 
})

new Promise((resolve, reject) => {
  resolve()
  console.log(4)
}).then(() => {
  console.log(5) 
}).then(() => {
  console.log(6) 
})

new Promise((resolve, reject) => {
  console.log(7)
  resolve()  
}).then(() => {
  console.log(8) 
})

console.log(9)

Result:

It's totally fine if you don't get the correct result by reading the snippet, but I think you are able to tell why after you see the result. We won't use promises like this snippet in real world. This is only for testing if you understand the order of synchronous and asynchronous code.

async await

async function and await is the syntax sugar to work with Promise.

Creating an async function is easy. Define a function and put the async keyword before the function keyword. What we return from a async function will implicitly be a "fulfilled" promise.

async function myFunc() {

}
myFunc()
// Promise {<fulfilled>: undefined}

We can explicitly throw new Error or return Promise.reject() to return a rejected promise.

async function myFunc() {
  return Promise.reject({reason: 'something went wrong'})
}
myFunc()
// Promise {<rejected>: {…}}

The benefit of using async function is that we can use await keyword to make asynchronous code look like synchronous code.

async function myFunc() {
  console.log(1)
  // await will wait this promise to be done before moving on to next statement.
  await new Promise((resolve, reject) => {
    console.log(2)
    resolve()
  })
  // below code runs after the promise being await is done
  console.log(3)
}

myFunc()
// 1
// 2
// 3

This is the same code writing without async and await. We need to chain a .then() to get the correct order of running console.log(3).

function myFunc() {
  console.log(1)
  new Promise((resolve, reject) => {
    console.log(2)
    resolve()
  }).then(() => {
    console.log(3)  
  })
}

myFunc()

We can await a promise to store the result of a "fulfilled" promise with a variable

async function myFunc() {
  const result = await new Promise((resolve, reject) => {
    resolve('hello')
  })
  console.log(result)
}

myFunc()
// hello

async function returns a promise, so it can also be await. Unless we explicitly return something or the code reach the end of a async function, the promise state would be "pending", which means that calling an async function with await, the code of that async function has to be done before moving on.

// async function returns a promise
async function myFunc() {
  console.log(1)
  await new Promise((resolve, reject) => {
    console.log(2)
    // delay the resolve
    setTimeout(() => {
      resolve()
    }, 1000)   
  })
  console.log(3)
}

// calling another async function inside this async function
async function anotherFunc() {
  console.log(4)
  // await an async function
  await myFunc()
  console.log(5)
}

anotherFunc()
// 4
/*
  await myFunc()
  1
  2 
  wait 1000ms
  3           
*/
// 5

We can use try catch to handle rejected promise inside async function.

async function myFunc() {
  try {
    await new Promise((resolve, reject) => {
      reject('something went wrong')
    })
  } catch(error) {
    console.log(error)
  }
}

myFunc()
// something went wrong

try catch is not a special thing for async function. It is meant to be used to catch errors.

We can handle error in the child scope and return a "fulfilled" promise, and decide what to do with the result inside the parent scope.

async function myFunc() {
  try {
    await new Promise((resolve, reject) => {
      // change the rejected value here to see different result from calling anotherFunc()
      reject('not a big deal')
    })
  } catch(error) {
    if (error === 'not a big deal') {
      return 'ok'
    } else {
      return 'bad'
    }
  }
}

async function anotherFunc() {
  try {
    // the function being called is the child scope
    const result = await myFunc()
    if (result === 'ok') {
      console.log('keep running code below')
    } else {
      throw new Error('throw error in try will jump to catch')
    }
    // other code
    // ...
  } catch(error) {
    console.log(error)
  }
}

anotherFunc()
// keep running code below

We can also return a rejected promise from the child scope, so we don't need to examine the result again in try block of the parent scope and can handle the error directly in catch block.

async function myFunc() {
  try {
    await new Promise((resolve, reject) => {
      reject('is a big deal')
    })
  } catch(error) {
    if (error === 'not a big deal') {
      return 'ok'
    } else {
      // explicitly return a rejected promise
      return Promise.reject('bad')
    }
  }
}

async function anotherFunc() {
  try {
    // await a promise that is rejected will jump to catch
    const result = await myFunc()

    // there is an error above 
    // so rest of the code in try block won't run
    // ...
  } catch(error) {
    console.log(error)
  }
}

anotherFunc()

Which one should be used is based on your needs.

Wrap up

In this article, we learn the necessary fundamentals to understand Promise. We learn how to use Promise and also learn how to use async await to work with Promise. I've tried to make this article as simple as possible, but learning promise can be frustrated. I hope this article can help make your journeys a little bit easier.

Array

Gohomewho — Sun, 24 Jul 2022 16:40:14 +0000

We use array to store a list of items. Generally, we put items that are relational in an array, so we can easily loop through the items and do something with them.

Basics

Let's start by creating an array. [] creates an array.

const a = [] // This is an empty array

We can store any kind of data inside an array. For example, we can store a number 1, a string '2', a function, and an empty array. Each item is separated by a comma ,.

const a = [1, '2', function hi(){}, []]

Array items are ordered. Their indexes start from 0. We can use index to access item like this, a[0] accesses index 0 item of array a.

const a = [1, '2', function hi(){}, []]
a[0] // 1
a[1] // '2'
a[2] // ƒ hi(){}
a[3] // []

The [] of a[0] doesn't create a new array. It's the syntax to access an item in an array with a given index.

We can use .length to check how many items that an array has.

a.length // 4

Note that this is a property not a method (function). So we don't need () to use it like a function a.length().

If array index starts from 1, then the index of the last item will equal to the length of an array. But we already know that array index starts from 0. So except empty array, the index of the last item will always be one less than the array length.

const a = [10, 20, 30]
a.length // 3
const lastItemIndex = a.length - 1
lastItemIndex // 2
const lastItem = a[lastItemIndex]
lastItem // 30

Update array

We can still change (mutate) an array after we create it.

const a = [1, '2']

// array.push() can add an item or items at the end of the array
a.push('hi') 

// array.unshift() can add an item or items at the start of the array.
a.unshift('hello')

a // ['hello', 1, '2', 'hi']

// array.pop() removes the last item from the array and returns that item 
const removedLastItem = a.pop() 
removedLastItem  // 'hi'

// array.shift() removes the first item from the array and returns that item 
const removedFirstItem = a.shift() 
removedFirstItem // 'hello'

a // [1, '2']

We can also change or set an item at a given index.

const a = [1, '2']
a[0] = 5
a[1] = '6'
a // [5, '6']

// add a item at index 2 which is the last item in this case
a[2] = 7
a // [5, '6', 7]

// this is like using a.push('8')
a[a.length] = '8'
a // [5, '6', 7, '8']

If we use index to set an item and the index is higher than the array.length, then there will be empty slots filled in those skipped indexes.

a[10] = 10
a // output from chrome devtool console [5, '6', 7, '8', empty × 6, 10]

a.length // 11

We can avoid using an index that doesn't currently exist in the array for setting item to avoid this issue.

Each array is unique

One thing to keep in mind is that when we create an array, we create a new value. Here, value refers to a memory space in the computer, not what we put inside an array.

const a = []
const b = []
console.log(a === b) // false

Although a and b look identical, they are two values in the memory. That's why they are not equal.

On the other hand, if we have many variables reference to the same array, the result of changing that array will be reflected to those variables. That's because they all points to the same value.

// all variables point to the same array 
const a = [] 
const b = a 
const c = b 

// change that array through variable c
c.push('hi','how','are','you')

// the result is reflected to all variables
c // ['hi', 'how', 'are', 'you']
b // ['hi', 'how', 'are', 'you']
a // ['hi', 'how', 'are', 'you']

Update item

We can use index to update an item in the array. Before doing that, we need to find the index of an item. We can use array.indexOf() to find it.

array.indexOf() returns the index of first matched item. We can then use that index to update the item.

const a = ['a', 'b', 'c', 'd', 'c']
const targetIndex = a.indexOf('c')
targetIndex // 2
a[targetIndex] = 'ccc'
a // ['a', 'b', 'ccc', 'd', 'c']

array.indexOf() returns -1 if it doesn't find the item. We should check that returned number >= 0 before using it. Otherwise, we might introduce subtle bug in the future. Because if we accidentally set an item at index -1, later when we use array.indexOf() to find an item but it doesn't exist and return -1, access array[-1] will find the item that was set accidentally.

const a = ['a', 'b', 'c', 'd']

// 'e' doesn't exist in array, so this will return -1
const targetIndex = a.indexOf('e') 

// we meant to update 'e' to 'g' 
// but accidentally set an item at index -1 
a[targetIndex] = 'g' 

// a.indexOf('g') return -1, but it doesn't actually find the index of 'g'
// it returns -1 because a.indexOf('g') cannot find the item
const newTargetIndex = a.indexOf('g')
newTargetIndex // -1 
a[newTargetIndex] // 'g'

// making change to the item
a[newTargetIndex] = 'hi'

// array.includes() can check if an item exist in the array
// we just set an item 'hi'. why doesn't it exist in the array?
a.includes('hi') // false

// because negative indexed item doesn't get counted.
a.length // 4

a // output from chrome devtool console ['a', 'b', 'c', 'd', -1: 'hi']

Imagine that we think we find the item and start working on it. Later, we could run into some bugs because the negative indexed item doesn't count in the array which means we've been working on a wrong target.

Suppose we want to update all 'c' to 'ccc', we'll need to repeat the action.

const a = ['a', 'b', 'c', 'd', 'c']

let targetIndex = a.indexOf('c')
targetIndex // 2
a[targetIndex] = 'ccc'
a // ['a', 'b', 'ccc', 'd', 'c']

targetIndex = a.indexOf('c')
targetIndex // 4
a[targetIndex] = 'ccc'
a // ['a', 'b', 'ccc', 'd', 'ccc']

What if we don't know the how many 'c' in the array in advance? Doing something like this doesn't guarantee to work.

a[a.indexOf('c')] = 'ccc'
a[a.indexOf('c')] = 'ccc'
a[a.indexOf('c')] = 'ccc'
a[a.indexOf('c')] = 'ccc'
a[a.indexOf('c')] = 'ccc'

A better solution to is using a loop.

Loop through array

Looping through arrays is so common that there are many built-in array methods that help make our lives easier. We'll learn how to use them step by step.

for loop

We use for loop to do something multiple times. we can also use for loop to loop through an array. We set let i = 0; as the starting point of for loop, because index start from 0.
We set the condition to i <= a.length - 1; because the index of last item is a.length - 1. We set i++ increase i by one each run because array index also increase by 1.

const a = [1, 2, 3, 4, 5]

for (let i = 0; i <= a.length - 1; i++) {
  console.log(a[i])
}

// only change the condition to i < a.length
// it's same as above
for (let i = 0; i < a.length; i++) {
  console.log(a[i])
}

This way, we change loop through every item in an array.

Let's bring back our previous example and use for loop to update all c to ccc.

const a = ['a', 'b', 'c', 'd', 'c']

for (let i = 0; i < a.length; i++) {
  // check if the item at index i is 'c'
  const isTarget = a[i] === 'c'

  // if true, update the item at index i 
  if(isTarget) {
    a[i] = 'ccc'
  }
}

a // ['a', 'b', 'ccc', 'd', 'ccc']

Now, no matter how many occurrences of 'c' in the array, we can use this for loop to update them to 'ccc'.

Usually, we won't create an array and loop through it immediately. Let's wrap that for loop inside a function so we can use it later.

const a = ['a', 'b', 'c', 'd', 'c']

function updateItemInArray(){
  for (let i = 0; i < a.length; i++) {
    const isTarget = a[i] === 'c'

    if(isTarget) {
      a[i] = 'ccc'
    }
  }
}

// imaging we run so much other code here...

// at some point we want to run our for loop
updateItemInArray() 

a // ['a', 'b', 'ccc', 'd', 'ccc']

Currently, the function only works on array a and update c to ccc. We can make the function more reusable. Let's start by making it take other arrays. Add a parameter called array to updateItemInArray and change a to array in for loop.

const a = ['a', 'b', 'c', 'd', 'c']

function updateItemInArray(array){
  for (let i = 0; i < array.length; i++) {
    const isTarget = array[i] === 'c'

    if(isTarget) {
      array[i] = 'ccc'
    }
  }
}

updateItemInArray(a) // pass variable a to the function

a // ['a', 'b', 'ccc', 'd', 'ccc']

Now the function can update 'c' to 'ccc' on any array. This doesn't sound very useful. Instead of deciding how to change the items directly inside the function updateItemInArray, it will be better if we can decide it when we call the function.

We can achieve that by using a callback (function). Add a second parameter called callback to updateItemInArray. On Each run of the loop, we pass the current item array[i] to the callback and replace the item at that index with whatever return from the callback

const a = ['a', 'b', 'c', 'd', 'c']

function updateItemInArray(array, callback){
  for (let i = 0; i < array.length; i++) {
    // callback(array[i]) pass current item to callback
    // array[i] = callback(array[i]) replace current item with the returned value from callback
    array[i] = callback(array[i]) 
  }
}

We can define a function and pass it as a callback to updateItemInArray.

const a = ['a', 'b', 'c', 'd', 'c']

function updateItemInArray(array, callback){ // ... }

function myCallback(item){
  if(item === 'c') {
      return 'ccc'
  } 

  return item
}

updateItemInArray(a, myCallback)

a // ['a', 'b', 'ccc', 'd', 'ccc']

Or we can make an inline function when we call updateItemInArray.

updateItemInArray(a, (item) => {
  if(item === 'ccc') {
      return 'e'
  } 

  return item
})

a // ['a', 'b', 'e', 'd', 'e']

Nice! updateItemInArray becomes easy to be reused. There is one more thing we can do. We can pass more information to callback, so the callback can access those information when needed.

function updateItemInArray(array, callback){
  for (let i = 0; i < array.length; i++) {
    // add extra arguments to callback
    array[i] = callback(array[i], i, array) 
  }
}

// if we only care about item and index in our callback
// we can skip the third parameter when defining the callback
updateItemInArray(a, (item, index) => index + item)

a // ['0a', '1b', '2e', '3d', '4e']

Array methods

There are many build-in array methods that serve different purpose. They are designed similar to the one we just made. We pass a callback to the function. How that callback is used is defined inside the function.

if callback return true, array.find(callback) will return that item

const a = ['a', 'b', 'c', 'd', 'c']
const result = a.find((item) => item === 'b')
result // 'b'

if callback return true, array.filter(callback) will return a new array with those item.

const a = ['a', 'b', 'c', 'd', 'c']
const result = a.filter((item, index) => index < 3)
result // ['a', 'b', 'c']

Similar to our updateItemInArray, array.map(callback) will return an with items of whatever the callback returns, but array.map(callback) doesn't change the original array.

const a = ['a', 'b', 'c', 'd', 'c']
const result = a.map((item) => {
  return { name: item }
})
result // [
  {"name": "a"},
  {"name": "b"},
  {"name": "c"},
  {"name": "d"},
  {"name": "c"}
]

Like array.map(callback), some array methods don't change the original array, but we might still accidentally change it. This usually happens when the items are objects. For example:

// we have an array of objects
const a = [
  {"name": "a"},
  {"name": "b"},
  {"name": "c"},
  {"name": "d"},
  {"name": "c"}
]

// we want to make a copy of the array and change some properties of each item
const result = a.map((item, index) => {
  // accidentally change a property of the item of this array
  item.name = index + item.name

  // return a new object with new value
  return { name: item.name }
})

// we get what we want
result // [
  {"name": "0a"},
  {"name": "1b"},
  {"name": "2c"},
  {"name": "3d"},
  {"name": "4c"}
]

// but we also change the original array
a // [
  {"name": "0a"},
  {"name": "1b"},
  {"name": "2c"},
  {"name": "3d"},
  {"name": "4c"}
]

It's hard to explain why changing original can cause problems if you haven't encountered any. The idea is that we unintentionally change something which will lead to unexpected results later in our program.

There are more useful build-in array methods, but I'll leave it for you to explore. After we understand why some array methods accept a callback, learning how to use them becomes so much easier.

Wrap up

In this article, we learn some basic operations of array. We learn some behaviors of array. And the most importantly, we learn how to loop through an array. The examples are not practical, but I think they are enough to demonstrate how things work. After we learn what array can do, we will know when and how to use them.