Forem: Radzion Chachura

Building a Guitar Triad Learning Tool with React

Radzion Chachura — Fri, 27 Jun 2025 14:21:51 +0000

This is part 9 of the series where we build a guitar theory app with React. Today we'll add a new page for learning triads – three-note chords that form the foundation of harmony in music. Triads are essential for understanding chord progressions, creating accompaniments, and building more complex chord structures. By mastering triads, guitarists gain a deeper understanding of how music works harmonically. You can find all the code in the GitHub repository.

Understanding Triads in the Context of Major Scale Patterns

Since most guitarists come to triads after learning the major scale, it's more intuitive to understand triads within the framework of the 5 major scale patterns. Triads are three-note chords built from the 1st (root), 3rd, and 5th degrees of a scale. These powerful building blocks form the foundation of Western harmony and are essential for chord construction across all musical genres.

When we overlay triads onto familiar major scale patterns, guitarists can immediately see how these chord structures relate to scales they already know. This approach has several advantages: it reinforces scale knowledge, reveals the harmonic relationship between scales and chords, and provides a systematic way to locate triads across the entire fretboard. Each major scale pattern contains all seven diatonic triads (I, ii, iii, IV, V, vi, vii°), giving guitarists a complete harmonic vocabulary within each position.

Core Triad Data Structure

import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"

export const triadIntervals = [1, 3, 5]

export const triadRomanNumerals = ["I", "ii", "iii", "IV", "V", "vi", "vii°"]

type ChordQuality = "major" | "minor" | "diminished"

export const chordQualities: ChordQuality[] = [
  "major",
  "minor",
  "minor",
  "major",
  "major",
  "minor",
  "diminished",
]

export const diatonicTriadsNumber = triadRomanNumerals.length

export const getTriadName = (index: number) => {
  const numberal = triadRomanNumerals[index]
  const quality = chordQualities[index]

  return [
    numberal,
    quality === "major" ? capitalizeFirstLetter(quality) : quality,
    "Triad",
  ].join(" ")
}

The getTriadName function constructs formatted names for each triad in the diatonic scale. It takes an index (0-6) and combines the corresponding Roman numeral (I, ii, etc.), chord quality (major, minor, diminished), and the word "Triad." Major qualities are capitalized, resulting in names like "I Major Triad" or "ii minor Triad" that clearly identify each chord's position and characteristic sound within the scale.

Static Site Generation for Triad Pages

To efficiently render our triad learning experience, we'll use Next.js static site generation to pre-build pages for every possible combination of root notes and triad positions. The following code creates static pages for all 12 chromatic notes combined with all 7 diatonic triads, resulting in 84 unique pages that load instantly without server-side processing. This approach maximizes performance while keeping our routing structure clean and SEO-friendly.

import { range } from "@lib/utils/array/range"
import { chromaticNotesNumber } from "@product/core/note"
import { fromUriNote, toUriNote } from "@product/core/note/uriNote"
import { diatonicTriadsNumber } from "@product/core/triads"
import { GetStaticPaths, GetStaticProps } from "next"

import { TriadPage } from "../../../../triad/TriadPage"

export default TriadPage

type Params = {
  index: string
  rootNote: string
}

export const getStaticPaths: GetStaticPaths<Params> = async () => {
  const paths = range(chromaticNotesNumber).flatMap((rootNote) =>
    range(diatonicTriadsNumber).map((index) => ({
      params: {
        index: index.toString(),
        rootNote: toUriNote(rootNote),
      },
    })),
  )

  return {
    paths,
    fallback: false,
  }
}

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const { rootNote, index } = params as Params

  return {
    props: {
      value: {
        rootNote: fromUriNote(rootNote),
        index: Number(index),
      },
    },
  }
}

State Management with TriadProvider

We will use TriadProvider to allow children components of the TriadPage to access the triad state directly, eliminating prop drilling. When a user selects a different triad index or root note, the useChangeTriad hook handles navigation to the corresponding page, maintaining our routing structure.

import { getValueProviderSetup } from "@lib/ui/state/getValueProviderSetup"
import { toUriNote } from "@product/core/note/uriNote"
import { useRouter } from "next/router"
import { useCallback } from "react"

export type TriadState = {
  index: number
  rootNote: number
}

export const makeTriadPath = ({ index, rootNote }: TriadState) =>
  `/triad/${[index, toUriNote(rootNote)].join("/")}`

export const { useValue: useTriad, provider: TriadProvider } =
  getValueProviderSetup<TriadState>("Triad")

export const useChangeTriad = () => {
  const value = useTriad()
  const { push } = useRouter()

  return useCallback(
    (params: Partial<TriadState>) => {
      push(makeTriadPath({ ...value, ...params }))
    },
    [push, value],
  )
}

Main Triad Page Component

The TriadPage component serves as the central organizing structure for our triad learning interface. It composes all the UI elements into a cohesive layout where guitarists can explore triads within each major scale pattern. The component uses a nested VStack structure to create visual hierarchy, separating the controls for root note and triad selection from the main content area. This separation helps players focus on one scale pattern at a time while maintaining access to navigation controls. The component renders each of the five major scale patterns in sequence, displaying how the selected triad fits within each pattern across the fretboard.

import { VStack } from "@lib/ui/css/stack"
import { ValueProp } from "@lib/ui/props"
import { range } from "@lib/utils/array/range"
import { scalePatternsNumber } from "@product/core/scale/ScaleType"

import { PageContainer } from "../layout/PageContainer"

import { ManageTriadIndex } from "./manage/ManageTriadIndex"
import { ManageTriadRootNote } from "./manage/ManageTriadRootNote"
import { TriadProvider, TriadState } from "./state/triad"
import { TriadOnMajorScalePattern } from "./TriadOnMajorScalePattern"
import { TriadPageTitle } from "./TriadPageTitle"

export const TriadPage = ({ value }: ValueProp<TriadState>) => (
  <TriadProvider value={value}>
    <PageContainer>
      <VStack gap={120}>
        <VStack gap={60}>
          <VStack gap={20} alignItems="center">
            <VStack alignItems="start" gap={20}>
              <ManageTriadRootNote />
              <ManageTriadIndex />
            </VStack>
          </VStack>
          <TriadPageTitle />
        </VStack>
        {range(scalePatternsNumber).map((index) => (
          <TriadOnMajorScalePattern key={index} scalePatternIndex={index} />
        ))}
      </VStack>
    </PageContainer>
  </TriadProvider>
)

Triad Selection Controls

The ManageTriadRootNote and ManageTriadIndex components both leverage the versatile GroupedRadioInput from RadzionKit, creating a consistent interface for musicians to select either root notes or triad positions.

import { GroupedRadioInput } from "@lib/ui/inputs/GroupedRadioInput"
import { InputContainer } from "@lib/ui/inputs/InputContainer"
import { InputLabel } from "@lib/ui/inputs/InputLabel"
import { range } from "@lib/utils/array/range"
import { chromaticNotesNames, chromaticNotesNumber } from "@product/core/note"

import { useChangeTriad } from "../state/triad"
import { useTriad } from "../state/triad"

export const ManageTriadRootNote = () => {
  const { rootNote } = useTriad()
  const setValue = useChangeTriad()

  return (
    <InputContainer>
      <InputLabel>
        Major scale root note: {chromaticNotesNames[rootNote]}
      </InputLabel>
      <GroupedRadioInput
        value={chromaticNotesNames[rootNote]}
        onChange={(noteName) => {
          const index = chromaticNotesNames.indexOf(noteName)
          setValue({ rootNote: index })
        }}
        options={range(chromaticNotesNumber).map(
          (index) => chromaticNotesNames[index],
        )}
        renderOption={(noteName) => noteName}
      />
    </InputContainer>
  )
}

Dynamic Page Title Generation

The TriadPageTitle component generates dynamic page titles and metadata based on the currently selected triad and root note. It extracts the root note name and triad information from the application state, then constructs formatted title and description strings that clearly identify the specific triad being studied. This component ensures our pages have meaningful titles for both users and search engines, helping guitarists understand exactly which triad and scale they're currently viewing.

import { PageMetaTags } from "@lib/next-ui/metadata/PageMetaTags"
import { chromaticNotesNames } from "@product/core/note"
import { getTriadName, triadRomanNumerals } from "@product/core/triads"

import { PageTitle } from "../ui/PageTitle"

import { useTriad } from "./state/triad"

export const TriadPageTitle = () => {
  const { rootNote, index } = useTriad()

  const rootNoteName = chromaticNotesNames[rootNote]
  const triadName = getTriadName(index)
  const romanNumeral = triadRomanNumerals[index]

  const title = `${rootNoteName} Major Scale - ${triadName} | Guitar Fretboard Patterns`
  const description = `Interactive guide to the ${triadName} (${romanNumeral}) in the ${rootNoteName} major scale. Learn how this triad appears across all standard scale patterns on the guitar fretboard.`

  return (
    <>
      <PageMetaTags title={title} description={description} />
      <PageTitle>
        {rootNoteName} Major Scale - {triadName}
      </PageTitle>
    </>
  )
}

Scale Pattern Generation

To render each of the 5 major scale patterns, we utilize the getFullScalePattern function. Since scale patterns deserve thorough explanation, there is a separate post covering both major and minor scale patterns here.

import { getLastItem } from "@lib/utils/array/getLastItem"
import { rotateArray } from "@lib/utils/array/rotateArray"
import { sum } from "@lib/utils/array/sum"
import { normalizeFretPositions } from "@product/core/note/normalizeFretPositions"

import { cagedChords, cagedTemplateDistances } from "../../chords/caged"
import { standardTuning } from "../../guitar/tuning"
import { shiftNotePositions } from "../../note/shiftNotePositions"
import { getFullScaleRelativeTonalityRootNote } from "../full/getFullScaleRelativeTonalityRootNote"
import {
  firstMajorScalePatternChord,
  majorScalePatterns,
} from "../full/majorScalePatterns"

import { ScalePatternResolver } from "./ScalePatternResolver"

export const getFullScalePattern: ScalePatternResolver = (input) => {
  if (input.scale.tonality === "minor") {
    return getFullScalePattern({
      ...input,
      scale: {
        ...input.scale,
        tonality: "major",
        rootNote: getFullScaleRelativeTonalityRootNote(input.scale),
      },
    })
  }
  const pattern = majorScalePatterns[input.index]

  const distances = rotateArray(
    cagedTemplateDistances.major,
    cagedChords.indexOf(firstMajorScalePatternChord),
  )

  const offset =
    input.scale.rootNote -
    getLastItem(standardTuning) +
    sum(distances.slice(0, input.index))

  const positionedPattern = shiftNotePositions(pattern, offset)

  return normalizeFretPositions(positionedPattern)
}

Visualizing Triads Within Scale Patterns

The TriadOnMajorScalePattern component visualizes how triads fit within each major scale pattern on the fretboard. For each pattern, it first retrieves the complete set of note positions using getFullScalePattern. Then it calculates the corresponding scale notes and rotates them based on the selected triad index—this rotation shifts our perspective to view the scale from the triad's root position. Each note on the fretboard is then assigned a scale degree (1-7), and the component highlights triad notes (degrees 1, 3, and 5) with a "primary" styling while rendering regular scale tones with standard styling. This creates a clear visual distinction between the three-note triad structure and the surrounding scale context, allowing guitarists to instantly recognize these chord tones within familiar scale patterns.

import { VStack } from "@lib/ui/css/stack"
import { rotateArray } from "@lib/utils/array/rotateArray"
import { getNoteFromPosition } from "@product/core/note/getNoteFromPosition"
import { getScaleName } from "@product/core/scale/getScaleName"
import { getScaleNotes } from "@product/core/scale/getScaleNotes"
import { getFullScalePattern } from "@product/core/scale/getScalePattern/full"
import { Scale } from "@product/core/scale/Scale"
import { scalePatterns } from "@product/core/scale/ScaleType"
import { getTriadName, triadIntervals } from "@product/core/triads"

import { Fretboard } from "../guitar/fretboard/Fretboard"
import { Note } from "../guitar/fretboard/Note"
import { SectionTitle } from "../ui/SectionTitle"

import { useTriad } from "./state/triad"

export const TriadOnMajorScalePattern = ({
  scalePatternIndex,
}: {
  scalePatternIndex: number
}) => {
  const { rootNote, index: triadIndex } = useTriad()

  const scale: Scale = {
    tonality: "major",
    rootNote,
    type: "full",
  }

  const scalePattern = getFullScalePattern({
    scale,
    index: scalePatternIndex,
  })

  const scaleNotes = rotateArray(
    getScaleNotes({
      rootNote,
      pattern: scalePatterns.full[scale.tonality],
    }),
    triadIndex,
  )

  const title = `${getTriadName(triadIndex)} on ${getScaleName(scale)} Pattern #${
    scalePatternIndex + 1
  }`

  return (
    <VStack gap={40}>
      <SectionTitle>{title}</SectionTitle>
      <Fretboard>
        {scalePattern.map((position) => {
          const scaleDegree =
            scaleNotes.indexOf(getNoteFromPosition({ position })) + 1

          const isTriadNote = triadIntervals.includes(scaleDegree)

          return (
            <Note
              key={`${position.string}-${position.fret}`}
              {...position}
              kind={isTriadNote ? "primary" : undefined}
            >
              {scaleDegree}
            </Note>
          )
        })}
      </Fretboard>
    </VStack>
  )
}

Conclusion

By mastering triads across the five major scale patterns, you'll develop a comprehensive understanding of chord construction that transfers to any musical context, allowing you to create more sophisticated harmonies and improvise with greater harmonic awareness throughout the entire fretboard.

Beyond switch-case: Type-safe Pattern Matching in TypeScript

Radzion Chachura — Sat, 21 Jun 2025 03:55:27 +0000

🐙 GitHub

Pattern matching in TypeScript has become an essential part of my daily workflow, both in React and Node.js. Personally, I haven't found a need for switch-case statements—I can't even recall the last time I used one. In this post, I'll share practical pattern matching techniques that I rely on regularly. All the reusable code can be found in the GitHub repository.

The Resolver Pattern: Type-safe Function Selection

Often, when we reach for a switch-case statement, our real goal is to run different logic depending on the value of a union type or enum. For example, in a music theory app, we need to generate different note patterns for different scale types. Each scale type—like blues, full, or pentatonic—has its own function that implements the specific logic for that scale, but all of these functions share the same input and output types, defined by the ScalePatternResolver interface. By creating a record that maps each scale type to its corresponding resolver function, we can easily select and call the right function based on the scale type, without needing a switch or if-else chain.

import { Scale } from "../Scale"
import { ScaleType } from "../ScaleType"

import { getBluesScalePattern } from "./blues"
import { getFullScalePattern } from "./full"
import { getPentatonicPattern } from "./pentatonic"
import { ScalePatternResolver } from "./ScalePatternResolver"

const resolvers: Record<ScaleType, ScalePatternResolver> = {
  blues: getBluesScalePattern,
  full: getFullScalePattern,
  pentatonic: getPentatonicPattern,
}

type RootScalePatternResolverInput = {
  index: number
  scale: Scale
}

export const getScalePattern = (input: RootScalePatternResolverInput) => {
  const resolver = resolvers[input.scale.type]

  return resolver(input)
}

If we ever introduce a new scale type but forget to add its resolver to this record, TypeScript will immediately flag the omission as an error. This safety net means we can confidently extend our code in the future, knowing that TypeScript will help us catch any missing cases during development.

The Match Function: Inline Pattern Matching

Most of the time, the logic we need to run for each value of a union type or enum is simple enough that creating a separate function for every case would be overkill. In these situations, it's much easier to define small handlers for each value right where we need them. That's where the match function is especially useful. For example, suppose we want to calculate a task's deadline timestamp based on its cadence.

import { match } from "@lib/utils/match"
import { convertDuration } from "@lib/utils/time/convertDuration"
import { TaskCadence } from "@product/entities/TaskFactory"
import { endOfISOWeek } from "date-fns"
import { endOfDay, getDaysInMonth, endOfMonth } from "date-fns"

type Input = {
  cadence: TaskCadence
  deadlineIndex?: number | null
  at: number
}

export const getRecurringTaskDeadline = ({
  cadence,
  deadlineIndex,
  at,
}: Input) =>
  match(cadence, {
    workday: () => {
      const dayEndedAt = endOfDay(at).getTime()
      const lastWorkdayEndedAt =
        endOfISOWeek(at).getTime() - convertDuration(2, "d", "ms")

      return Math.min(dayEndedAt, lastWorkdayEndedAt)
    },
    day: () => endOfDay(at).getTime(),
    week: () =>
      endOfISOWeek(at).getTime() -
      convertDuration(6 - (deadlineIndex ?? 0), "d", "ms"),
    month: () => {
      const daysInMonth = getDaysInMonth(at)
      return (
        endOfMonth(at).getTime() -
        convertDuration(
          daysInMonth - 1 - Math.min(deadlineIndex ?? 0, daysInMonth - 1),
          "d",
          "ms",
        )
      )
    },
  })

Pattern Matching for API Interactions

Here's another example that shows how pattern matching can streamline logic when working with multiple OAuth providers. Instead of relying on nested conditionals, the match function lets us directly associate each provider with its specific logic for fetching user information—Google uses a GET request with an authorization header, while Facebook requires query parameters in the URL. This approach keeps the code organized and easy to extend: if we add a new provider to the OAuthProvider type, TypeScript will prompt us to handle it in the match function, helping prevent overlooked cases and making future updates straightforward.

import { match } from "@lib/utils/match"
import { addQueryParams } from "@lib/utils/query/addQueryParams"
import { OAuthProvider } from "@product/entities/OAuthProvider"

import { queryOAuthProvider } from "./queryOAuthProvider"

interface GetOAuthUserInfoParams {
  accessToken: string
  provider: OAuthProvider
}

interface UserInfoResponse {
  email?: string
  name?: string
}

const GOOGLE_USER_INFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo"
const FACEBOOK_USER_INFO_URL = "https://graph.facebook.com/me"

export const getOAuthUserInfo = async ({
  accessToken,
  provider,
}: GetOAuthUserInfoParams) => {
  const actionName = `get ${provider} user info`

  return match(provider, {
    google: async () =>
      queryOAuthProvider<UserInfoResponse>(actionName, GOOGLE_USER_INFO_URL, {
        method: "GET",
        headers: {
          Authorization: `Bearer ${accessToken}`,
        },
      }),
    facebook: async () =>
      queryOAuthProvider<UserInfoResponse>(
        actionName,
        addQueryParams(FACEBOOK_USER_INFO_URL, {
          fields: ["email", "name"].join(","),
          access_token: accessToken,
        }),
      ),
  })
}

The Core Implementation

At the heart of this approach is a simple yet powerful match function. This utility takes a value—such as a string, number, or symbol—and a set of handlers for each possible value. It then calls the handler that matches the input, returning its result. By using this function, we can replace verbose conditional logic with a concise, type-safe pattern that's easy to read and extend.

export function match<T extends string | number | symbol, V>(
  value: T,
  handlers: { [key in T]: () => V },
): V {
  const handler = handlers[value]

  return handler()
}

Bringing Pattern Matching to React

While the match function works well for plain TypeScript logic, it's also possible to bring this pattern matching approach into React components. The Match component provides a way to render different UI fragments based on a value, using a prop-driven pattern that closely mirrors the type-safe logic of the utility function. By mapping each possible value to a render function, Match makes it straightforward to conditionally display content in a declarative and maintainable way.

import { ReactNode } from "react"

import { ValueProp } from "../props"

type MatchProps<T extends string | number | symbol> = Record<
  T,
  () => ReactNode
> &
  ValueProp<T>

export function Match<T extends string | number | symbol>(
  props: MatchProps<T>,
) {
  const render = props[props.value]

  return <>{render()}</>
}

Visual State Indicators with Pattern Matching

For instance, let's say we need to display a different visual indicator depending on the current status of a task: a checkbox when it's completed, a spinner while it's active, and an empty placeholder when it's still pending. This approach makes it easy to see at a glance what stage each task is in, using clear and distinct UI elements for each possible state.

import styled from "styled-components"

import { Match } from "../../base/Match"
import { centerContent } from "../../css/centerContent"
import { sameDimensions } from "../../css/sameDimensions"
import { HStack } from "../../css/stack"
import { CheckIcon } from "../../icons/CheckIcon"
import { Spinner } from "../../loaders/Spinner"
import { ChildrenProp, KindProp } from "../../props"
import { Text, TextColor } from "../../text"
import { getColor } from "../../theme/getters"

export type ProgressListItemKind = "completed" | "active" | "pending"

const IndicatorContainer = styled.div`
  ${sameDimensions(24)}
  ${centerContent}
`

const CompletedIndicator = styled(CheckIcon)`
  color: ${getColor("success")};
`

const ActiveIndicator = styled(Spinner)`
  color: ${getColor("contrast")};
`

const kindToColor: Record<ProgressListItemKind, TextColor> = {
  completed: "regular",
  active: "contrast",
  pending: "shy",
}

export const ProgressListItem = ({
  kind,
  children,
}: KindProp<ProgressListItemKind> & ChildrenProp) => {
  return (
    <HStack gap={12} alignItems="center">
      <IndicatorContainer>
        <Match
          value={kind}
          completed={() => <CompletedIndicator />}
          active={() => <ActiveIndicator />}
          pending={() => <div />}
        />
      </IndicatorContainer>
      <Text color={kindToColor[kind]}>{children}</Text>
    </HStack>
  )
}

Managing Query States with Pattern Matching

We can also create a custom pattern matching component tailored for handling the results of queries or mutations—something I often need when working with react-query. Typically, a query result might be pending, successful, or in an error state, and sometimes there's an inactive state, such as when a query is disabled based on certain conditions. The MatchQuery component lets you define handlers for each of these cases, allowing you to specify only the ones relevant to your situation and keep your UI logic clean and focused.

import { ValueProp } from "@lib/utils/entities/props"
import { ReactNode } from "react"

import { Query } from "../Query"

export type MatchQueryProps<T, E = unknown> = ValueProp<Query<T, E>> & {
  error?: (error: E) => ReactNode
  pending?: () => ReactNode
  success?: (data: T) => ReactNode
  inactive?: () => ReactNode
}

export function MatchQuery<T, E = unknown>({
  value,
  error = () => null,
  pending = () => null,
  success = () => null,
  inactive = () => null,
}: MatchQueryProps<T, E>) {
  if (value.data !== undefined) {
    return <>{success(value.data)}</>
  }

  if (value.error) {
    return <>{error(value.error)}</>
  }

  if (value.isLoading === false) {
    return <>{inactive()}</>
  }

  if (value.isPending) {
    return <>{pending()}</>
  }

  return null
}

MatchQuery in Action

Here's how MatchQuery helps manage different query states in the UI: it renders the scoreboard when the data is available, shows a spinner while the query is loading, and displays an error message if something goes wrong. This approach keeps the component focused and makes each state easy to handle and understand.

import { Panel } from "@lib/ui/css/panel"
import { HStack, VStack } from "@lib/ui/css/stack"
import { Spinner } from "@lib/ui/loaders/Spinner"
import { MatchQuery } from "@lib/ui/query/components/MatchQuery"
import { Text } from "@lib/ui/text"
import { SectionTitle } from "@lib/ui/text/SectionTitle"
import { useApiQuery } from "@product/api-ui/hooks/useApiQuery"
import {
  ScoreboardPeriod,
  scoreboardPeriodInDays,
} from "@product/entities/PerformanceScoreboard"
import { LastScoreboardUpdate } from "@product/ui/scoreboard/LastScoreboardUpdate"
import { ScoreboardTable } from "@product/ui/scoreboard/ScoreboardTable"

export const Scoreboard = () => {
  const scoreboardPeriod: ScoreboardPeriod = "week"
  const query = useApiQuery("scoreboard", { id: scoreboardPeriod })

  return (
    <Panel kind="secondary">
      <VStack gap={24}>
        <SectionTitle>
          Last {scoreboardPeriodInDays[scoreboardPeriod]} days top performers
        </SectionTitle>
        <MatchQuery
          value={query}
          success={(value) => (
            <VStack gap={24}>
              <ScoreboardTable
                myPosition={value.myPosition}
                users={value.users}
              />
              <HStack fullWidth justifyContent="end">
                <LastScoreboardUpdate value={value.syncedAt} />
              </HStack>
            </VStack>
          )}
          error={() => <Text>Something went wrong</Text>}
          pending={() => <Spinner />}
        />
      </VStack>
    </Panel>
  )
}

Pattern Matching with Record Unions

A more interesting use case for pattern matching arises when we work with more complex data structures, such as a record union. For example, consider a Shape type that can represent a circle, rectangle, or triangle. In this context, a record union refers to an object with a single key that uniquely identifies each variant.

type Shape =
  | { circle: { radius: number } }
  | { rectangle: { width: number; height: number } }
  | { triangle: { base: number; height: number } }

To work with record unions—where each variant is a unique key—you can use a utility like matchRecordUnion to dispatch logic based on that key. This avoids manual type checks or nested conditionals, and ensures each handler receives a strongly typed argument for its variant. As a result, your code stays concise, type-safe, and easy to extend.

const getArea = (shape: Shape): number =>
  matchRecordUnion(shape, {
    circle: ({ radius }) => Math.PI * radius * radius,
    rectangle: ({ width, height }) => width * height,
    triangle: ({ base, height }) => 0.5 * base * height,
  })

The Implementation of matchRecordUnion

The implementation of matchRecordUnion requires some TypeScript type gymnastics to properly infer and extract the types involved. It uses conditional types to first determine the keys of the union type, then extract the value associated with a specific key. At runtime, the function first extracts the key from the object, and then calls the appropriate handler with the value associated with that key.

type KeyOfUnion<U> = U extends any ? keyof U : never
type ValueForKey<U, K extends string | number | symbol> =
  U extends Record<K, infer V> ? V : never

export function matchRecordUnion<U, R>(
  value: U,
  handlers: { [K in KeyOfUnion<U>]: (val: ValueForKey<U, K>) => R },
): R {
  const key = Object.keys(value as any)[0] as KeyOfUnion<U>
  return handlers[key]((value as any)[key])
}

Record Union Pattern Matching in React

Just as we transformed the match function into a React component earlier, we can similarly convert matchRecordUnion into a component-based version.

import React from "react"

type KeyOfUnion<U> = U extends any ? keyof U : never
type ValueForKey<U, K extends string | number | symbol> =
  U extends Record<K, infer V> ? V : never

export type MatchRecordUnionProps<U> = {
  value: U
  handlers: {
    [K in KeyOfUnion<U>]: (payload: ValueForKey<U, K>) => React.ReactNode
  }
}

export function MatchRecordUnion<U>({
  value,
  handlers,
}: MatchRecordUnionProps<U>) {
  const key = Object.keys(value as any)[0] as KeyOfUnion<U>
  const content = handlers[key]((value as any)[key])
  return <>{content}</>
}

Advanced Pattern Matching for Different Union Structures

The match and matchRecordUnion utilities, combined with the resolvers pattern discussed earlier, address most real-world pattern matching scenarios in TypeScript. While these patterns handle the majority of use cases, you can adapt them for other type structures when needed. For instance, my toolkit also includes matchDiscriminatedUnion, which I reserve for working with external APIs that provide unions structured as { case: 'foo', value: { ... } } | { case: 'bar', value: { ... } } — where a discriminant field identifies the type and a separate field holds the actual data. Despite having this option available, I typically favor record unions for their more compact representation.

type PropertyKey = string | number | symbol

type DiscriminantValues<U, D extends PropertyKey> =
  U extends Record<D, infer X> ? X : never

type PayloadForCase<
  U,
  D extends PropertyKey,
  V extends PropertyKey,
  K extends PropertyKey,
> = U extends { [p in D]: K } & Record<V, infer R> ? R : never

type HandlerMap<U, D extends PropertyKey, V extends PropertyKey, R> = {
  [K in DiscriminantValues<U, D> & PropertyKey]: (
    payload: PayloadForCase<U, D, V, K>,
  ) => R
}

export function matchDiscriminatedUnion<
  U extends Record<D, any> & Record<V, any>,
  R,
  D extends PropertyKey = PropertyKey,
  V extends PropertyKey = PropertyKey,
>(
  value: U,
  discriminantKey: D,
  valueKey: V,
  handlers: HandlerMap<U, D, V, R>,
): R {
  const key = value[discriminantKey] as DiscriminantValues<U, D> & PropertyKey
  const narrowed = value as Extract<U, { [p in D]: typeof key }>
  return handlers[key](narrowed[valueKey])
}

Type Predicates for Safe Pattern Matching

Let me introduce a small but useful utility function that complements our pattern matching approach. When working with pattern matching, we often need to verify if a string value is one of the possible values in a union type before proceeding with the match operation.

export function isOneOf<T>(item: unknown, items: readonly T[]): item is T {
  return items.includes(item as T)
}

Type-Safe Pattern Matching with External Data

This example demonstrates why isOneOf is essential for type-safe pattern matching with external data. The function returns a boolean indicating if the item exists in the array, but crucially, the item is T return type is a TypeScript type predicate that narrows the type when used in conditionals. In our email provider example, once isOneOf confirms the extracted provider is valid, TypeScript treats it as a member of our const array, ensuring the subsequent match call only receives values it can properly handle and preventing compiler errors from unhandled cases.

import { isOneOf } from "./array/isOneOf"
import { extractEmailProvider } from "./extractEmailProvider"
import { match } from "./match"

const emailProvidersWithClient = [
  "gmail",
  "outlook",
  "hotmail",
  "live",
  "yahoo",
  "protonmail",
  "aol",
  "zoho",
] as const

const outlookInboxLink = "https://outlook.live.com/mail/0/inbox"

export const suggestInboxLink = (
  email: string,
  sender?: string,
): string | undefined => {
  const emailProvider = extractEmailProvider(email)
  if (!emailProvider) return undefined

  if (!isOneOf(emailProvider, emailProvidersWithClient)) return undefined

  return match(emailProvider, {
    gmail: () => {
      const url = "https://mail.google.com/mail/u/0/#search"
      if (!sender) return url

      const searchStr = encodeURIComponent(`from:@${sender}+in:anywhere`)
      return [url, searchStr].join("/")
    },
    outlook: () => outlookInboxLink,
    hotmail: () => outlookInboxLink,
    live: () => outlookInboxLink,
    yahoo: () => "https://mail.yahoo.com/d/folders/1",
    protonmail: () => "https://mail.protonmail.com/u/0/inbox",
    aol: () => "https://mail.aol.com/webmail-std/en-us/inbox",
    zoho: () => "https://mail.zoho.com/zm/#mail/folder/inbox",
  })
}

Conclusion

Pattern matching in TypeScript transforms conditional logic from verbose switch statements into concise, type-safe patterns that catch errors at compile time and scale beautifully as your codebase grows. By embracing these techniques in your projects, you'll write more maintainable code with better type safety while making it easier to handle complex data structures and UI states.

From Theory to Fretboard: Dynamic Guitar Scale Patterns

Radzion Chachura — Sun, 15 Jun 2025 03:25:03 +0000

🐙 GitHub | 🎮 Demo

Introduction

Welcome to Part 8 of our guitar theory app series! Today, we'll expand our scales functionality by implementing five essential patterns that make learning complete major and minor scales more intuitive. These patterns provide a systematic approach to mastering scales across the fretboard. Check out the complete source code in the GitHub repository.

Implementing Relative Scale Relationships

Instead of memorizing separate patterns for major and minor scales, we can leverage their relative relationship—a concept elegantly implemented in our code through the getFullScaleRelativeTonalityRootNote function. This function calculates that relative scales share identical note patterns but with roots positioned three semitones apart; for instance, C major and A minor contain the same notes, with A being three semitones below C. Our implementation uses pattern matching to determine the direction of this three-semitone shift (upward when converting from minor to major, downward when moving from major to minor) and applies modulo arithmetic to ensure the resulting root note stays within our chromatic range, making scale navigation more efficient for guitarists learning to traverse the fretboard.

import { match } from "@lib/utils/match"

import { chromaticNotesNumber } from "../../note"
import { Scale } from "../Scale"

const semitones = 3

export const getFullScaleRelativeTonalityRootNote = ({
  tonality,
  rootNote,
}: Omit<Scale, "type">): number => {
  const direction = match(tonality, {
    minor: () => 1,
    major: () => -1,
  })

  return (
    (rootNote + semitones * direction + chromaticNotesNumber) %
    chromaticNotesNumber
  )
}

Building the UI for Scale Relationship Navigation

To display this relative relationship in our interface, we've implemented a RelativeScaleSubtitle component that accepts a relativeRootNote prop. This component renders a clickable link that seamlessly navigates users to the corresponding relative scale. While we also utilize this component with pentatonic scales, the underlying calculation for determining the relative root note differs in that context. For those interested in exploring how pentatonic patterns work, check out our detailed explanation in this post.

import { UnstyledButton } from "@lib/ui/buttons/UnstyledButton"
import { getColor } from "@lib/ui/theme/getters"
import { getPairComplement } from "@lib/utils/pair/getPairComplement"
import { getScaleName } from "@product/core/scale/getScaleName"
import { tonalities } from "@product/core/tonality"
import styled from "styled-components"

import { useChangeScale, useScale } from "./state/scale"

const Button = styled(UnstyledButton)`
  &:hover {
    color: ${getColor("textPrimary")};
  }
`

export const RelativeScaleSubtitle = ({
  relativeRootNote,
}: {
  relativeRootNote: number
}) => {
  const scale = useScale()

  const changeScale = useChangeScale()

  const relativeTonality = getPairComplement(tonalities, scale.tonality)
  const relativeScale = {
    ...scale,
    rootNote: relativeRootNote,
    tonality: relativeTonality,
  }

  return (
    <Button onClick={() => changeScale(relativeScale)}>
      (same notes as in {getScaleName(relativeScale)})
    </Button>
  )
}

Defining the Scale Type System

To represent scales in our app, we use a Scale type with three key properties: a type (either full, pentatonic, or blues), a tonality (major or minor), and a root note (an integer from 0 to 11 representing positions in the chromatic scale).

export const tonalities = ["major", "minor"] as const
export type Tonality = (typeof tonalities)[number]

export const scaleTypes = ["full", "pentatonic", "blues"] as const
export type ScaleType = (typeof scaleTypes)[number]

export type Scale = {
  type: ScaleType
  tonality: Tonality
  rootNote: number
}

Implementing Scale Navigation

When a user selects a different scale, our app redirects them to a dedicated page for that selection. For those interested in exploring how scales are visualized on the fretboard, check out the first post in this series here.

import { getValueProviderSetup } from "@lib/ui/state/getValueProviderSetup"
import { toUriNote } from "@product/core/note/uriNote"
import { Scale } from "@product/core/scale/Scale"
import { useRouter } from "next/router"
import { useCallback } from "react"

export const makeScalePath = ({ type, tonality, rootNote }: Scale) =>
  `/scale/${toUriNote(rootNote)}/${type}/${tonality}`

export const { useValue: useScale, provider: ScaleProvider } =
  getValueProviderSetup<Scale>("Scale")

export const useChangeScale = () => {
  const value = useScale()

  const { push } = useRouter()

  return useCallback(
    (params: Partial<Scale>) => {
      push(makeScalePath({ ...value, ...params }))
    },
    [push, value],
  )
}

Creating the Scale Patterns UI Component

Now let's examine the UI implementation that displays these patterns. Our ScalePatterns component creates a visual representation of the five pattern system, allowing guitarists to see how each pattern connects across the fretboard. The component dynamically generates patterns based on the currently selected scale using the getScalePattern function, which calculates note positions for each pattern index.

import { VStack } from "@lib/ui/css/stack"
import { Text } from "@lib/ui/text"
import { range } from "@lib/utils/array/range"
import { getScaleName } from "@product/core/scale/getScaleName"
import { getScalePattern } from "@product/core/scale/getScalePattern"
import { scalePatternsNumber } from "@product/core/scale/ScaleType"
import { useMemo } from "react"

import { useScale } from "../state/scale"

import { ScalePattern } from "./ScalePattern"

export const ScalePatterns = () => {
  const scale = useScale()

  const scaleName = getScaleName(scale)

  const patterns = useMemo(() => {
    return range(scalePatternsNumber).map((index) =>
      getScalePattern({ index, scale }),
    )
  }, [scale])

  return (
    <VStack gap={60}>
      <VStack gap={8}>
        <Text
          centerHorizontally
          weight={800}
          size={32}
          color="contrast"
          as="h2"
        >
          {scaleName} Patterns
        </Text>
        <Text
          centerHorizontally
          weight={700}
          size={20}
          color="supporting"
          as="h4"
        >
          {scalePatternsNumber} Essential Shapes for Guitar Solos
        </Text>
      </VStack>
      {patterns.map((pattern, index) => (
        <ScalePattern key={index} value={pattern} index={index} />
      ))}
    </VStack>
  )
}

Pattern Resolution System

Each scale has its own logic for calculating patterns. The getScalePattern function serves as a resolver that selects the appropriate calculation function based on scale type and applies it with the necessary parameters.

import { Scale } from "../Scale"
import { ScaleType } from "../ScaleType"

import { getBluesScalePattern } from "./blues"
import { getFullScalePattern } from "./full"
import { getPentatonicPattern } from "./pentatonic"
import { ScalePatternResolver } from "./ScalePatternResolver"

const resolvers: Record<ScaleType, ScalePatternResolver> = {
  blues: getBluesScalePattern,
  full: getFullScalePattern,
  pentatonic: getPentatonicPattern,
}

type RootScalePatternResolverInput = {
  index: number
  scale: Scale
}

export const getScalePattern = (input: RootScalePatternResolverInput) => {
  const resolver = resolvers[input.scale.type]

  return resolver(input)
}

Designing the Pattern Resolver Interface

Each pattern resolver function follows a consistent interface: it accepts both a scale object (with the type property omitted since it's determined by the resolver) and a pattern index as inputs. The function processes these parameters and returns an array of NotePosition objects that precisely map where notes should appear on the fretboard for that specific pattern.

import { NotePosition } from "../../note/NotePosition"
import { Scale } from "../Scale"

type ScalePatternResolverInput = {
  index: number
  scale: Omit<Scale, "type">
}

export type ScalePatternResolver = (
  input: ScalePatternResolverInput,
) => NotePosition[]

Representing Note Positions

To represent the precise location of notes on the guitar fretboard, we define a NotePosition type with two key properties: a zero-based string index and a fret number. The fret value uses a specific convention where -1 indicates an open string (no finger pressed), 0 represents the first fret, and so on.

export type NotePosition = {
  // 0-based index of the string
  string: number
  // -1 if the note is open
  // 0 if the note is on the 1st fret
  fret: number
}

Implementing the CAGED System for Scale Patterns

Our scale patterns are built on the CAGED chord system framework, with each pattern anchored to a specific chord shape—the first pattern corresponds to the E form as defined by firstMajorScalePatternChord. While some note positions use fret index -2 (not physically playable in open positions), we shift these patterns up to the 12th fret area when needed for practical playability. This approach maintains the spatial relationship between patterns according to the CAGED sequence, allowing guitarists to smoothly connect all positions across the fretboard. For a deeper understanding of the CAGED system that underpins these patterns, check out our detailed explanation in this post.

import { CagedChord } from "../../chords/caged"
import { NotePosition } from "../../note/NotePosition"

export const majorScalePatterns: NotePosition[][] = [
  [
    { string: 0, fret: 1 },
    { string: 0, fret: -1 },
    { string: 0, fret: -2 },

    { string: 1, fret: 1 },
    { string: 1, fret: -1 },

    { string: 2, fret: 1 },
    { string: 2, fret: 0 },
    { string: 2, fret: -2 },

    { string: 3, fret: 1 },
    { string: 3, fret: 0 },
    { string: 3, fret: -2 },

    { string: 4, fret: 1 },
    { string: 4, fret: -1 },
    { string: 4, fret: -2 },

    { string: 5, fret: 1 },
    { string: 5, fret: -1 },
    { string: 5, fret: -2 },
  ],
  [
    { string: 0, fret: 2 },
    { string: 0, fret: 1 },
    { string: 0, fret: -1 },

    { string: 1, fret: 2 },
    { string: 1, fret: 1 },
    { string: 1, fret: -1 },

    { string: 2, fret: 1 },
    { string: 2, fret: -1 },
    { string: 2, fret: -2 },

    { string: 3, fret: 1 },
    { string: 3, fret: -1 },
    { string: 3, fret: -2 },

    { string: 4, fret: 1 },
    { string: 4, fret: -1 },

    { string: 5, fret: 2 },
    { string: 5, fret: 1 },
    { string: 5, fret: -1 },
  ],
  [
    { string: 0, fret: 2 },
    { string: 0, fret: 0 },
    { string: 0, fret: -1 },

    { string: 1, fret: 2 },
    { string: 1, fret: 0 },
    { string: 1, fret: -1 },

    { string: 2, fret: 1 },
    { string: 2, fret: -1 },

    { string: 3, fret: 2 },
    { string: 3, fret: 1 },
    { string: 3, fret: -1 },

    { string: 4, fret: 2 },
    { string: 4, fret: 1 },
    { string: 4, fret: -1 },

    { string: 5, fret: 2 },
    { string: 5, fret: 0 },
    { string: 5, fret: -1 },
  ],
  [
    { string: 0, fret: -1 },
    { string: 0, fret: 1 },

    { string: 1, fret: 1 },
    { string: 1, fret: 2 },
    { string: 1, fret: -1 },

    { string: 2, fret: 1 },
    { string: 2, fret: 0 },
    { string: 2, fret: -2 },

    { string: 3, fret: 1 },
    { string: 3, fret: -1 },
    { string: 3, fret: -2 },

    { string: 4, fret: 1 },
    { string: 4, fret: -1 },
    { string: 4, fret: -2 },

    { string: 5, fret: 1 },
    { string: 5, fret: -1 },
  ],
  [
    { string: 0, fret: 2 },
    { string: 0, fret: 1 },
    { string: 0, fret: -1 },

    { string: 1, fret: 2 },
    { string: 1, fret: 0 },
    { string: 1, fret: -1 },

    { string: 2, fret: 1 },
    { string: 2, fret: -1 },
    { string: 2, fret: -2 },

    { string: 3, fret: 1 },
    { string: 3, fret: -1 },

    { string: 4, fret: 2 },
    { string: 4, fret: 1 },
    { string: 4, fret: -1 },

    { string: 5, fret: 2 },
    { string: 5, fret: 1 },
    { string: 5, fret: -1 },
  ],
]

export const firstMajorScalePatternChord: CagedChord = "e"

Normalizing Note Positions for Playability

To implement this automatic octave shifting, our normalizeFretPositions utility detects patterns with fret values below -1 and transposes all notes up by exactly one octave (12 frets), preserving their relative relationships while making them physically playable on the guitar.

import { NotePosition } from "./NotePosition"
import { shiftNotePositions } from "./shiftNotePositions"

import { chromaticNotesNumber } from "."

export const normalizeFretPositions = (
  positions: NotePosition[],
): NotePosition[] => {
  if (positions.some((position) => position.fret < -1)) {
    return shiftNotePositions(positions, chromaticNotesNumber)
  }

  return positions
}

Shifting Scale Patterns Across the Fretboard

For repositioning scale patterns across the fretboard, we implement the shiftNotePositions function, which transposes all notes in a pattern by a specified fret offset.

import { NotePosition } from "./NotePosition"

export const shiftNotePositions = (
  positions: NotePosition[],
  offset: number,
) => {
  return positions.map((position) => ({
    ...position,
    fret: position.fret + offset,
  }))
}

Calculating Scale Patterns Dynamically

The getFullScalePattern function handles positioning scale patterns on the fretboard with a straightforward approach. For minor scales, it uses the relative tonality system to convert them to their equivalent major patterns. With major scales, it retrieves the base pattern, rotates the CAGED system distances to maintain proper spacing, and calculates an offset based on the root note, standard tuning, and distance from the first pattern. After shifting the notes by this offset, it ensures all positions are playable through normalization. This method creates a system where the five patterns connect naturally across the fretboard.

import { getLastItem } from "@lib/utils/array/getLastItem"
import { rotateArray } from "@lib/utils/array/rotateArray"
import { sum } from "@lib/utils/array/sum"
import { normalizeFretPositions } from "@product/core/note/normalizeFretPositions"

import { cagedChords, cagedTemplateDistances } from "../../chords/caged"
import { standardTuning } from "../../guitar/tuning"
import { shiftNotePositions } from "../../note/shiftNotePositions"
import { getFullScaleRelativeTonalityRootNote } from "../full/getFullScaleRelativeTonalityRootNote"
import {
  firstMajorScalePatternChord,
  majorScalePatterns,
} from "../full/majorScalePatterns"

import { ScalePatternResolver } from "./ScalePatternResolver"

export const getFullScalePattern: ScalePatternResolver = (input) => {
  if (input.scale.tonality === "minor") {
    return getFullScalePattern({
      ...input,
      scale: {
        ...input.scale,
        tonality: "major",
        rootNote: getFullScaleRelativeTonalityRootNote(input.scale),
      },
    })
  }
  const pattern = majorScalePatterns[input.index]

  const distances = rotateArray(
    cagedTemplateDistances.major,
    cagedChords.indexOf(firstMajorScalePatternChord),
  )

  const offset =
    input.scale.rootNote -
    getLastItem(standardTuning) +
    sum(distances.slice(0, input.index))

  const positionedPattern = shiftNotePositions(pattern, offset)

  return normalizeFretPositions(positionedPattern)
}

Visualizing Scale Patterns on the Fretboard

The ScalePattern component visualizes fretboard patterns by rendering note positions calculated by the getScalePattern function, leveraging the core fretboard visualization components introduced in the first post of this series to create an interactive representation of each scale shape.

import { VStack } from "@lib/ui/css/stack"
import { IndexProp, ValueProp } from "@lib/ui/props"
import { NotePosition } from "@product/core/note/NotePosition"
import { getScaleName } from "@product/core/scale/getScaleName"

import { Fretboard } from "../../guitar/fretboard/Fretboard"
import { SectionTitle } from "../../ui/SectionTitle"
import { ScaleNote } from "../ScaleNote"
import { useScale } from "../state/scale"

export const ScalePattern = ({
  value,
  index,
}: ValueProp<NotePosition[]> & IndexProp) => {
  const scale = useScale()

  const scaleName = getScaleName(scale)

  const title = `${scaleName} Pattern #${index + 1}`

  return (
    <VStack gap={40}>
      <SectionTitle>{title}</SectionTitle>
      <Fretboard>
        {value.map((position) => {
          return (
            <ScaleNote
              key={`${position.string}-${position.fret}`}
              {...position}
            />
          )
        })}
      </Fretboard>
    </VStack>
  )
}

Conclusion

By implementing these five interconnected scale patterns based on the CAGED system, our app provides guitarists with a systematic approach to mastering scales across the entire fretboard, transforming what was once a daunting memorization task into an intuitive learning journey.

Building a Custom Cryptocurrency Candlestick Chart from Scratch with React

Radzion Chachura — Sat, 07 Jun 2025 04:11:13 +0000

🐙 GitHub | 🎮 Demo

Introduction

In this tutorial, we'll create a custom real-time candlestick chart for tracking cryptocurrency prices from scratch, without relying on external charting libraries. Follow along step-by-step or explore the complete implementation in the GitHub repository.

Building the Demo Component

To demonstrate our solution, we'll create a CandlestickDemo component that fetches the last 24 weeks of BTC price data and renders it as a candlestick chart upon successful loading.

import { useAssetPriceCandlesQuery } from "@lib/chain-ui/queries/useAssetPriceCandlesQuery"
import { MatchQuery } from "@lib/ui/query/components/MatchQuery"
import { Text } from "@lib/ui/text"
import { getErrorMessage } from "@lib/utils/getErrorMessage"

import { CandlestickChart } from "./chart/CandlestickChart"

export const CandlestickDemo = () => {
  const query = useAssetPriceCandlesQuery({
    id: "BTC",
    limit: 24,
    candleDuration: { value: 1, unit: "w" },
  })

  return (
    <MatchQuery
      value={query}
      success={(value) => <CandlestickChart value={value} />}
      error={(error) => (
        <Text>Failed to fetch data: {getErrorMessage(error)}</Text>
      )}
      pending={() => <Text>Loading...</Text>}
    />
  )
}

Setting Up Data Fetching

The useAssetPriceCandlesQuery hook functions as a React Query wrapper for the price data fetching function. It accepts the same input parameters and leverages react-query to handle caching, loading states, and error management automatically.

import { useQuery } from "@tanstack/react-query"

import { getAssetPriceCandles } from "../../chain/trading/getAssetPriceCandles"
import { GetAssetPriceCandlesInput } from "../../chain/trading/getAssetPriceCandles"

export const useAssetPriceCandlesQuery = (input: GetAssetPriceCandlesInput) => {
  return useQuery({
    queryKey: ["asset-price-candles", input],
    queryFn: () => getAssetPriceCandles(input),
  })
}

Defining the Data Structure

Before implementing the chart, we need to define our price candle data structure. We'll create a constant array of price fields that will allow us to iterate over them efficiently when rendering chart elements or displaying price information.

import { Milliseconds } from "@lib/utils/time/types"

export const priceCandlePriceFields = ["open", "high", "low", "close"] as const
export type PriceCandlePriceField = (typeof priceCandlePriceFields)[number]
export type PriceCandlePriceFields = Record<PriceCandlePriceField, number>

export type PriceCandle = PriceCandlePriceFields & {
  startTime: Milliseconds
}

Implementing API Integration

Let's implement the core functionality for fetching cryptocurrency price data from the Binance API. Our getAssetPriceCandles function converts input parameters into the format Binance expects, manages the HTTP request, and transforms the raw kline data into structured candle objects. We use TypeScript's discriminated unions to ensure type safety throughout this process, especially with the CandleDuration type that restricts time intervals to only those supported by Binance's API.

import { PriceCandle } from "@lib/trading/PriceCandle"
import { order } from "@lib/utils/array/order"
import { addQueryParams } from "@lib/utils/query/addQueryParams"
import { queryUrl } from "@lib/utils/query/queryUrl"
import { withoutUndefinedFields } from "@lib/utils/record/withoutUndefinedFields"

const binanceUnitMap = {
  min: "m",
  h: "h",
  d: "d",
  w: "w",
}

export type CandleDuration =
  | { value: 1; unit: "min" }
  | { value: 3; unit: "min" }
  | { value: 5; unit: "min" }
  | { value: 15; unit: "min" }
  | { value: 30; unit: "min" }
  | { value: 1; unit: "h" }
  | { value: 2; unit: "h" }
  | { value: 4; unit: "h" }
  | { value: 6; unit: "h" }
  | { value: 8; unit: "h" }
  | { value: 12; unit: "h" }
  | { value: 1; unit: "d" }
  | { value: 3; unit: "d" }
  | { value: 1; unit: "w" }

const toBinanceInterval = (duration: CandleDuration): string => {
  const apiUnit = binanceUnitMap[duration.unit]
  if (!apiUnit) {
    throw new Error(`Unsupported duration unit: ${duration.unit}`)
  }

  return `${duration.value}${apiUnit}`
}

export type GetAssetPriceCandlesInput = {
  id: string
  startTime?: number
  endTime?: number
  candleDuration: CandleDuration
  limit?: number
}

type KlineData = [
  number, // Open time
  string, // Open price
  string, // High price
  string, // Low price
  string, // Close price
  string, // Volume
  number, // Close time
  string, // Quote asset volume
  number, // Number of trades
  string, // Taker buy base asset volume
  string, // Taker buy quote asset volume
  string, // Ignore
]

const baseUrl = "https://api.binance.com/api/v3/klines"

export const maxLimit = 1000

export const getAssetPriceCandles = async ({
  id,
  startTime,
  endTime,
  candleDuration,
  limit = maxLimit,
}: GetAssetPriceCandlesInput): Promise<PriceCandle[]> => {
  const symbol = `${id.toUpperCase()}USDT`

  const url = addQueryParams(
    baseUrl,
    withoutUndefinedFields({
      symbol,
      interval: toBinanceInterval(candleDuration),
      startTime,
      endTime,
      limit,
    }),
  )

  const klines = await queryUrl<KlineData[]>(url.toString())

  return order(
    klines.map((kline) => ({
      startTime: kline[0],
      open: parseFloat(kline[1]),
      high: parseFloat(kline[2]),
      low: parseFloat(kline[3]),
      close: parseFloat(kline[4]),
    })),
    (o) => o.startTime,
    "asc",
  )
}

Creating Chart Components

With our data pipeline established, we're ready to implement the chart's visual components. The chart consists of several key elements: X and Y axes with appropriate labels, candlestick representations of price movements, and an interactive hover tracker that highlights individual candles while displaying their detailed price information.

import { PriceCandle, priceCandlePriceFields } from "@lib/trading/PriceCandle"
import { ElementSizeAware } from "@lib/ui/base/ElementSizeAware"
import { HoverTracker } from "@lib/ui/base/HoverTracker"
import { ChartHorizontalGridLines } from "@lib/ui/charts/ChartHorizontalGridLines"
import { ChartLabel } from "@lib/ui/charts/ChartLabel"
import { ChartSlice } from "@lib/ui/charts/ChartSlice"
import { ChartXAxis } from "@lib/ui/charts/ChartXAxis"
import { ChartYAxis } from "@lib/ui/charts/ChartYAxis"
import { generateYLabels } from "@lib/ui/charts/utils/generateYLabels"
import { VStack } from "@lib/ui/css/stack"
import { TakeWholeSpaceAbsolutely } from "@lib/ui/css/takeWholeSpaceAbsolutely"
import { UniformColumnGrid } from "@lib/ui/css/uniformColumnGrid"
import { BodyPortal } from "@lib/ui/dom/BodyPortal"
import { ValueProp } from "@lib/utils/entities/props"
import { getSegmentIndex } from "@lib/utils/math/getSegmentIndex"
import { normalizeDataArrays } from "@lib/utils/math/normalizeDataArrays"
import { recordFromKeys } from "@lib/utils/record/recordFromKeys"
import { format } from "date-fns"
import { useMemo, useState } from "react"

import { Candlestick } from "./Candlestick"
import { CandlestickInfo } from "./CandlestickInfo"
import { chartConfig } from "./config"

export function CandlestickChart({ value }: ValueProp<PriceCandle[]>) {
  const yLabels = useMemo(() => {
    return generateYLabels({
      data: value.flatMap((candle) => [candle.low, candle.high]),
    })
  }, [value])

  const normalized = normalizeDataArrays({
    yLabels,
    ...recordFromKeys(priceCandlePriceFields, (field) =>
      value.map((candle) => candle[field]),
    ),
  })

  const [selectedIndex, setSelectedIndex] = useState<number | null>(null)

  return (
    <VStack fullWidth gap={20}>
      <ChartSlice yLabelsWidth={chartConfig.yLabelsWidth}>
        <ChartYAxis
          renderLabel={(index) => (
            <ChartLabel key={index}>${yLabels[index]}</ChartLabel>
          )}
          data={normalized.yLabels}
        />
        <VStack
          style={{
            position: "relative",
          }}
          fullWidth
        >
          <UniformColumnGrid
            gap={4}
            style={{
              height: chartConfig.chartHeight,
              position: "relative",
            }}
          >
            {value.map((_, index) => (
              <Candlestick
                key={index}
                value={recordFromKeys(
                  priceCandlePriceFields,
                  (field) => normalized[field][index],
                )}
                isActive={selectedIndex === index}
              />
            ))}
            <HoverTracker
              onChange={({ position }) => {
                setSelectedIndex(
                  position ? getSegmentIndex(value.length, position.x) : null,
                )
              }}
              render={({ props, clientPosition }) => (
                <TakeWholeSpaceAbsolutely {...props}>
                  <BodyPortal>
                    {clientPosition && selectedIndex !== null && (
                      <CandlestickInfo
                        position={clientPosition}
                        value={value[selectedIndex]}
                      />
                    )}
                  </BodyPortal>
                </TakeWholeSpaceAbsolutely>
              )}
            />
          </UniformColumnGrid>
          <ChartHorizontalGridLines data={normalized.yLabels} />
        </VStack>
      </ChartSlice>
      <ElementSizeAware
        render={({ setElement, size }) => (
          <ChartSlice yLabelsWidth={chartConfig.yLabelsWidth} ref={setElement}>
            <div />
            {size?.width !== undefined && (
              <ChartXAxis
                dataSize={value.length}
                containerWidth={size.width}
                expectedLabelHeight={chartConfig.xLabelsHeight}
                expectedLabelWidth={chartConfig.xLabelsWidth}
                labelsMinDistance={chartConfig.xLabelsMinDistance}
                renderLabel={(index) => (
                  <ChartLabel key={index}>
                    {format(value[index].startTime, "MMM yyyy")}
                  </ChartLabel>
                )}
              />
            )}
          </ChartSlice>
        )}
      />
    </VStack>
  )
}

Generating Y-Axis Labels

With our chart's structure in place, we need a system for generating meaningful Y-axis labels that work across any price range. The following algorithm intelligently determines the optimal step size between labels based on the data's range, creating visually balanced axis labels that use familiar increments (1, 2, 2.5, 5, 10) scaled to match the data's magnitude.

import { range } from "@lib/utils/array/range"

type Input = {
  data: number[]
  minLabels?: number
  maxLabels?: number
}

const PREFERRED_STEPS = [1, 2, 2.5, 5, 10] as const

const getMagnitude = (value: number): number => {
  if (value === 0) return 1
  return Math.pow(10, Math.floor(Math.log10(Math.abs(value))))
}

const getBoundaryValue = (
  value: number,
  step: number,
  roundUp: boolean,
): number => {
  return (roundUp ? Math.ceil(value / step) : Math.floor(value / step)) * step
}

const getStepSizes = (approximateStep: number): number[] => {
  const magnitude = getMagnitude(approximateStep)
  return PREFERRED_STEPS.map((step) => step * magnitude)
}

const findBestStep = (
  dataRange: number,
  stepSizes: number[],
  minLabels: number,
  maxLabels: number,
): number => {
  if (dataRange === 0) {
    return stepSizes[0]
  }

  for (const step of stepSizes) {
    const labelCount = Math.floor(dataRange / step) + 1
    if (labelCount >= minLabels && labelCount <= maxLabels) {
      return step
    }
  }
  return stepSizes[0]
}

export const generateYLabels = ({
  data,
  minLabels = 4,
  maxLabels = 6,
}: Input): number[] => {
  if (data.length === 0) {
    return []
  }

  const maxValue = Math.max(...data)
  const minValue = Math.min(...data)
  const dataRange = maxValue - minValue

  if (dataRange === 0) {
    const magnitude = getMagnitude(Math.abs(maxValue))
    const step = magnitude / 2
    const base = getBoundaryValue(maxValue, step, false)
    return range(5).map((i) => Number((base + (i - 2) * step).toFixed(2)))
  }

  const approximateStep = dataRange / (maxLabels - 1)
  const stepSizes = getStepSizes(approximateStep)
  const bestStep = findBestStep(dataRange, stepSizes, minLabels, maxLabels)

  const lowerBound = getBoundaryValue(minValue, bestStep, false)
  const upperBound = getBoundaryValue(maxValue, bestStep, true)
  const labelCount = Math.floor((upperBound - lowerBound) / bestStep) + 1

  return range(labelCount).map((i) =>
    Number((lowerBound + i * bestStep).toFixed(2)),
  )
}

Normalizing Data for Responsive Rendering

The key to rendering our chart components at any size is normalizing the data to a consistent scale. The following utility function transforms multiple arrays of numerical data to the 0-1 range, making it easy to position elements using percentage-based measurements instead of absolute pixel values. This approach provides flexibility when working with dynamic container sizes and eliminates the need for manual recalculation when the chart dimensions change.

export const normalizeDataArrays = <T extends Record<string, number[]>>(
  input: T,
): T => {
  const values = Object.values(input).flat()
  const max = Math.max(...values)
  const min = Math.min(...values)
  const range = max - min
  return Object.fromEntries(
    Object.entries(input).map(([key, value]) => [
      key,
      value.map((v) => (v - min) / range),
    ]),
  ) as T
}

Centralizing Chart Configuration

To ensure consistent sizing and spacing throughout our chart, we define a configuration object that centralizes all dimensional parameters. This approach makes it easy to fine-tune the chart's appearance and maintain proper proportions between its components without scattered magic numbers.

export const chartConfig = {
  chartHeight: 600,
  yLabelsWidth: 58,
  xLabelsHeight: 18,
  xLabelsWidth: 80,
  xLabelsMinDistance: 20,
  tailWidth: 1,
}

Creating the Chart Layout Structure

Now let's create a ChartSlice component to handle the layout structure of our chart. This component provides a two-column grid where the first column contains y-axis labels and the second contains the chart's main content area.

import { toSizeUnit } from "@lib/ui/css/toSizeUnit"
import styled from "styled-components"

type ChartSliceProps = {
  yLabelsWidth: number | string
}

export const ChartSlice = styled.div<ChartSliceProps>`
  position: relative;
  display: grid;
  grid-template-columns: ${({ yLabelsWidth }) => toSizeUnit(yLabelsWidth)} 1fr;
`

Building the Y-Axis Component

The ChartYAxis component renders the vertical axis labels at positions determined by normalized data values. By using the toPercents utility to convert normalized values (0-1) to percentage-based CSS positions, we can place labels at their proper vertical positions regardless of the chart's physical height.

import { toPercents } from "@lib/utils/toPercents"
import { ReactNode } from "react"
import styled from "styled-components"

import { PositionAbsolutelyCenterHorizontally } from "../layout/PositionAbsolutelyCenterHorizontally"
import { UiProps } from "../props"

type ChartYAxisProps = UiProps & {
  data: number[]
  renderLabel: (index: number) => ReactNode
}

const Container = styled.div`
  position: relative;
`

export const ChartYAxis = ({ data, renderLabel, ...rest }: ChartYAxisProps) => {
  return (
    <Container {...rest}>
      {data.map((value, index) => {
        return (
          <PositionAbsolutelyCenterHorizontally
            top={toPercents(1 - value)}
            key={index}
          >
            {renderLabel(index)}
          </PositionAbsolutelyCenterHorizontally>
        )
      })}
    </Container>
  )
}

Implementing Positioning Utilities

The PositionAbsolutelyCenterHorizontally component serves as a positioning utility that places elements at specific vertical positions while centering them horizontally. This approach creates a clean, responsive layout where elements maintain their relative positions when the container dimensions change.

import styled from "styled-components"

import { ChildrenProp } from "../props"

interface PositionAbsolutelyCenterHorizontallyProps extends ChildrenProp {
  top: React.CSSProperties["top"]
  fullWidth?: boolean
}

const Wrapper = styled.div`
  position: absolute;
  left: 0;
`

const Container = styled.div`
  position: relative;
  display: flex;
  align-items: center;
`

const Content = styled.div`
  position: absolute;
  left: 0;
`

export const PositionAbsolutelyCenterHorizontally = ({
  top,
  children,
  fullWidth,
}: PositionAbsolutelyCenterHorizontallyProps) => {
  const width = fullWidth ? "100%" : undefined
  return (
    <Wrapper style={{ top, width }}>
      <Container style={{ width }}>
        <Content style={{ width }}>{children}</Content>
      </Container>
    </Wrapper>
  )
}

Creating a Flexible Grid Layout

The UniformColumnGrid component provides the flexible container layout for our candlesticks, ensuring they're evenly distributed across the chart width. This responsive grid automatically adjusts column widths based on available space while maintaining consistent gaps between elements. With configurable parameters for spacing and sizing constraints, it creates the perfect foundation for visualizing time-series data where each column represents a distinct time interval.

import styled, { css } from "styled-components"

import { toSizeUnit } from "../css/toSizeUnit"

export type UniformColumnGridParams = {
  gap: number
  minChildrenWidth?: number
  maxChildrenWidth?: number
  childrenWidth?: number
  rowHeight?: number
  fullWidth?: boolean
  maxColumns?: number
}

const getColumnMax = (maxColumns: number | undefined, gap: number) => {
  if (!maxColumns) return `0px`

  const gapCount = maxColumns - 1
  const totalGapWidth = `calc(${gapCount} * ${toSizeUnit(gap)})`

  return `calc((100% - ${totalGapWidth}) / ${maxColumns})`
}

const getColumnWidth = ({
  minChildrenWidth,
  maxChildrenWidth,
  maxColumns,
  gap,
  childrenWidth,
}: UniformColumnGridParams) => {
  if (childrenWidth !== undefined) {
    return toSizeUnit(childrenWidth)
  }

  return `
    minmax(
      max(
        ${toSizeUnit(minChildrenWidth || 0)},
        ${getColumnMax(maxColumns, gap)}
      ),
      ${maxChildrenWidth ? toSizeUnit(maxChildrenWidth) : "1fr"}
  )`
}

export const uniformColumnGrid = (params: UniformColumnGridParams) => css`
  display: grid;
  grid-template-columns: repeat(auto-fit, ${getColumnWidth(params)});
  gap: ${toSizeUnit(params.gap)};
  ${params.rowHeight &&
  css`
    grid-auto-rows: ${toSizeUnit(params.rowHeight)};
  `}
  ${params.fullWidth &&
  css`
    width: 100%;
  `}
`

export const UniformColumnGrid = styled.div<UniformColumnGridParams>`
  ${uniformColumnGrid}
`

Adding Interactive Hover Tracking

The chart's interactivity relies on the HoverTracker component, which elegantly handles mouse movements to create a responsive hover experience. This component captures mouse positions, converts them to normalized coordinates within the chart, and notifies parent components when users interact with specific data points. By separating this tracking logic into a reusable component, we maintain clean separation of concerns while providing a consistent hover experience throughout the visualization.

import { useIsomorphicLayoutEffect } from "@lib/ui/hooks/useIsomorphicLayoutEffect"
import { RenderProp } from "@lib/ui/props"
import { Point } from "@lib/utils/entities/Point"
import { MouseEvent, MouseEventHandler, useCallback, useState } from "react"

import { useBoundingBox } from "../hooks/useBoundingBox"
import { useRelativePosition } from "../hooks/useRelativePosition"

interface ContainerProps {
  onMouseEnter?: MouseEventHandler<HTMLElement>
  onMouseLeave?: MouseEventHandler<HTMLElement>
  onMouseMove?: MouseEventHandler<HTMLElement>
  ref: (node: HTMLElement | null) => void
}

interface ChangeParams {
  position: Point | null
  clientPosition: Point | null
}

interface RenderParams extends ChangeParams {
  props: ContainerProps
}

interface HoverTrackerProps extends RenderProp<RenderParams> {
  onChange?: (params: ChangeParams) => void
}

export const HoverTracker = ({ render, onChange }: HoverTrackerProps) => {
  const [container, setContainer] = useState<HTMLElement | null>(null)
  const box = useBoundingBox(container)

  const [clientPosition, setClientPosition] = useState<Point | null>(null)

  const position = useRelativePosition({ box, clientPosition })

  const handleMouse = useCallback((event: MouseEvent) => {
    setClientPosition({ x: event.clientX, y: event.clientY })
  }, [])

  useIsomorphicLayoutEffect(() => {
    if (onChange) {
      onChange({ position, clientPosition })
    }
  }, [onChange, position, clientPosition])

  return (
    <>
      {render({
        props: {
          ref: setContainer,
          onMouseEnter: handleMouse,
          onMouseLeave: position
            ? () => {
                setClientPosition(null)
              }
            : undefined,
          onMouseMove: position ? handleMouse : undefined,
        },
        position: position,
        clientPosition,
      })}
    </>
  )
}

Rendering Candlestick Elements

Now that we've established the core chart structure, we need to create the Candlestick component - the visual heart of our chart. This component renders each price candle with a thin "tail" representing the full price range (high to low) and a wider "body" showing the opening and closing prices. It uses color to instantly communicate price movement: green for bullish candles (price increased) and red for bearish ones (price decreased). When hovered, an indicator line appears to help users track the selected candle.

import { PriceCandlePriceFields } from "@lib/trading/PriceCandle"
import { vStack } from "@lib/ui/css/stack"
import { toSizeUnit } from "@lib/ui/css/toSizeUnit"
import { IsActiveProp } from "@lib/ui/props"
import { getColor } from "@lib/ui/theme/getters"
import { ValueProp } from "@lib/utils/entities/props"
import { toPercents } from "@lib/utils/toPercents"
import styled, { useTheme } from "styled-components"

import { chartConfig } from "./config"

type CandlestickProps = ValueProp<PriceCandlePriceFields> & IsActiveProp

const Container = styled.div`
  position: relative;
  ${vStack({ alignItems: "center", fullHeight: true })};

  > * {
    position: absolute;
  }
`

const Tail = styled.div`
  width: ${toSizeUnit(chartConfig.tailWidth)};
`

const Body = styled.div`
  width: 100%;
`

const Indicator = styled.div`
  width: ${toSizeUnit(chartConfig.tailWidth)};
  height: 100%;
  background: ${getColor("textShy")};
`

export const Candlestick = ({ value, isActive }: CandlestickProps) => {
  const { colors } = useTheme()
  const isBullish = value.close > value.open
  const background = (isBullish ? colors.success : colors.alert).toCssValue()

  return (
    <Container>
      {isActive && <Indicator />}
      <Tail
        style={{
          background,
          height: toPercents(value.high - value.low),
          bottom: toPercents(value.low),
        }}
      />
      <Body
        style={{
          background,
          height: toPercents(Math.abs(value.close - value.open)),
          bottom: toPercents(Math.min(value.close, value.open)),
        }}
      />
    </Container>
  )
}

Building the Interactive Tooltip

To complete our interactive chart, we need to create a tooltip component that displays detailed price information when users hover over a candle. The CandlestickInfo component uses Floating UI to position itself optimally near the cursor, providing a clean, non-intrusive way to show the date and OHLC (Open, High, Low, Close) values for the selected time period.

import {
  offset,
  shift,
  flip,
  useFloating,
  autoUpdate,
} from "@floating-ui/react"
import { PriceCandle, priceCandlePriceFields } from "@lib/trading/PriceCandle"
import { FixedReference } from "@lib/ui/base/FixedReference"
import { borderRadius } from "@lib/ui/css/borderRadius"
import { HStack, vStack, VStack } from "@lib/ui/css/stack"
import { Text } from "@lib/ui/text"
import { getColor } from "@lib/ui/theme/getters"
import { Point } from "@lib/utils/entities/Point"
import { ValueProp } from "@lib/utils/entities/props"
import { formatAmount } from "@lib/utils/formatAmount"
import { format } from "date-fns"
import { useEffect } from "react"
import styled from "styled-components"

type CandlestickInfoProps = {
  position: Point
} & ValueProp<PriceCandle>

const Container = styled.div`
  border: 1px solid ${getColor("textShy")};
  background: ${getColor("foregroundExtra")};
  ${borderRadius.s};
  overflow: hidden;

  min-width: 160px;

  ${vStack({
    gap: 20,
  })}

  padding: 12px;
  background: ${getColor("foreground")};
`

export const CandlestickInfo = ({ position, value }: CandlestickInfoProps) => {
  const {
    refs: { setReference, setFloating },
    floatingStyles,
    update,
  } = useFloating({
    open: true,
    placement: "right-start",
    strategy: "fixed",
    middleware: [offset(16), flip(), shift()],
    whileElementsMounted: autoUpdate,
  })

  useEffect(() => {
    update()
  }, [position, update])

  return (
    <>
      <FixedReference
        ref={setReference}
        style={{
          left: position.x,
          top: position.y,
        }}
      />
      <Container ref={setFloating} style={{ ...floatingStyles }}>
        <Text weight="600" size={16} color="supporting">
          {format(value.startTime, "MMM d, yyyy")}
        </Text>
        <VStack gap={8}>
          {priceCandlePriceFields.map((field) => (
            <HStack alignItems="center" gap={8} key={field}>
              <Text color="supporting">{field.slice(0, 1).toUpperCase()}:</Text>
              <Text weight="600">${formatAmount(value[field])}</Text>
            </HStack>
          ))}
        </VStack>
      </Container>
    </>
  )
}

Implementing the X-Axis with Smart Label Placement

To complete our chart, we need to implement the X-axis that displays time labels. The ChartXAxis component intelligently handles label placement to prevent overlapping text, making it suitable for any chart width or data density. It calculates optimal label positions based on container dimensions, expected label sizes, and minimum spacing requirements. For time series data, this ensures readable date markers that maintain consistent spacing whether the chart shows a few days or several months of data.

import { range } from "@lib/utils/array/range"
import { withoutUndefined } from "@lib/utils/array/withoutUndefined"
import { useMemo } from "react"
import styled from "styled-components"

import { PositionAbsolutelyCenterVertically } from "../layout/PositionAbsolutelyCenterVertically"

import { JustifyPoints, positionDataPoint } from "./utils/positionDataPoints"

type ChartXAxisProps = {
  dataSize: number
  containerWidth: number
  expectedLabelHeight: number
  expectedLabelWidth: number
  labelsMinDistance?: number
  renderLabel: (index: number) => React.ReactNode
  justifyPoints?: JustifyPoints
}

const Container = styled.div`
  width: 100%;
  position: relative;
`

export const ChartXAxis = ({
  dataSize,
  containerWidth,
  expectedLabelHeight,
  expectedLabelWidth,
  labelsMinDistance = 0,
  renderLabel,
  justifyPoints = "space-between",
}: ChartXAxisProps) => {
  const itemIndexes = useMemo(() => {
    if (justifyPoints === "space-between") {
      const stepInPx = containerWidth / (dataSize - 1)
      let lastItemEnd = 0
      return withoutUndefined(
        range(dataSize).map((index) => {
          const startsAt = index * stepInPx - expectedLabelWidth / 2
          const endsAt = startsAt + expectedLabelWidth
          if (startsAt < lastItemEnd + labelsMinDistance) return

          if (endsAt > containerWidth) return

          lastItemEnd = endsAt
          return index
        }),
      )
    }

    const itemSize = containerWidth / dataSize
    const step = Math.ceil(expectedLabelWidth / itemSize)

    return range(dataSize).filter((index) => index % step === 0)
  }, [
    containerWidth,
    dataSize,
    expectedLabelWidth,
    justifyPoints,
    labelsMinDistance,
  ])

  return (
    <Container
      style={{
        minHeight: expectedLabelHeight,
      }}
    >
      {itemIndexes.map((itemIndex) => {
        const center = positionDataPoint({
          dataSize,
          containerWidth,
          index: itemIndex,
          justifyPoints,
        })

        return (
          <PositionAbsolutelyCenterVertically key={itemIndex} left={center}>
            {renderLabel(itemIndex)}
          </PositionAbsolutelyCenterVertically>
        )
      })}
    </Container>
  )
}

Conclusion

By building this chart from scratch, we've created a flexible, customizable solution that gives us complete control over every aspect of the visualization while avoiding the bloat of large charting libraries. This approach not only results in better performance but also deepens our understanding of data visualization principles and responsive UI design.

Building a CAGED System Visualizer with React: Interactive Guitar Fretboard Mapping

Radzion Chachura — Sat, 31 May 2025 10:14:46 +0000

🐙 GitHub | 🎮 Demo

Welcome to the seventh installment in our React-based guitar theory application series. In this post, we'll explore the CAGED system further by implementing a dedicated page that visualizes chord templates for each of the five foundational CAGED shapes. As always, you can explore the complete implementation in the GitHub repository.

Understanding the CAGED System

The CAGED template is a powerful system that connects five major chord forms across the fretboard, allowing you to play any major chord in multiple positions. Starting with an open chord (like C), you can systematically move up the fretboard by transitioning through each form in the sequence: C-A-G-E-D. Each transition involves replacing your ring finger with your index finger to form a barre chord, maintaining the same chord but in a different position. This creates a continuous chain of the same chord that repeats every octave, giving you complete fretboard access. For example, a C major chord can be played using all five forms, starting with the open C shape and progressing through A, G, E, and D forms, each time moving higher on the neck while still playing C major.

Managing State with TypeScript

To manage the page's state, we'll use a straightforward TypeScript interface that captures two key aspects: the visualization type and the selected chord. The view can toggle between chord and arpeggio displays, building upon the arpeggio visualization concepts we explored in our previous post. When no specific chord is selected, the page displays an overview of all five CAGED shapes in either chord or arpeggio form, providing a comprehensive view of the system.

export const cagedViews = ["chord", "arpeggio"] as const

export type CagedView = (typeof cagedViews)[number]

export const cagedChords = ["c", "a", "g", "e", "d"] as const

export type CagedChord = (typeof cagedChords)[number]

export type CagedState = {
  view: CagedView
  chord?: CagedChord
}

Implementing Dynamic Routes with NextJS

Our application uses NextJS's static site generation to create optimized, pre-rendered pages at build time. We'll implement two dynamic routes: caged/[view]/index.tsx for the overview page that displays all CAGED shapes in a comprehensive grid layout, and caged/[view]/[chord]/index.tsx for the template page that presents detailed positions for a specific chord. While we covered the overview page implementation in our previous post, this post will focus on the template page that provides an in-depth look at each CAGED shape for a specific chord.

To implement these dynamic routes in NextJS, we'll use static site generation through the getStaticPaths and getStaticProps functions. The getStaticPaths function generates all possible combinations of views (chord or arpeggio) and CAGED shapes, ensuring each combination has its own pre-rendered page. Meanwhile, getStaticProps extracts the view and chord parameters from the URL to provide the necessary state for rendering the page components. This approach optimizes performance by pre-building all possible template variations at build time rather than generating them on demand.

import { cagedViews, cagedChords } from "@product/core/chords/caged"
import { GetStaticPaths, GetStaticProps } from "next"

import { CagedPage } from "../../../../caged/CagedPage"
import { CagedTemplateState } from "../../../../caged/template/state/cagedTemplate"

export default CagedPage

export const getStaticPaths: GetStaticPaths<CagedTemplateState> = async () => {
  const paths = cagedViews.flatMap((view) =>
    cagedChords.map((chord) => ({
      params: {
        view,
        chord,
      },
    })),
  )

  return {
    paths,
    fallback: false,
  }
}

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const { view, chord } = params as CagedTemplateState

  return {
    props: {
      value: {
        view,
        chord,
      },
    },
  }
}

Creating a Centralized State Management System

To manage state across our application, we implement a centralized state management approach that leverages Next.js routing and React context. The following code establishes our core state management pattern for the CAGED system. It creates a typed provider that makes the current view and selected chord available throughout the component tree, while also providing a convenient navigation function that updates both the UI state and URL path simultaneously.

import { getValueProviderSetup } from "@lib/ui/state/getValueProviderSetup"
import { withoutUndefined } from "@lib/utils/array/withoutUndefined"
import { CagedChord, CagedView } from "@product/core/chords/caged"
import { useRouter } from "next/router"
import { useCallback } from "react"

export type CagedState = {
  view: CagedView
  chord?: CagedChord
}

export const makeCagedPath = ({ view, chord }: CagedState) =>
  `/caged/${withoutUndefined([view, chord]).join("/")}`

export const { useValue: useCaged, provider: CagedProvider } =
  getValueProviderSetup<CagedState>("Caged")

export const useChangeCaged = () => {
  const value = useCaged()
  const { push } = useRouter()

  return useCallback(
    (params: Partial<CagedState>) => {
      push(makeCagedPath({ ...value, ...params }))
    },
    [push, value],
  )
}

Type-Safe Hooks for Template Pages

For template pages where chord selection is always required, we implement a specialized hook that transforms our optional chord field into a required one. This utility leverages TypeScript's type system through the RequiredFields helper to ensure that components using this hook can safely access the chord without optional chaining. When template components use this hook, they get type-safe access to chord data with the guarantee that it will be present, simplifying their implementation by removing the need to handle the undefined case.

import { shouldBePresent } from "@lib/utils/assert/shouldBePresent"
import { RequiredFields } from "@lib/utils/types/RequiredFields"
import { useMemo } from "react"

import { CagedState, useCaged } from "../../state/caged"

export type CagedTemplateState = RequiredFields<CagedState, "chord">

export const useCagedTemplate = () => {
  const caged = useCaged()

  return useMemo(
    () => ({
      ...caged,
      chord: shouldBePresent(caged.chord),
    }),
    [caged],
  )
}

Building the Main Component

The main CagedPage component serves as a unified container for both overview and template views, conditionally rendering different content based on whether a specific chord is selected. This component leverages our state management system to provide consistent navigation between views while maintaining a clean component hierarchy. The layout consists of navigation controls at the top, followed by contextual titles, and finally the main content area that displays either the detailed template for a single chord or the overview grid of all CAGED shapes. This approach allows users to seamlessly switch between broad concept exploration and detailed chord study without disrupting the interface's overall structure or requiring separate page implementations.

import { HStack, VStack } from "@lib/ui/css/stack"
import { ValueProp } from "@lib/ui/props"
import { cagedChords } from "@product/core/chords/caged"

import { PageContainer } from "../layout/PageContainer"

import { CagedItem } from "./CagedItem"
import { CagedPageTitle } from "./CagedPageTitle"
import { ManageCagedChordPresense } from "./manage/ManageCagedChordPresense"
import { ManageCagedView } from "./manage/ManageCagedView"
import { CagedProvider, CagedState } from "./state/caged"
import { CagedTemplate } from "./template/CagedTemplate"
import { CagedTemplatePageTitle } from "./template/CagedTemplatePageTitle"
import { ManageCagedChord } from "./template/manage/ManageCagedChord"

export const CagedPage = ({ value }: ValueProp<CagedState>) => (
  <CagedProvider value={value}>
    <PageContainer>
      <VStack gap={60}>
        <VStack gap={20} alignItems="center">
          <HStack wrap="wrap" gap={20}>
            <ManageCagedView />
            <ManageCagedChordPresense />
          </HStack>
          {value.chord && <ManageCagedChord />}
        </VStack>
        {value.chord ? <CagedTemplatePageTitle /> : <CagedPageTitle />}
        {value.chord ? (
          <CagedTemplate />
        ) : (
          <HStack
            fullWidth
            gap={60}
            alignItems="center"
            justifyContent="center"
            wrap="wrap"
          >
            {cagedChords.map((chord) => (
              <CagedItem key={chord} value={chord} />
            ))}
          </HStack>
        )}
      </VStack>
    </PageContainer>
  </CagedProvider>
)

Creating Intuitive Controls

For our shape selection controls, we implement GroupedRadioInput from RadzionKit, providing an intuitive way for users to switch between the five CAGED chord shapes. This same radio-style selection pattern extends to both the ManageCagedView and ManageCagedChordPresense components.

import { GroupedRadioInput } from "@lib/ui/inputs/GroupedRadioInput"
import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"
import { cagedChords } from "@product/core/chords/caged"

import { useChangeCaged } from "../../state/caged"
import { useCagedTemplate } from "../state/cagedTemplate"

export const ManageCagedChord = () => {
  const { chord } = useCagedTemplate()
  const setValue = useChangeCaged()

  return (
    <GroupedRadioInput
      value={chord}
      onChange={(chord) => setValue({ chord })}
      options={cagedChords}
      renderOption={(chord) => `${capitalizeFirstLetter(chord)}`}
    />
  )
}

Visualizing the Cyclical Nature of CAGED

To visualize the cyclical nature of the CAGED system, our template implementation displays six fretboards rather than just the five shapes. This arrangement demonstrates how the system wraps around the neck, with the sixth position showing the same chord as the first but as a barre chord on the 12th fret. This circular representation helps guitarists understand how these shapes connect across the entire fretboard, creating a continuous pattern that repeats at the octave.

import { VStack } from "@lib/ui/css/stack"
import { range } from "@lib/utils/array/range"
import { cagedChords } from "@product/core/chords/caged"

import { CagedTemplatePart } from "./CagedTemplatePart"

export const CagedTemplate = () => {
  return (
    <VStack gap={60}>
      {range(cagedChords.length + 1).map((index) => (
        <CagedTemplatePart key={index} index={index} />
      ))}
    </VStack>
  )
}

Determining Shape Sequences

To determine which CAGED form to display at each position in our template sequence, we implement a utility function that calculates the appropriate form based on the selected root chord and position index. This function maintains the circular nature of the CAGED system by using modulo arithmetic to wrap around the chord array, ensuring a continuous sequence that properly represents how these shapes connect across the fretboard.

import { CagedChord, cagedChords } from "./caged"

export const getCagedTemplateForm = (chord: CagedChord, index: number) =>
  cagedChords[(cagedChords.indexOf(chord) + index) % cagedChords.length]

Representing Fretboard Positions

To represent positions on the guitar fretboard, we use a simple data structure that captures both string and fret coordinates. Each note's location is identified by which string it's played on and at which fret position. The string is represented as a zero-based index (highest pitch string is 0) and the fret as a numeric value where -1 indicates an open string.

export type NotePosition = {
  // 0-based index of the string
  string: number
  // -1 if the note is open
  // 0 if the note is on the 1st fret
  fret: number
}

Handling Special Chord Voicings

To complete our CAGED system implementation, we need two specialized chord collections to handle the unique requirements of visualizing these shapes across the fretboard. While most open chord shapes naturally extend into the CAGED sequence, the D chord requires special treatment because its standard open voicing typically spans only four strings. To achieve a complete six-string D major voicing that maintains consistent intervallic relationships when shifted up the neck as a barre chord, we extend the D shape in our cagedTemplateOpenChords collection. In this extended version, we add the appropriate chord tones on the lower strings—fretting the low E string at the 2nd fret to produce F♯ (the major third) and using the open A string for the A (the fifth)—so that the complete D major chord (D, F♯, A) is represented. In contrast, our cagedTemplateBarreChords collection omits the highest string because it can be difficult to fret cleanly when barred in higher positions, a practical adaptation that preserves the chord's harmonic integrity throughout the CAGED system.

import { NotePosition } from "../note/NotePosition"

export const cagedViews = ["chord", "arpeggio"] as const

export type CagedView = (typeof cagedViews)[number]

export const cagedChords = ["c", "a", "g", "e", "d"] as const

export type CagedChord = (typeof cagedChords)[number]

export const openCagedChords: Record<CagedChord, NotePosition[]> = {
  c: [
    { string: 0, fret: -1 },
    { string: 1, fret: 0 },
    { string: 2, fret: -1 },
    { string: 3, fret: 1 },
    { string: 4, fret: 2 },
  ],
  a: [
    { string: 0, fret: -1 },
    { string: 1, fret: 1 },
    { string: 2, fret: 1 },
    { string: 3, fret: 1 },
    { string: 4, fret: -1 },
  ],
  g: [
    { string: 0, fret: 2 },
    { string: 1, fret: -1 },
    { string: 2, fret: -1 },
    { string: 3, fret: -1 },
    { string: 4, fret: 1 },
    { string: 5, fret: 2 },
  ],
  e: [
    { string: 0, fret: -1 },
    { string: 1, fret: -1 },
    { string: 2, fret: 0 },
    { string: 3, fret: 1 },
    { string: 4, fret: 1 },
    { string: 5, fret: -1 },
  ],
  d: [
    { string: 0, fret: 1 },
    { string: 1, fret: 2 },
    { string: 2, fret: 1 },
    { string: 3, fret: -1 },
  ],
}

export const cagedArpeggios: Record<CagedChord, NotePosition[]> = {
  c: [
    { string: 0, fret: -1 },
    { string: 0, fret: 2 },
    { string: 1, fret: 0 },
    { string: 2, fret: -1 },
    { string: 3, fret: 1 },
    { string: 4, fret: 2 },
    { string: 5, fret: -1 },
    { string: 5, fret: 2 },
  ],
  a: [
    { string: 0, fret: -1 },
    { string: 1, fret: 1 },
    { string: 2, fret: 1 },
    { string: 3, fret: -2 },
    { string: 3, fret: 1 },
    { string: 4, fret: -1 },
    { string: 5, fret: -1 },
  ],
  g: [
    { string: 0, fret: 2 },
    { string: 1, fret: -1 },
    { string: 1, fret: 2 },
    { string: 2, fret: -1 },
    { string: 3, fret: -1 },
    { string: 4, fret: 1 },
    { string: 5, fret: 2 },
  ],
  e: [
    { string: 0, fret: -1 },
    { string: 1, fret: -1 },
    { string: 2, fret: 0 },
    { string: 3, fret: 1 },
    { string: 4, fret: 1 },
    { string: 4, fret: -2 },
    { string: 5, fret: -1 },
  ],
  d: [
    { string: 0, fret: 1 },
    { string: 1, fret: 2 },
    { string: 2, fret: 1 },
    { string: 2, fret: -2 },
    { string: 3, fret: -1 },
    { string: 4, fret: -1 },
    { string: 5, fret: 1 },
  ],
}

export const cagedPositions: Record<
  CagedView,
  Record<CagedChord, NotePosition[]>
> = {
  chord: openCagedChords,
  arpeggio: cagedArpeggios,
}

export const cagedTemplateDistances = [3, 2, 3, 2, 2]

export const cagedTemplateOpenChords: Record<CagedChord, NotePosition[]> = {
  ...openCagedChords,
  d: [
    { string: 0, fret: 1 },
    { string: 1, fret: 2 },
    { string: 2, fret: 1 },
    { string: 3, fret: -1 },
    { string: 4, fret: -1 },
    { string: 5, fret: 1 },
  ],
}

export const cagedTemplateBarreChords: Record<CagedChord, NotePosition[]> = {
  ...cagedPositions.chord,
  d: [
    { string: 1, fret: 2 },
    { string: 2, fret: 1 },
    { string: 3, fret: -1 },
    { string: 4, fret: -1 },
    { string: 5, fret: 1 },
  ],
}

Calculating Fretboard Positions

To calculate the exact fretboard positions for each CAGED shape, we need a function that translates theoretical concepts into practical finger positions. The getCagedTemplatePartPositions function serves this purpose by determining not only which chord form to use, but also where on the neck it should be positioned. The CAGED system follows specific intervallic distances between shapes—3 frets from C to A, 2 from A to G, 3 from G to E, and 2 from E to D—which we store in cagedTemplateDistances. By rotating this array according to our starting chord and calculating cumulative distances, we can accurately position each shape at its proper fret position. This creates a continuous chain of the same chord ascending the neck, with each subsequent position shifted by the appropriate number of frets, maintaining harmonic consistency while changing fingering patterns.

import { rotateArray } from "@lib/utils/array/rotateArray"
import { sum } from "@lib/utils/array/sum"
import { match } from "@lib/utils/match"

import { NotePosition } from "../note/NotePosition"

import {
  CagedChord,
  CagedView,
  cagedChords,
  cagedPositions,
  cagedTemplateBarreChords,
  cagedTemplateDistances,
  cagedTemplateOpenChords,
} from "./caged"
import { getCagedTemplateForm } from "./getCagedTemplateForm"

type GetCagedTemplatePartPositionsInput = {
  chord: CagedChord
  view: CagedView
  index: number
}

export const getCagedTemplatePartPositions = ({
  chord,
  view,
  index,
}: GetCagedTemplatePartPositionsInput): NotePosition[] => {
  const form = getCagedTemplateForm(chord, index)

  const distances = rotateArray(
    cagedTemplateDistances,
    cagedChords.indexOf(chord),
  )

  const openPositions = match(view, {
    arpeggio: () => cagedPositions.arpeggio[form],
    chord: () => {
      const chords =
        index === 0 ? cagedTemplateOpenChords : cagedTemplateBarreChords

      return chords[form]
    },
  })

  const shift = sum(distances.slice(0, index))

  return openPositions.map((position) => ({
    ...position,
    fret: position.fret + shift,
  }))
}

Identifying Root Notes

When visualizing chord shapes across the fretboard, identifying the root note in its bass position provides crucial orientation for guitarists. The getChordPrimaryPosition utility accomplishes this by locating the lowest-pitched occurrence of a specified note within each chord shape. By ordering positions from bass strings to treble strings and finding the first matching note, we ensure consistent root identification across all CAGED positions. This approach works universally for any chord in the CAGED system, helping guitarists maintain their bearings by highlighting the root note as it appears in different positions along the neck, regardless of which chord they're playing or which CAGED shape they're using.

import { order } from "@lib/utils/array/order"

import { tuning } from "../../app/guitar/config"
import { getNoteFromPosition } from "../note/getNoteFromPosition"
import { NotePosition } from "../note/NotePosition"

export const getChordPrimaryPosition = ({
  positions,
  note,
}: {
  positions: NotePosition[]
  note: number
}) =>
  order(positions, (p) => p.string, "desc").find(
    (position) => getNoteFromPosition({ tuning, position }) === note,
  )

Implementing the Template Component

Now let's implement the CagedTemplatePart component, the visual foundation of our CAGED system. This component integrates our utility functions to render each shape contextually on the fretboard. It determines the appropriate form for each position, calculates exact fret locations, and highlights the root note for orientation. For arpeggios, we use a special marker (fret value -2) to indicate notes that belong theoretically but can't be practically played in that position. The component filters these unplayable positions during rendering, keeping only open strings (-1) and fretted notes. Based on this filtering, it dynamically labels arpeggios as "incomplete" when appropriate—a situation that occurs with A, E, and D shapes in open positions. By the time we reach the 6th position (around the 12th fret), these arpeggios become fully playable. This final position completes our visualization and demonstrates how the CAGED system forms a continuous cycle repeating at the octave, providing clear insight into how these shapes interconnect across the entire fretboard.

import { VStack } from "@lib/ui/css/stack"
import { IndexProp } from "@lib/ui/props"
import { Text } from "@lib/ui/text"
import { match } from "@lib/utils/match"
import { getCagedTemplateForm } from "@product/core/chords/getCagedTemplateForm"
import { getCagedTemplatePartPositions } from "@product/core/chords/getCagedTemplatePartPositions"
import { getChordPrimaryPosition } from "@product/core/chords/getChordPrimaryPosition"
import { chromaticNotesNames } from "@product/core/note"
import { useMemo } from "react"

import { Fretboard } from "../../guitar/fretboard/Fretboard"
import { Note } from "../../guitar/fretboard/Note"

import { useCagedTemplate } from "./state/cagedTemplate"

export const CagedTemplatePart = ({ index }: IndexProp) => {
  const { chord, view } = useCagedTemplate()

  const form = getCagedTemplateForm(chord, index)

  const positions = useMemo(() => {
    return getCagedTemplatePartPositions({
      chord,
      view,
      index,
    })
  }, [chord, index, view])

  const primaryPosition = getChordPrimaryPosition({
    positions,
    note: chromaticNotesNames.indexOf(chord.toUpperCase()),
  })

  const title = useMemo(() => {
    return match(view, {
      arpeggio: () => {
        const isIncomplete = positions.some((position) => position.fret < -1)
        if (isIncomplete) {
          return `Open ${chord.toUpperCase()} chord (incomplete arpeggio)`
        }
        return `${chord.toUpperCase()} arpeggio ("${form.toUpperCase()} form")`
      },
      chord: () =>
        index === 0
          ? `Open ${chord.toUpperCase()} chord`
          : `${chord.toUpperCase()} ("${form.toUpperCase()} form" barre chord)`,
    })
  }, [chord, form, index, positions, view])

  return (
    <VStack gap={40}>
      <Text centerHorizontally color="contrast" as="h3" weight="700" size={18}>
        {title}
      </Text>
      <Fretboard>
        {positions
          .filter((position) => position.fret >= -1)
          .map((position) => (
            <Note
              key={`${position.string}-${position.fret}`}
              string={position.string}
              fret={position.fret}
              kind={position === primaryPosition ? "primary" : "regular"}
            />
          ))}
      </Fretboard>
    </VStack>
  )
}

Conclusion

By implementing this CAGED system visualization, we've created a practical tool that helps guitarists understand how chord shapes interconnect across the entire fretboard. This approach not only demystifies the relationship between chord forms but also provides a systematic framework for exploring different voicings of the same chord in multiple positions.

Building a Type-Safe Router for React Without Browser Navigation

Radzion Chachura — Sat, 24 May 2025 03:22:38 +0000

🐙 GitHub

In this post, we will build a typed routing navigation system for React apps without using external libraries. While most web applications benefit from full browser navigation with URL pathnames, there are specific scenarios where simpler routing solutions make sense. Desktop apps built with Electron, Chrome extensions, or simple browser widgets often don't require traditional URL-based navigation. These applications typically bundle everything together without lazy loading, functioning more like traditional software.

There are also cases where your specific requirements aren't easily addressed by existing routing libraries. Today, I'll share a routing foundation I developed for such a situation, which I now use whenever traditional browser navigation isn't needed. Though for most standard web applications, I recommend using TanStack Router, as it provides excellent typed navigation out of the box. If you're curious about implementing a custom router for your specific needs, let's explore how it works. You can find all the source code in this repository.

Defining View Types

To illustrate the implementation, let's create a simple widget with three distinct views: a home screen with calculation state, a settings page, and a results view.

export type AppView =
  | {
      id: "home"
      state: CalculationState
    }
  | {
      id: "settings"
    }
  | {
      id: "result"
      state: CalculationState
    }

export type AppViewId = AppView["id"]

The home screen allows you to select a calculation operation and generate two random numbers to work with. When you navigate to the result view, the application displays the calculated outcome based on your selected operation and inputs.

export const calculationOperations = [
  "sum",
  "subtract",
  "multiply",
  "divide",
] as const
export type CalculationOperation = (typeof calculationOperations)[number]

export type CalculationState = {
  inputs: number[]
  operation: CalculationOperation
}

When you launch the widget, your initial view displays the home screen with a predefined calculation state.

export const initialView: AppView = {
  id: "home",
  state: {
    inputs: [5, 3],
    operation: "sum",
  },
}

Core Router Structure

In our router implementation, a view consists of both a path identifier and optional state data. This approach mirrors how traditional routing systems work, where data is typically passed between views using URL query parameters or browser history state. However, since we're building a solution independent of browser navigation features, we're implementing our own state management system.

export type View = {
  id: string
  state?: any
}

To define views with type safety, we'll create a generic Views type that receives a type parameter T. In our application, this parameter will be the AppViewId type—a union of 'home', 'settings', and 'result' strings—ensuring our router recognizes only valid view identifiers.

import { ComponentType } from "react"

export type Views<T extends string = string> = Record<T, ComponentType<any>>

With our Views type defined, we'll now map each route identifier to its corresponding React component, establishing the connection between our navigation system and the actual UI elements rendered for each view.

import { Views } from "@lib/navigation/Views"

import { HomeView } from "../HomeView"
import { ResultView } from "../ResultView"
import { SettingsView } from "../SettingsView"

import { AppViewId } from "./AppView"

export const views: Views<AppViewId> = {
  home: HomeView,
  settings: SettingsView,
  result: ResultView,
}

Navigation State Management

To enable backward navigation within our application, we'll structure our navigation state around two key elements: an array that maintains the complete history of visited views, and a numeric index that tracks our current position within that history stack. This approach mimics how browser history works while giving us full control over the navigation experience.

import { getStateProviderSetup } from "@lib/ui/state/getStateProviderSetup"

import { View } from "./View"

type NavigationState = {
  history: View[]
  currentIndex: number
}

export const { useState: useNavigation, provider: NavigationProvider } =
  getStateProviderSetup<NavigationState>("Navigation")

The getStateProviderSetup function is a utility from RadzionKit that generates a React Context provider and a custom hook for state management. In our navigation system, it creates a provider component and a hook to access navigation state throughout the application without writing boilerplate context code.

import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"
import { Dispatch, SetStateAction, createContext, useState } from "react"

import { ChildrenProp } from "../props"

import { ContextState } from "./ContextState"
import { createContextHook } from "./createContextHook"

export function getStateProviderSetup<T>(name: string) {
  const Context = createContext<ContextState<T> | undefined>(undefined)

  type Props = ChildrenProp & { initialValue: T }

  const Provider = ({ children, initialValue }: Props) => {
    const [value, setValue] = useState(initialValue)

    return (
      <Context.Provider value={{ value, setValue }}>
        {children}
      </Context.Provider>
    )
  }

  return {
    provider: Provider,
    useState: createContextHook(
      Context,
      capitalizeFirstLetter(name),
      (result): [T, Dispatch<SetStateAction<T>>] => [
        result.value,
        result.setValue,
      ],
    ),
  }
}

Setting Up the Application

To implement our navigation system, we'll wrap the application in a NavigationProvider component that exposes the navigation state to all child components throughout the component tree. We initialize the navigation with currentIndex set to 0 and a history array containing only our previously defined initial view.

import { ActiveView } from "@lib/navigation/ActiveView"
import { NavigationProvider } from "@lib/navigation/state"

import { Layout } from "./Layout"
import { initialView } from "./navigation/AppView"
import { views } from "./navigation/views"

export const NavigationDemo = () => (
  <NavigationProvider
    initialValue={{ history: [initialView], currentIndex: 0 }}
  >
    <Layout>
      <ActiveView views={views} />
    </Layout>
  </NavigationProvider>
)

Creating a Layout Component

Next, we'll implement a Layout component to create a consistent container for all views in our application. This layout includes a back button in the top-left corner that remains disabled unless there's both a previous view in the navigation history and the current view isn't the first one in the sequence.

import { useNavigateBack } from "@lib/navigation/hooks/useNavigateBack"
import { useNavigation } from "@lib/navigation/state"
import { IconButton } from "@lib/ui/buttons/IconButton"
import { borderRadius } from "@lib/ui/css/borderRadius"
import { interactive } from "@lib/ui/css/interactive"
import { hStack, vStack } from "@lib/ui/css/stack"
import { ChevronLeftIcon } from "@lib/ui/icons/ChevronLeftIcon"
import { SettingsIcon } from "@lib/ui/icons/SettingsIcon"
import { ChildrenProp } from "@lib/ui/props"
import { text } from "@lib/ui/text"
import { getColor } from "@lib/ui/theme/getters"
import styled from "styled-components"

import { initialView } from "./navigation/AppView"
import { useAppNavigate } from "./navigation/hooks/useAppNavigate"

const Container = styled.div`
  width: 320px;
  ${borderRadius.m}
  ${vStack()};
  border: 1px solid ${getColor("mist")};

  > * {
    padding: 12px;
  }
`

const Header = styled.div`
  ${hStack({
    alignItems: "center",
    justifyContent: "space-between",
  })};
  background: ${getColor("mist")};
`

const Content = styled.div`
  ${vStack({
    gap: 20,
    justifyContent: "space-between",
  })};
  min-height: 200px;
`

const Title = styled.div`
  ${interactive};
  ${text({
    size: 20,
    weight: 600,
  })};
  &:hover {
    color: ${getColor("contrast")};
  }
`

export const Layout = ({ children }: ChildrenProp) => {
  const [{ history, currentIndex }] = useNavigation()
  const goBack = useNavigateBack()
  const navigate = useAppNavigate()

  return (
    <Container>
      <Header>
        <IconButton
          isDisabled={history.length < 2 || currentIndex === 0}
          icon={<ChevronLeftIcon />}
          title="Back"
          onClick={goBack}
        />
        <Title onClick={() => navigate(initialView)}>Calculator</Title>
        <IconButton
          icon={<SettingsIcon />}
          title="Settings"
          onClick={() => navigate({ id: "settings" })}
        />
      </Header>
      <Content>{children}</Content>
    </Container>
  )
}

Implementing Navigation Hooks

Now let's implement the hook that powers our back button functionality. The useNavigateBack hook provides a clean abstraction for navigating to previous views in our history stack. It checks if backward navigation is possible by verifying the current position in our history array, and simply decrements the index when called.

import { useCallback } from "react"

import { useNavigation } from "../state"

export const useNavigateBack = () => {
  const [, setState] = useNavigation()

  return useCallback(() => {
    setState((state) => {
      if (state.currentIndex <= 0) {
        return state
      }

      return {
        ...state,
        currentIndex: state.currentIndex - 1,
      }
    })
  }, [setState])
}

The useAppNavigate hook provides type safety for navigation, ensuring you can only pass views that conform to the AppView type definition. This prevents potential runtime errors by catching invalid navigation attempts during development.

import { useNavigate } from "@lib/navigation/hooks/useNavigate"

import { AppView } from "../AppView"

export function useAppNavigate() {
  return useNavigate<AppView>()
}

Creating a Type-Safe Navigation Hook

The generic useNavigate hook powers our navigation system and provides the foundation for type-safe navigation. It manages history by tracking view entries and their associated state, handling both regular navigation and view replacement through a simple options parameter. When called with a view entry, it either adds a new history item or updates the current one, maintaining the appropriate index position for backward navigation.

import { updateAtIndex } from "@lib/utils/array/updateAtIndex"
import { useCallback } from "react"

import { useNavigation } from "../state"
import { View } from "../View"

type NavigateOptions = {
  replace?: boolean
}

export function useNavigate<T extends View = View>() {
  const [, setState] = useNavigation()

  return useCallback(
    (entry: T, options: NavigateOptions = {}) => {
      const { id, state } = entry
      const { replace } = options

      setState((prev) => {
        if (replace) {
          return {
            ...prev,
            history: updateAtIndex(prev.history, prev.currentIndex, () => ({
              id,
              state,
            })),
          }
        }

        const newHistory = [...prev.history, { id, state }]

        return {
          history: newHistory,
          currentIndex: newHistory.length - 1,
        }
      })
    },
    [setState],
  )
}

Rendering the Active View

With our navigation hooks in place, we now need a component that renders the appropriate UI based on the current navigation state. The ActiveView component serves as the bridge between our navigation system and the actual view components. It extracts the current view ID from our navigation history at the current index position, looks up the corresponding component from our views mapping, and renders it to the screen.

import { useNavigation } from "./state"
import { Views } from "./Views"

type ActiveViewProps = {
  views: Views
}

export const ActiveView = ({ views }: ActiveViewProps) => {
  const [state] = useNavigation()

  const View = views[state.history[state.currentIndex].id]

  return <View />
}

Building the View Components

To demonstrate how view state changes work, the HomeView component provides two interactive elements: a radio input for selecting calculation operations and a button to generate new random inputs. When users interact with these controls, the application updates the state by pushing new view entries to the navigation history array, ensuring both the UI and internal state remain synchronized.

import { Button } from "@lib/ui/buttons/Button"
import { IconButton } from "@lib/ui/buttons/IconButton"
import { HStack } from "@lib/ui/css/stack"
import { RefreshIcon } from "@lib/ui/icons/RefreshIcon"
import { GroupedRadioInput } from "@lib/ui/inputs/GroupedRadioInput"
import { Text } from "@lib/ui/text"
import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"
import { randomIntegerInRange } from "@lib/utils/randomInRange"

import { calculationOperations } from "./CalculationState"
import { InputItem } from "./InputItem"
import { useAppNavigate } from "./navigation/hooks/useAppNavigate"
import { useAppViewState } from "./navigation/hooks/useAppViewState"

export const HomeView = () => {
  const [state, setState] = useAppViewState<"home">()
  const navigate = useAppNavigate()

  return (
    <>
      <GroupedRadioInput
        value={state.operation}
        onChange={(operation) => {
          setState((prev) => ({
            ...prev,
            operation,
          }))
        }}
        options={calculationOperations}
        renderOption={capitalizeFirstLetter}
      />
      <HStack alignItems="center" gap={8} justifyContent="space-between">
        <HStack alignItems="center" gap={8}>
          <IconButton
            icon={<RefreshIcon />}
            title="Generate new inputs"
            onClick={() => {
              setState((prev) => ({
                ...prev,
                inputs: prev.inputs.map(() => randomIntegerInRange(1, 10)),
              }))
            }}
          />
          <Text>Inputs:</Text>
        </HStack>
        <HStack alignItems="center" gap={8}>
          {state.inputs.map((input, index) => (
            <InputItem key={index} index={index} value={input} />
          ))}
        </HStack>
      </HStack>

      <Button onClick={() => navigate({ id: "result", state })}>
        Calculate
      </Button>
    </>
  )
}

Type-Safe State Management

To properly handle state in our typed navigation system, we need a mechanism that preserves type information across different views. When accessing a view's state, we want TypeScript to know exactly which properties are available based on the view ID. The useAppViewState hook provides this capability by leveraging TypeScript's type system to extract the correct state type for each view. This ensures you can only access state properties that actually exist for the current view.

import { useViewState } from "@lib/navigation/hooks/useViewState"

import { AppView } from "../AppView"

type AppViewWithState = Extract<AppView, { state: any }>
type AppViewWithStateId = AppViewWithState["id"]
type AppViewStateMap = {
  [K in AppViewWithStateId]: Extract<AppView, { id: K }>["state"]
}

export function useAppViewState<P extends AppViewWithStateId>() {
  return useViewState<AppViewStateMap[P]>()
}

Managing View State

The useAppViewState hook builds on a more fundamental hook that manages state updates for any view type. The useViewState hook handles the core functionality of accessing and updating state within our navigation system. It returns both the current view's state and a setter function that maintains our navigation history, similar to React's useState pattern. When state changes occur, rather than simply updating the existing entry, it creates a new history item with the updated state, allowing users to navigate back to previous states while preserving the view's identity.

import { Dispatch, SetStateAction, useCallback } from "react"

import { useNavigation } from "../state"

export function useViewState<T = any>(): [T, Dispatch<SetStateAction<T>>] {
  const [state, setState] = useNavigation()
  const currentState = state.history[state.currentIndex].state as T

  const setRouteState = useCallback(
    (newState: SetStateAction<T>) => {
      setState((prev) => {
        const id = prev.history[prev.currentIndex].id
        const state =
          typeof newState === "function"
            ? (newState as (prevState: T) => T)(
                prev.history[prev.currentIndex].state,
              )
            : newState

        const history = [...prev.history, { id, state }]

        return {
          ...prev,
          history,
          currentIndex: history.length - 1,
        }
      })
    },
    [setState],
  )

  return [currentState, setRouteState]
}

Displaying Calculation Results

Clicking the "Calculate" button on the home screen triggers a sequence of navigation actions: a new view entry is pushed to the history array, the current index increments, and the ActiveView component responds by rendering ResultView. The result view then accesses the calculation state through the useAppViewState hook to display the computation outcome.

import { HStack } from "@lib/ui/css/stack"
import { Text } from "@lib/ui/text"
import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"
import { match } from "@lib/utils/match"

import { CalculationState } from "./CalculationState"
import { InputItem } from "./InputItem"
import { useAppViewState } from "./navigation/hooks/useAppViewState"

const calculateResult = ({ inputs, operation }: CalculationState): number => {
  return match(operation, {
    sum: () => inputs.reduce((sum, num) => sum + num, 0),
    subtract: () =>
      inputs.reduce(
        (result, num, index) => (index === 0 ? num : result - num),
        0,
      ),
    multiply: () => inputs.reduce((product, num) => product * num, 1),
    divide: () =>
      inputs.reduce(
        (result, num, index) => (index === 0 ? num : result / num),
        0,
      ),
  })
}

export const ResultView = () => {
  const [state] = useAppViewState<"result">()
  const result = calculateResult(state)

  return (
    <>
      <HStack alignItems="center" gap={8} justifyContent="space-between">
        <Text>Operation:</Text>
        {capitalizeFirstLetter(state.operation)}
      </HStack>

      <HStack alignItems="center" gap={8} justifyContent="space-between">
        <Text>Inputs:</Text>
        <HStack alignItems="center" gap={8}>
          {state.inputs.map((input, index) => (
            <InputItem key={index} index={index} value={input} />
          ))}
        </HStack>
      </HStack>

      <HStack alignItems="center" gap={8} justifyContent="space-between">
        <Text>Result:</Text>
        {result.toFixed(2)}
      </HStack>
    </>
  )
}

Conclusion

This lightweight routing solution provides type-safe navigation for React applications that don't require browser-based routing, making it particularly valuable for desktop apps, extensions, and widgets where you need full control over navigation state without URL dependencies.

Building a Vocabulary Tool for Audiobook Lovers with TypeScript

Radzion Chachura — Sat, 17 May 2025 03:21:22 +0000

🐙 GitHub

The Challenge of Unfamiliar Words

Fiction has always captivated me, and I find audiobooks to be the perfect medium to experience it. While most audiobooks are in English, which isn't my native language, I've developed strong proficiency in it over the years. However, fiction often introduces rare words that remain unfamiliar to non-native speakers, especially those of us who don't live in English-speaking countries. My goal is simple: learn these words to enhance my audiobook experience. After all, the fewer unknown words I encounter, the more vivid and immersive the story becomes in my mind.

In this article, I'll walk you through a practical solution for expanding your vocabulary while enjoying audiobooks. I've developed a TypeScript script that helps identify and extract unfamiliar words, making the learning process more systematic. The complete implementation is available on GitHub if you'd like to try it yourself or build upon it.

Project Structure

There are three files specific to you in this project:

input.epub: This is the book from which you want to extract words.
output.txt: This file will contain all the new words from the book you provided.
ignore_words.txt: This file will include all the words you already know or wish to ignore.

Getting Started

To get started, install the dependencies with yarn, then navigate to the product/words directory. Run yarn start to process your book, and the script will generate an output.txt file containing all the new words found in your text.

How It Works

The implementation processes the book in several steps. First, it extracts all words from the EPUB file and loads your list of known words. It then filters out words that are too short (less than 3 characters), already known, or incorrectly spelled according to the English dictionary. For each remaining word, it determines the base form (for example, "running" becomes "run") to avoid learning different forms of the same word separately. Finally, it saves the unique set of new base words to the output file.

import fs from "fs"
import path from "path"

import nspell from "nspell"

import { extractWordsFromEpub } from "./core/extractWordsFromEpub"
import { getWordBaseForm } from "./core/getWordBaseForm"

const inputSrc = path.join(__dirname, "input.epub")
const outputSrc = path.join(__dirname, "output.txt")
const ignoreWordsSrc = path.join(__dirname, "ignore_words.txt")

const main = async () => {
  const en = await import("dictionary-en")

  const spell = nspell(en.default as any)

  const allWords = await extractWordsFromEpub(inputSrc)
  const ignoreWords = await fs.promises.readFile(ignoreWordsSrc, "utf-8")
  const ignoreWordsSet = new Set(ignoreWords.split("\n"))

  const result = new Set<string>()

  allWords.forEach((word) => {
    if (word.length < 3 || ignoreWordsSet.has(word) || !spell.correct(word)) {
      return
    }

    const baseForm = getWordBaseForm(word)

    if (ignoreWordsSet.has(baseForm)) {
      return
    }

    result.add(baseForm)
  })

  fs.promises.writeFile(outputSrc, Array.from(result).join("\n"), "utf-8")
}

main()

Extracting Words from EPUB Files

The core functionality for extracting words from EPUB files relies on the epub package to parse the book's content. The implementation processes each chapter sequentially, stripping HTML tags and breaking the text into sentences. For each sentence, we extract individual words while applying several filters: removing punctuation, handling whitespace, and excluding numbers. To maintain consistency with English text conventions, we convert first words of sentences to lowercase only if they're common words, and for other positions, we exclude words that start with capital letters to avoid including proper nouns. This approach helps focus on learning common vocabulary rather than names or places.

import EPub from "epub"

export const extractWordsFromEpub = async (
  filePath: string,
): Promise<Set<string>> => {
  return new Promise((resolve, reject) => {
    const epub = new EPub(filePath)
    const wordSet = new Set<string>()

    epub.on("end", () => {
      const chapters = [...epub.flow]

      const processChapter = (chapterIndex: number) => {
        if (chapterIndex >= chapters.length) {
          resolve(wordSet)
          return
        }

        const chapter = chapters[chapterIndex]
        epub.getChapter(chapter.id, (error: Error | null, text: string) => {
          if (error) {
            reject(error)
            return
          }

          const strippedText = text.replace(/<[^>]*>/g, " ")

          const sentences = strippedText.split(/[.!?]+/)

          sentences.forEach((sentence) => {
            const words = sentence
              .replace(/[^\w\s-]/g, " ")
              .replace(/\s+/g, " ")
              .trim()
              .split(" ")
              .filter((word) => word.length > 0)
              .filter((word) => !/\d/.test(word))

            if (words.length > 0) {
              const firstWord = words[0].toLowerCase()
              if (firstWord.length > 0) {
                wordSet.add(firstWord)
              }

              words.slice(1).forEach((word) => {
                if (word.length > 0 && !/^[A-Z]/.test(word)) {
                  wordSet.add(word.toLowerCase())
                }
              })
            }
          })

          processChapter(chapterIndex + 1)
        })
      }

      processChapter(0)
    })

    epub.on("error", (error: Error) => {
      reject(error)
    })

    epub.parse()
  })
}

Handling Word Forms with NLP

To handle different word forms effectively, we need to extract the base form of each word. For example, we want to treat "running," "runs," and "ran" as variations of "run." The getWordBaseForm function uses the compromise natural language processing library to handle this conversion. It processes words through several steps: first checking if it's a noun that needs to be converted to singular form, then attempting to find the infinitive form of verbs, and finally handling adjectives and adverbs. For adverbs specifically, we maintain a mapping of common suffixes to transform them back to their adjectival form.

Learning Workflow

After running the script, I review the words in the output.txt file and look up any unfamiliar ones in a ChatGPT chat to learn their meanings. As I process each section of familiar words, I add them to the ignore_words.txt file, ensuring they won't appear in subsequent runs of the tool.

I am a native Russian speaker with a strong command of English, but I occasionally encounter new words. I will provide you with an English word, and I would like you to translate it and offer a clear explanation to help me remember its meaning effectively.

import { order } from "@lib/utils/array/order"
import nlp from "compromise"
import Three from "compromise/types/view/three"

const getAdjective = (doc: Three) => {
  const adjective = doc.adjectives()
  const [adjectiveResult] = adjective.conjugate()
  if (adjectiveResult && "Adjective" in adjectiveResult) {
    return adjectiveResult.Adjective as string
  }
}

const adverbAdjectiveSuffixes: Record<string, string> = {
  ibly: "ible",
  ably: "able",
  ally: "al",
  ily: "y",
  ly: "",
}

const adverbSuffixes = order(
  Object.keys(adverbAdjectiveSuffixes),
  (suffix) => suffix.length,
  "desc",
)

export const getWordBaseForm = (word: string): string => {
  const doc = nlp(`${word} to`)

  const singularForm = doc.nouns().toSingular().text()
  if (singularForm) {
    return singularForm
  }

  const baseForm = doc.verbs().toInfinitive().text()
  if (baseForm) {
    return baseForm.replace(" to", "")
  }

  const adjective = getAdjective(doc)
  if (adjective) {
    return adjective
  }

  const adverb = doc.adverbs().text()
  if (adverb) {
    const suffix = adverbSuffixes.find((suffix) => adverb.endsWith(suffix))
    if (suffix) {
      const replacement = adverbAdjectiveSuffixes[suffix]
      const adjective = getAdjective(
        nlp(adverb.slice(0, -suffix.length) + replacement),
      )
      if (adjective) {
        return adjective
      }
    }
  }

  return word
}

Conclusion

This TypeScript implementation combines EPUB parsing, natural language processing, and word form normalization to create a practical tool for vocabulary expansion. By systematically extracting and processing unfamiliar words from audiobooks, it provides a structured approach to language learning that enhances the reading experience for non-native English speakers.

Building a React-Based Guitar Theory Practice Page: Connecting Theory and Application

Radzion Chachura — Sat, 10 May 2025 03:44:33 +0000

🐙 GitHub | 🎮 Demo

Welcome to the sixth post in our series on building a React-based guitar theory learning app. While we've explored guitar scales and CAGED concepts in previous posts, theory alone isn't enough—we need practical application to reinforce these concepts. In this post, we'll create a songs page that helps you find music specifically tailored to practice different aspects of guitar theory. You can find all the source code in the GitHub repository.

Organizing Songs by Theory Topics

For the content of this page, we've curated a comprehensive collection of songs from Desi Serna's "Fretboard Theory" book. Each song serves as a practical example of specific guitar theory concepts, organized into 40 distinct sections.

import { ClientOnly } from "@lib/ui/base/ClientOnly"

export const guitarTheoryTopics = [
  "e-minor-pentatonic",
  "g-major-pentatonic",
  "g-minor-pentatonic",
  "pentatonic",
  "blues-scale",
  "c-form",
  "a-form",
  "g-form",
  "e-form",
  "d-form",
  "minor-forms",
  "chromatic-riffs",
  "major-scale",
  "major-scale-not-all-seven-degrees",
  "major-scale-chromatic-passing-tones",
  "triads",
  "major-chords-1-4-5",
  "minor-chords-2-3-6",
  "major-chords-1-4-5-string-5",
  "minor-chords-2-3-6-string-5",
  "e-major-root",
  "a-minor-root",
  "changing-pentatonic-scales",
  "blues",
  "ionian-mode",
  "dorian-mode",
  "lydian-mode",
  "mixolydian-mode",
  "aeolian-mode",
  "inverted-power-chords",
  "thirds",
  "sixths",
  "sixth-and-flat-seventh",
  "octaves",
  "minor-seven",
  "major-seven",
  "dominant-seven",
  "minor-seven-am-form",
  "e-form-major-seven",
  "c-form-add-9",
] as const

export type GuitarTheoryTopic = (typeof guitarTheoryTopics)[number]

Creating the Song Data Structure

The Song type represents a musical piece with three key properties: name, artist, and an optional details field. The details field captures important contextual information such as the song's key or specific sections relevant to guitar theory practice. For example, when studying pentatonic scales, the details might highlight a particular guitar riff that demonstrates the scale's application, allowing focused practice on that specific section rather than the entire song.

import { withoutUndefined } from "@lib/utils/array/withoutUndefined"

import { GuitarTheoryTopic } from "./GuitarTheoryTopic"

export type Song = {
  name: string
  artist: string
  details?: string
}

Mapping Topics to Song Collections

To organize our song collection, we'll use a TypeScript Record where each guitar theory topic maps to its corresponding array of songs. For simplicity, we'll focus exclusively on guitar pieces in standard tuning, omitting bass guitar arrangements and alternate tunings that were present in the original Fretboard Theory material.

import { GuitarTheoryTopic } from "./GuitarTheoryTopic"
import { Song } from "./Song"

export const songs: Record<GuitarTheoryTopic, Song[]> = {
  "e-minor-pentatonic": [
    {
      name: "Susie Q",
      artist: "Creedence Clearwater Revival",
      details: "Guitar riff",
    },
    {
      name: "Green River",
      artist: "Creedence Clearwater Revival",
      details: "Guitar riff",
    },
    {
      name: "Purple Haze",
      artist: "Jimi Hendrix",
      details: "Guitar riff",
    },
    {
      name: "Are You Gonna Go My Way",
      artist: "Lenny Kravitz",
      details: "Guitar riff",
    },
    {
      name: "Voodoo Child (Slight Return)",
      artist: "Jimi Hendrix",
      details: "Guitar riff",
    },
    {
      name: "Back In Black",
      artist: "AC/DC",
      details: "Guitar riff",
    },
    {
      name: "Man in the Box",
      artist: "Alice In Chains",
      details: "Guitar riff",
    },
    {
      name: "Play That Funky Music",
      artist: "Wild Cherry",
      details: "Guitar during verse",
    },
    {
      name: "Paranoid",
      artist: "Black Sabbath",
      details: "Guitar solo",
    },
    {
      name: "Hey Joe",
      artist: "Jimi Hendrix",
      details: "Guitar solo",
    },
    {
      name: "Turn Off the Light",
      artist: "Nelly Furtado",
      details: "Guitar solo",
    },
    {
      name: "Pawn Shop",
      artist: "Sublime",
      details: "Guitar solo",
    },
  ],
  "g-major-pentatonic": [
    {
      name: "Honky Tonk Woman",
      artist: "The Rolling Stones",
      details: "Intro guitar lick",
    },
    {
      name: "Wish You Were Here",
      artist: "Pink Floyd",
      details: "Guitar intro",
    },
    {
      name: "Sweet Home Alabama",
      artist: "Lynyrd Skynyrd",
      details: "Guitar intro and solos",
    },
    {
      name: "Centerfold",
      artist: "The J. Geils Band",
      details: "Guitar riff",
    },
    {
      name: "Cannonball",
      artist: "Duane Eddy",
      details: "Guitar riff",
    },
  ],
  "g-minor-pentatonic": [
    {
      name: "Money for Nothing",
      artist: "Dire Straits",
      details: "Guitar riff",
    },
    {
      name: "I Shot the Sheriff",
      artist: "Bob Marley/Eric Clapton",
      details: "Guitar riff at chorus end",
    },
    {
      name: "Play That Funky Music",
      artist: "Wild Cherry",
      details: "Guitar riff during chorus",
    },
    {
      name: "Are You Gonna Go My Way",
      artist: "Lenny Kravitz",
      details: "Guitar riff",
    },
    {
      name: "Lady Marmalade",
      artist: "Patti Labelle",
    },
  ],
  // ...
}

Building the Songs Page Component

Now, let's implement the songs page component that will display this collection. The page structure is straightforward - we'll use a container with a title and a list of sections, where each section corresponds to a guitar theory topic and its associated songs.

import { VStack } from "@lib/ui/css/stack"
import { guitarTheoryTopics } from "@product/core/songs/GuitarTheoryTopic"

import { PageContainer } from "../layout/PageContainer"

import { SongsPageTitle } from "./SongsPageTitle"
import { SongsSection } from "./SongsSection"

export const SongsPage = () => {
  return (
    <PageContainer contentMaxWidth={640}>
      <VStack gap={60}>
        <SongsPageTitle />
        <VStack gap={20}>
          {guitarTheoryTopics.map((topic) => (
            <SongsSection key={topic} value={topic} />
          ))}
        </VStack>
      </VStack>
    </PageContainer>
  )
}

Handling Client-Side State with Next.js

Since our application is built with Next.js and uses static site generation (SSG), we need to handle components that depend on client-side state carefully. The ClientOnly component ensures that sections are only rendered in the browser, where we can access localStorage to maintain which theory topics a user has expanded. This prevents hydration mismatches that would occur if we tried to render these dynamic sections during static generation, as each user will have their own unique set of expanded sections stored locally.

import { ClientOnly } from "@lib/ui/base/ClientOnly"
import { vStack, VStack } from "@lib/ui/css/stack"
import { verticalPadding } from "@lib/ui/css/verticalPadding"
import { ValueProp } from "@lib/ui/props"
import { songs } from "@product/core/songs"
import { GuitarTheoryTopic } from "@product/core/songs/GuitarTheoryTopic"
import { getGuitarTheorySongId } from "@product/core/songs/Song"
import styled from "styled-components"

import { SongItem } from "./SongItem"
import { SongsSectionHeader } from "./SongSectionHeader"
import { useExpandedSongTopics } from "./state/expandedSongTopics"

const Content = styled.div`
  ${vStack({ gap: 12 })}
  ${verticalPadding(8)}
`

export const SongsSection = ({ value }: ValueProp<GuitarTheoryTopic>) => {
  const items = songs[value]

  const [expandedTopics] = useExpandedSongTopics()

  const isExpanded = expandedTopics.includes(value)

  return (
    <VStack>
      <SongsSectionHeader value={value} />
      <ClientOnly>
        {isExpanded && (
          <Content>
            {items.map((song) => (
              <SongItem
                key={getGuitarTheorySongId(value, song)}
                song={song}
                topic={value}
              />
            ))}
          </Content>
        )}
      </ClientOnly>
    </VStack>
  )
}

Persisting User Preferences with Local Storage

To maintain a consistent user experience across sessions, we store which sections are expanded in the browser's local storage. This allows users to return to their previous view state without having to re-expand all the sections they were interested in. For a deeper dive into our storage implementation, check out the dedicated blog post.

import { guitarTheoryTopics } from "@product/core/songs/GuitarTheoryTopic"

import { PersistentStateKey } from "../../state/persistentState"
import { usePersistentState } from "../../state/persistentState"

const defaultValue = guitarTheoryTopics.slice(0, 1)

export const useExpandedSongTopics = () => {
  return usePersistentState<string[]>(
    PersistentStateKey.ExpandedSongTopics,
    defaultValue,
  )
}

Creating Interactive Section Headers

Each section header serves as both a navigation element and a progress indicator. The SongsSectionHeader component displays the theory topic name and manages the expanded/collapsed state of its song list. It also includes a visual indicator that shows whether any songs in that section have been marked as learned. This interactive element helps users quickly identify which concepts they've practiced.

import { ClientOnly } from "@lib/ui/base/ClientOnly"
import { UnstyledButton } from "@lib/ui/buttons/UnstyledButton"
import { round } from "@lib/ui/css/round"
import { sameDimensions } from "@lib/ui/css/sameDimensions"
import { hStack } from "@lib/ui/css/stack"
import { verticalPadding } from "@lib/ui/css/verticalPadding"
import { Center } from "@lib/ui/layout/Center"
import { CollapsableStateIndicator } from "@lib/ui/layout/CollapsableStateIndicator"
import { IsActiveProp, ValueProp } from "@lib/ui/props"
import { Text } from "@lib/ui/text"
import { getColor, matchColor } from "@lib/ui/theme/getters"
import { without } from "@lib/utils/array/without"
import { songs } from "@product/core/songs"
import {
  GuitarTheoryTopic,
  guitarTheoryTopicNames,
} from "@product/core/songs/GuitarTheoryTopic"
import { getGuitarTheorySongId } from "@product/core/songs/Song"
import styled from "styled-components"

import { SongItemFrame } from "./SongItemFrame"
import { useCheckedSongs } from "./state/checkedSongs"
import { useExpandedSongTopics } from "./state/expandedSongTopics"

const CompletionIndicator = styled.div<IsActiveProp>`
  ${round}
  ${sameDimensions(10)}
  background: ${matchColor("isActive", {
    true: "success",
    false: "mistExtra",
  })};
`

const CollapseIndicator = styled(CollapsableStateIndicator)`
  font-size: 20px;
  color: ${getColor("textSupporting")};
`

const Container = styled(UnstyledButton)`
  ${hStack({
    fullWidth: true,
    alignItems: "center",
    justifyContent: "space-between",
    gap: 8,
  })}
  ${verticalPadding(8)}

  &:hover ${CollapseIndicator} {
    color: ${getColor("contrast")};
  }
`

export const SongsSectionHeader = ({ value }: ValueProp<GuitarTheoryTopic>) => {
  const items = songs[value]
  const [checkedSongs] = useCheckedSongs()

  const hasCheckedSong = checkedSongs.some((songId) =>
    items.some((song) => getGuitarTheorySongId(value, song) === songId),
  )

  const [expandedTopics, setExpandedTopics] = useExpandedSongTopics()

  const isExpanded = expandedTopics.includes(value)

  return (
    <Container
      onClick={() =>
        setExpandedTopics(
          isExpanded
            ? without(expandedTopics, value)
            : [...expandedTopics, value],
        )
      }
    >
      <SongItemFrame>
        <Center>
          <ClientOnly>
            <CompletionIndicator isActive={hasCheckedSong} />
          </ClientOnly>
        </Center>
        <Text color="contrast" as="h3" weight={700} size={18}>
          {guitarTheoryTopicNames[value]}
        </Text>
      </SongItemFrame>
      <ClientOnly>
        <CollapseIndicator isOpen={isExpanded} />
      </ClientOnly>
    </Container>
  )
}

Maintaining Visual Consistency with Grid Layout

To have header and song item content aligned, we implement a consistent grid layout with the SongItemFrame component. This ensures that both section headers and individual song items maintain visual uniformity throughout the interface.

import { toSizeUnit } from "@lib/ui/css/toSizeUnit"
import styled from "styled-components"

const boxSize = 28

export const SongItemFrame = styled.div`
  display: grid;
  gap: 16px;
  grid-template-columns: ${toSizeUnit(boxSize)} 1fr;
  line-height: ${toSizeUnit(boxSize)};
`

Building the Song Item Component

The SongItem component displays individual songs within each theory topic. It includes a checkbox for tracking learned songs and shows both the song name and artist. We utilize the CopyText component from RadzionKit to enhance usability—when clicked, it copies the full song information to the clipboard, allowing users to easily search for these songs on YouTube or elsewhere.

import { CheckStatus } from "@lib/ui/checklist/CheckStatus"
import { InvisibleHTMLCheckbox } from "@lib/ui/inputs/InvisibleHTMLCheckbox"
import { Text } from "@lib/ui/text"
import { CopyText } from "@lib/ui/text/CopyText"
import { without } from "@lib/utils/array/without"
import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"
import { GuitarTheoryTopic } from "@product/core/songs/GuitarTheoryTopic"
import { getGuitarTheorySongId, Song } from "@product/core/songs/Song"

import { SongItemFrame } from "./SongItemFrame"
import { useCheckedSongs } from "./state/checkedSongs"

type SongItemProps = {
  song: Song
  topic: GuitarTheoryTopic
}

export const SongItem = ({ song, topic }: SongItemProps) => {
  const [checkedSongs, setCheckedSongs] = useCheckedSongs()

  const songId = getGuitarTheorySongId(topic, song)

  const isChecked = checkedSongs.includes(songId)

  const songText = `"${song.name}" by ${song.artist}`

  return (
    <SongItemFrame>
      <CheckStatus as="label" isInteractive value={isChecked}>
        <InvisibleHTMLCheckbox
          value={isChecked}
          onChange={(value) =>
            setCheckedSongs((prev) =>
              value ? [...prev, songId] : without(prev, songId),
            )
          }
        />
      </CheckStatus>
      <Text>
        <CopyText content={songText}>
          <Text as="span" color="contrast">
            {songText}
          </Text>
        </CopyText>
        {song.details && (
          <Text color="supporting" style={{ marginLeft: 8 }} as="span">
            ({capitalizeFirstLetter(song.details)})
          </Text>
        )}
      </Text>
    </SongItemFrame>
  )
}

Generating Unique Song Identifiers

To ensure each song has a unique identifier within our application, we need a function that creates IDs in the context of guitar theory topics. Since each song appears only once per theory topic (even though the same song might appear in multiple topics), we can generate unique IDs by combining the topic name with the song's artist and title.

import { withoutUndefined } from "@lib/utils/array/withoutUndefined"

import { GuitarTheoryTopic } from "./GuitarTheoryTopic"

export type Song = {
  name: string
  artist: string
  details?: string
}

export const getGuitarTheorySongId = (
  topic: GuitarTheoryTopic,
  { artist, name }: Pick<Song, "artist" | "name">,
) =>
  withoutUndefined([topic, artist, name])
    .map((s) => s.toLowerCase().replace(/ /g, "-"))
    .join("-")

With this songs page implementation, we've bridged the gap between abstract guitar theory and practical application, allowing guitarists to track their progress while discovering songs that reinforce specific concepts they're learning—transforming theoretical knowledge into musical fluency through deliberate practice.

Finding Hidden Comic Book Deals: A TypeScript Scraping Solution

Radzion Chachura — Sun, 04 May 2025 10:32:54 +0000

🐙 GitHub

The Value Challenge in Comic Book Collecting

Comic book collectors face a common challenge: getting the best value for their money. While the cover price is straightforward, the actual value can vary significantly when you consider the number of pages in each volume. A $20 comic might contain 100 pages, while another at the same price point offers 400 pages. To solve this practical problem, we'll develop a TypeScript program that calculates and compares the price per page, helping collectors make data-driven purchasing decisions. The complete source code for this project is available on GitHub.

Using this approach, I bought four 400-plus-page comics for $85 total, including shipping costs. The implementation focuses on the Wildberries e-commerce platform, which serves Eastern European markets. The code structure is modular, allowing for easy adaptation to other online retailers by modifying the web scraping functions.

Defining the Data Model

Our data model represents each comic book with a TypeScript interface containing four essential properties: name, price, number of pages, and product URL. The getBookPagePrice function uses this structure to calculate the cost per page, our key metric for comparison.

export type Book = {
  name: string
  price: number
  numberOfPages: number
  url: string
}

export const getBookPagePrice = ({
  price,
  numberOfPages,
}: Pick<Book, "price" | "numberOfPages">): number => {
  return price / numberOfPages
}

export const printBook = (book: Book) => {
  return [
    `Name: ${book.name}`,
    `Price: ${book.price}`,
    `Number of pages: ${book.numberOfPages}`,
    `Price per page: ${getBookPagePrice(book).toFixed(2)}`,
    `URL: ${book.url}`,
  ].join("\n")
}

Managing Browser Lifecycle

For web scraping with Puppeteer, we'll create a withBrowser helper function that handles browser lifecycle. Our main findBooks function will receive a browser instance from it and focus on the scraping logic, while withBrowser takes care of proper browser cleanup.

import { Browser, launch } from "puppeteer"

type WithBrowserFn<T> = (browser: Browser) => Promise<T>

export const withBrowser = async <T>(fn: WithBrowserFn<T>) => {
  const browser = await launch({
    headless: true,
    args: ["--no-sandbox", "--disable-setuid-sandbox"],
  })

  try {
    return await fn(browser)
  } finally {
    await browser.close()
  }
}

Page Lifecycle Management

To handle browser page lifecycle management, we'll implement a higher-order function that encapsulates page creation and cleanup. The makeWithPage function takes a URL and browser instance as input, returning a function that manages the page's lifecycle. This pattern ensures proper resource cleanup and standardizes page configuration across our scraping operations.

import { Page, Browser } from "puppeteer"

type WithPageFn<T> = (browser: Page) => Promise<T>

type MakeWithPageInput = {
  url: string
  browser: Browser
}

export const makeWithPage = ({ url, browser }: MakeWithPageInput) => {
  const withPage = async <T>(fn: WithPageFn<T>) => {
    const page = await browser.newPage()
    await page.setViewport({ width: 1280, height: 800 })
    await page.setUserAgent(
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
    )
    await page.goto(url, { waitUntil: "networkidle2" })

    try {
      return await fn(page)
    } finally {
      await page.close()
    }
  }

  return withPage
}

Scraping Search Results

To extract product links from the search results page, we need to handle infinite scroll pagination and wait for all products to load. While Wildberries does provide pagination controls, we intentionally focus only on the first page since it contains the most relevant results sorted by popularity. The scrapeSearchPage function implements this by recursively scrolling to the bottom of the first page until no new products appear. Once all products are loaded, it extracts the URLs using DOM selectors. This approach ensures we capture the most relevant comic books from the search results before proceeding with individual product page scraping.

import { sleep } from "@lib/utils/sleep"
import { Page } from "puppeteer"

const productLinkSelector = ".product-card-list .product-card__link"

export async function scrapeSearchPage(page: Page): Promise<string[]> {
  console.log(`Scraping search page: ${page.url()}`)

  const recursiveScroll = async (pageCounts: number[]) => {
    const currentProductCount = await page.evaluate(
      (selector) => document.querySelectorAll(selector).length,
      productLinkSelector,
    )

    if (pageCounts.find((count) => count === currentProductCount)) {
      return
    }

    await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))
    await sleep(1000)

    await recursiveScroll([...pageCounts, currentProductCount])
  }

  await recursiveScroll([])

  const bookLinks = await page.evaluate((selector) => {
    return Array.from(document.querySelectorAll(selector))
      .map((link) => link.getAttribute("href"))
      .filter((href): href is string => href !== null)
  }, productLinkSelector)

  if (bookLinks.length === 0) {
    throw new Error(`No books found on ${page.url()}`)
  }

  console.log(`Found ${bookLinks.length} books on ${page.url()}`)
  return bookLinks
}

Extracting Comic Book Details

With the product links collected, we now need to visit each page and extract the comic book details. The scrapeBookPage function navigates the DOM to find the title, price, and page count for each comic. It uses Puppeteer's evaluation methods to extract text from specific selectors and includes error handling to maintain data integrity. The price extraction handles the formatting challenges of converting display text to numerical values. For finding the page count, the function scans all page elements for text containing "страниц" (pages in Russian) and uses regex to extract the number.

import { attempt } from "@lib/utils/attempt"
import { Page } from "puppeteer"

const headerSelector = ".product-page__header h1"

export async function scrapeBookPage(page: Page) {
  const header = await attempt(
    page.waitForSelector(headerSelector, { timeout: 5000 }),
  )

  if ("error" in header) {
    throw new Error(`Product header not found for ${page.url()}`)
  }

  const productName = await page.$eval(
    headerSelector,
    (el: Element) => el.textContent?.trim() || "",
  )
  if (!productName) {
    throw new Error(`Could not extract product name for ${page.url()}`)
  }

  const priceText = await page.$eval(
    ".price-block__final-price",
    (el: Element) => el.textContent?.trim() || "",
  )
  const priceMatch = priceText.match(/[\d\s,.]+/)
  const price = priceMatch
    ? parseFloat(priceMatch[0].replace(/\s+/g, "").replace(",", "."))
    : 0

  if (price === 0) {
    throw new Error(`Could not extract valid price for ${page.url()}`)
  }

  const numberOfPages = await page.evaluate(() => {
    for (const element of document.querySelectorAll("*")) {
      const text = element.textContent?.trim() || ""
      if (text.includes("страниц")) {
        const pagesMatch = text.match(/(\d+)\s*страниц/)
        if (pagesMatch && pagesMatch[1]) {
          return parseInt(pagesMatch[1], 10)
        }
      }
    }
  })

  if (!numberOfPages) {
    throw new Error(`Could not find page count for ${page.url()}`)
  }

  return {
    name: productName,
    price,
    numberOfPages,
    url: page.url(),
  }
}

Orchestrating the Scraping Process

Now let's build the main function that orchestrates our entire scraping operation. The code below connects all components into a complete workflow: it constructs search URLs with price filters, extracts product links from search results, processes these URLs in batches to prevent memory issues, and finally sorts comics by price per page. The implementation handles errors at each step, ensuring the program continues even when individual requests fail. By processing multiple search queries for different comic series and using a batched approach, we avoid rate limiting while efficiently gathering data from numerous product pages.

import { order } from "@lib/utils/array/order"
import { toBatches } from "@lib/utils/array/toBatches"
import { withoutDuplicates } from "@lib/utils/array/withoutDuplicates"
import { withoutUndefined } from "@lib/utils/array/withoutUndefined"
import { attempt } from "@lib/utils/attempt"
import { getErrorMessage } from "@lib/utils/getErrorMessage"
import { chainPromises } from "@lib/utils/promise/chainPromises"
import { addQueryParams } from "@lib/utils/query/addQueryParams"
import { Browser } from "puppeteer"

import { getBookPagePrice, printBook } from "./Book"
import { makeWithPage } from "./scrape/makeWithPage"
import { scrapeBookPage } from "./scrape/scrapeBookPage"
import { scrapeSearchPage } from "./scrape/scrapeSearchPage"
import { withBrowser } from "./scrape/withBrowser"

const searchStrings = [
  "бэтмен комиксы",
  "люди икс комиксы",
  "сорвиголова комиксы",
  "капитан америка комиксы",
  "дэдпул комиксы",
]

const maxResultsToDisplay = 20
const batchSize = 5

const minPrice = 40
const maxPrice = 100

const findBooks = async (browser: Browser) => {
  const searchUrls = searchStrings.map((searchString) =>
    addQueryParams(`https://www.wildberries.ru/catalog/0/search.aspx`, {
      page: 1,
      sort: "popular",
      search: encodeURIComponent(searchString),
      priceU: [minPrice, maxPrice].map((v) => v * 100).join(";"),
      foriginal: "1",
    }),
  )

  const bookUrls = withoutDuplicates(
    (
      await chainPromises(
        searchUrls.map((url) => async () => {
          const result = await attempt(
            makeWithPage({ url, browser })(scrapeSearchPage),
          )

          if ("error" in result) {
            console.error(getErrorMessage(result.error))
            return []
          }

          return result.data
        }),
      )
    ).flat(),
  )

  console.log(`Found ${bookUrls.length} books total`)

  const batches = toBatches(bookUrls, batchSize)

  const books = withoutUndefined(
    (
      await chainPromises(
        batches.map((batch, index) => () => {
          console.log(`Scraping batch #${index + 1} of ${batches.length}`)
          return Promise.all(
            batch.map(async (url) => {
              const result = await attempt(
                makeWithPage({ url, browser })(scrapeBookPage),
              )

              if ("error" in result) {
                console.error(getErrorMessage(result.error))
                return
              }

              return result.data
            }),
          )
        }),
      )
    )
      .flat()
      .flat(),
  )

  const sortedBooks = order(books, getBookPagePrice, "asc").slice(
    0,
    maxResultsToDisplay,
  )

  console.log("Top Deals:")
  sortedBooks.forEach((book, index) => {
    console.log(`${index + 1}. ${printBook(book)}`)
    console.log("---")
  })
}

withBrowser(findBooks).catch(console.error)

Conclusion

This practical approach to comic book shopping demonstrates how a simple TypeScript application can transform raw data into actionable insights, helping collectors maximize value while building their collections.

Implementing Arpeggios in the CAGED System for Guitar

Radzion Chachura — Mon, 28 Apr 2025 03:32:14 +0000

🐙 GitHub | 🎮 Demo

This is the fifth post in our series building a React guitar theory app. So far, we've created a fretboard with various scales and implemented the CAGED system's five basic open chords. Now we're adding arpeggios to our CAGED page—a natural progression since arpeggios break down chords into individual notes played sequentially, helping guitarists understand chord construction while developing technique for melodic playing. You can find all the source code in the GitHub repository.

Creating Type-Safe View Options

To implement switching between chord and arpeggio views, we'll define a type-safe union of the two views using TypeScript:

export const cagedViews = ["chord", "arpeggio"] as const

export type CagedView = (typeof cagedViews)[number]

Implementing Dynamic Routes

Next, we'll leverage Next.js dynamic routes to create our CAGED page with switchable views. This pattern generates separate static pages for chord and arpeggio views at build time, improving performance. We'll use getStaticPaths to generate routes from our cagedViews array, while GetStaticProps passes the current view to our CagedPage component, enabling view-specific rendering.

import { GetStaticPaths, GetStaticProps } from "next"
import { CagedPage } from "../../../caged/CagedPage"
import { cagedViews } from "@product/core/chords/caged"
import { CagedState } from "../../../caged/state/caged"

export default CagedPage

export const getStaticPaths: GetStaticPaths<CagedState> = async () => {
  const paths = cagedViews.map((view) => ({
    params: {
      view,
    },
  }))

  return {
    paths,
    fallback: false,
  }
}

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const { view } = params as CagedState

  return {
    props: {
      value: {
        view,
      },
    },
  }
}

Managing State with React Context

To manage state for our CAGED component, we'll implement a React context for tracking the current view. The getValueProviderSetup utility from RadzionKit is a small helper that simplifies creating single value providers by handling the context creation, provider component, and hook generation in one concise function. The resulting CagedProvider wraps our page component to make the selected view available to all children without prop drilling. Additionally, we create two utilities: makeCagedPath generates URL paths based on state, while useChangeCaged provides a convenient hook for navigating between views by updating the URL.

import { getValueProviderSetup } from "@lib/ui/state/getValueProviderSetup"
import { useRouter } from "next/router"
import { useCallback } from "react"
import { CagedView } from "@product/core/chords/caged"

export type CagedState = {
  view: CagedView
}

export const makeCagedPath = ({ view }: CagedState) => `/caged/${view}`

export const { useValue: useCaged, provider: CagedProvider } =
  getValueProviderSetup<CagedState>("Caged")

export const useChangeCaged = () => {
  const value = useCaged()
  const { push } = useRouter()

  return useCallback(
    (params: Partial<CagedState>) => {
      push(makeCagedPath({ ...value, ...params }))
    },
    [push, value],
  )
}

Structuring the CAGED Page Component

Our page structure uses a CagedProvider to wrap the entire CAGED page, creating a shared context for view state. The page layout consists of three main components: a ManageCagedView component for switching between chord and arpeggio views, a CagedPageTitle, and a responsive grid of CagedItem components displayed in a horizontally stacked layout.

import { HStack, VStack } from "@lib/ui/css/stack"
import { PageContainer } from "../layout/PageContainer"
import { CagedPageTitle } from "./CagedPageTitle"
import { cagedChords } from "@product/core/chords/caged"
import { CagedProvider, CagedState } from "./state/caged"
import { ValueProp } from "@lib/ui/props"
import { CagedItem } from "./CagedItem"
import { ManageCagedView } from "./manage/ManageCagedView"

export const CagedPage = ({ value }: ValueProp<CagedState>) => (
  <CagedProvider value={value}>
    <PageContainer>
      <VStack gap={60}>
        <VStack alignItems="center">
          <ManageCagedView />
        </VStack>
        <CagedPageTitle />
        <HStack
          fullWidth
          gap={60}
          alignItems="center"
          justifyContent="center"
          wrap="wrap"
        >
          {cagedChords.map((chord) => (
            <CagedItem key={chord} value={chord} />
          ))}
        </HStack>
      </VStack>
    </PageContainer>
  </CagedProvider>
)

Creating a View Switcher Component

For our view switching interface, we implement a ManageCagedView component that leverages the GroupedRadioInput component from RadzionKit to create an intuitive toggle between chord and arpeggio views.

import { GroupedRadioInput } from "@lib/ui/inputs/GroupedRadioInput"
import { useChangeCaged, useCaged } from "../state/caged"
import { cagedViews } from "@product/core/chords/caged"
import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"

export const ManageCagedView = () => {
  const { view } = useCaged()
  const setValue = useChangeCaged()

  return (
    <GroupedRadioInput
      value={view}
      onChange={(view) => setValue({ view })}
      options={cagedViews}
      renderOption={(view) => `${capitalizeFirstLetter(view)}s`}
    />
  )
}

Enhancing SEO with Dynamic Page Titles

To ensure consistent SEO across our application, we'll create a CagedPageTitle component that dynamically generates page titles and descriptions based on the current view. This component pulls the view state from our context, capitalizes the view name, and uses the match utility for view-specific description text.

import { VStack } from "@lib/ui/css/stack"
import { useCaged } from "./state/caged"
import { PageMetaTags } from "@lib/next-ui/metadata/PageMetaTags"
import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"
import { match } from "@lib/utils/match"
import { PageTitle } from "../ui/PageTitle"

export const CagedPageTitle = () => {
  const { view } = useCaged()
  const viewTitle = `${capitalizeFirstLetter(view)}s`
  const title = `CAGED ${viewTitle} System for Guitar | Master Fretboard Positions`
  const description = `Interactive guide to the CAGED ${viewTitle.toLowerCase()} system for guitarists. Learn C, A, G, E, D ${match(
    view,
    {
      chord: () => "chord shapes",
      arpeggio: () => "arpeggio patterns",
    },
  )} to navigate the entire fretboard and improve your playing.`

  return (
    <VStack>
      <PageMetaTags title={title} description={description} />
      <PageTitle>CAGED {viewTitle}</PageTitle>
    </VStack>
  )
}

Defining CAGED Chord Types

To render each chord or arpeggio shape, we map through the cagedChords array, rendering a CagedItem component for each chord position.

export const cagedChords = ["c", "a", "g", "e", "d"] as const

export type CagedChord = (typeof cagedChords)[number]

Representing Notes on the Fretboard

export type NotePosition = {
  // 0-based index of the string
  string: number
  // -1 if the note is open
  // 0 if the note is on the 1st fret
  fret: number
}

Mapping Chord and Arpeggio Patterns

We'll use the openCagedChords and cagedArpeggios objects to store the note positions for each chord and arpeggio shape. The C and G arpeggios can be played in the same position as their corresponding open chords, maintaining their familiar low-position fingerings. However, the A, E, and D arpeggios contain notes that would extend beyond the guitar's physical limitations if played in open position. To address this, we shift these arpeggios one octave higher (same notes, but 12 frets higher in pitch), placing them around the 11th-13th frets where all notes can be comfortably reached within a single hand position.

export const openCagedChords: Record<CagedChord, NotePosition[]> = {
  c: [
    { string: 0, fret: -1 },
    { string: 1, fret: 0 },
    { string: 2, fret: -1 },
    { string: 3, fret: 1 },
    { string: 4, fret: 2 },
  ],
  a: [
    { string: 0, fret: -1 },
    { string: 1, fret: 1 },
    { string: 2, fret: 1 },
    { string: 3, fret: 1 },
    { string: 4, fret: -1 },
  ],
  g: [
    { string: 0, fret: 2 },
    { string: 1, fret: -1 },
    { string: 2, fret: -1 },
    { string: 3, fret: -1 },
    { string: 4, fret: 1 },
    { string: 5, fret: 2 },
  ],
  e: [
    { string: 0, fret: -1 },
    { string: 1, fret: -1 },
    { string: 2, fret: 0 },
    { string: 3, fret: 1 },
    { string: 4, fret: 1 },
    { string: 5, fret: -1 },
  ],
  d: [
    { string: 0, fret: 1 },
    { string: 1, fret: 2 },
    { string: 2, fret: 1 },
    { string: 3, fret: -1 },
  ],
}

export const cagedArpeggios: Record<CagedChord, NotePosition[]> = {
  c: [
    { string: 0, fret: -1 },
    { string: 0, fret: 2 },
    { string: 1, fret: 0 },
    { string: 2, fret: -1 },
    { string: 3, fret: 1 },
    { string: 4, fret: 2 },
    { string: 5, fret: -1 },
    { string: 5, fret: 2 },
  ],
  a: [
    { string: 0, fret: 11 },
    { string: 1, fret: 13 },
    { string: 2, fret: 13 },
    { string: 3, fret: 10 },
    { string: 3, fret: 13 },
    { string: 4, fret: 11 },
    { string: 5, fret: 11 },
  ],
  g: [
    { string: 0, fret: 2 },
    { string: 1, fret: -1 },
    { string: 1, fret: 2 },
    { string: 2, fret: -1 },
    { string: 3, fret: -1 },
    { string: 4, fret: 1 },
    { string: 5, fret: 2 },
  ],
  e: [
    { string: 0, fret: 11 },
    { string: 1, fret: 11 },
    { string: 2, fret: 12 },
    { string: 3, fret: 13 },
    { string: 4, fret: 13 },
    { string: 4, fret: 10 },
    { string: 5, fret: 11 },
  ],
  d: [
    { string: 0, fret: 13 },
    { string: 1, fret: 14 },
    { string: 2, fret: 13 },
    { string: 2, fret: 10 },
    { string: 3, fret: 11 },
    { string: 4, fret: 11 },
    { string: 5, fret: 13 },
  ],
}

Rendering Chord and Arpeggio Shapes

Now let's examine how the CagedItem component renders each chord or arpeggio shape with proper highlighting of the root note. For better visual identification, we need to distinguish the root note from other chord tones. The component calculates the lowestBassString by filtering all positions to find notes that match the chord's root note value, then determining which of these is on the lowest bass string (highest string number in our zero-based index). This root note is then rendered with the "primary" styling to provide consistent visual anchoring across both chord and arpeggio shapes.

The actual rendering of notes on the fretboard uses our custom Fretboard and Note components, which handle the visual representation of string positions, fret markers, and note indicators. The component also intelligently calculates the visible fret range to ensure all notes are displayed clearly, with a minimum of 4 frets shown. For a deeper understanding of how these fretboard visualization components work, refer to the first post in this series where we established the foundational rendering system.

import { ValueProp } from "@lib/ui/props"
import {
  cagedArpeggios,
  CagedChord,
  openCagedChords,
} from "@product/core/chords/caged"
import { vStack } from "@lib/ui/css/stack"
import { Text } from "@lib/ui/text"
import { Fretboard } from "../guitar/fretboard/Fretboard"
import { Note } from "../guitar/fretboard/Note"
import styled from "styled-components"
import { useCaged } from "./state/caged"
import { getNoteFromPosition } from "@product/core/note/getNoteFromPosition"
import { tuning } from "../guitar/config"
import { chromaticNotesNames } from "@product/core/note"

const Container = styled.div`
  ${vStack({
    gap: 40,
  })}

  min-width: 320px;
  max-width: 400px;
`

const positionsRecord = {
  chord: openCagedChords,
  arpeggio: cagedArpeggios,
}

const minVisibleFrets = 4

export const CagedItem = ({ value }: ValueProp<CagedChord>) => {
  const { view } = useCaged()
  const positions = positionsRecord[view][value]

  const lowestBassString = Math.max(
    ...positions
      .filter(
        (position) =>
          getNoteFromPosition({ tuning, position }) ===
          chromaticNotesNames.indexOf(value.toUpperCase()),
      )
      .map((position) => position.string),
  )

  const firstVisibleFret = Math.min(
    ...positions.map((position) => position.fret),
  )

  return (
    <Container>
      <Text centerHorizontally color="contrast" as="h3" weight="700" size={18}>
        {value.toUpperCase()} major {view}
      </Text>
      <Fretboard
        visibleFrets={{
          start: firstVisibleFret,
          end: Math.max(
            ...positions.map((position) => position.fret),
            firstVisibleFret + minVisibleFrets,
          ),
        }}
      >
        {positions.map((position) => (
          <Note
            key={`${position.string}-${position.fret}`}
            string={position.string}
            fret={position.fret}
            kind={position.string === lowestBassString ? "primary" : "regular"}
          />
        ))}
      </Fretboard>
    </Container>
  )
}

Conclusion

With both chord shapes and arpeggios implemented in our CAGED system, guitarists can now switch between viewing full chord voicings and their broken-down note patterns. This provides a comprehensive learning tool that helps players understand chord construction while developing the technical facility to incorporate these patterns into their solos and improvisation.

Simplify TypeScript Error Handling with the Attempt Pattern

Radzion Chachura — Mon, 21 Apr 2025 04:30:46 +0000

🐙 GitHub

Say goodbye to verbose try-catch blocks in TypeScript! In this article, I'll introduce you to the attempt function—a cleaner, more functional approach to error handling that has transformed how I write defensive code. This simple yet powerful utility encapsulates the try-catch pattern into a reusable function that improves both readability and maintainability. You can find the complete implementation in my open-source [RadzionKit](https://github.com/radzionc/radzionkit) repository.

The Problem with Traditional Error Handling

Traditional try-catch blocks often lead to cluttered, difficult-to-follow code. They force error handling to the end of execution flow, which can be counterintuitive when you want to handle errors first. Sometimes you simply need a fallback value if an operation fails, without complex error handling logic. Languages like Go implement this pattern as a core feature, returning both a result and an error that can be checked immediately. The attempt function brings this cleaner approach to TypeScript, allowing for more concise code that separates the happy path from error handling in a structured, readable way.

Defining the Result Type

export type Success<T> = { data: T; error?: never }
export type Failure<E = unknown> = { data?: never; error: E }
export type Result<T, E = unknown> = Success<T> | Failure<E>

Our attempt function will return a Result type, which can be either a Success or a Failure. This discriminated union leverages TypeScript's type narrowing capabilities to provide type safety throughout your error handling flow. When you check for the presence of an error property, TypeScript automatically narrows the type, ensuring that in the error case, data is unavailable, while in the success case, data is guaranteed to be present and properly typed—not T | undefined, but exactly T. This eliminates the need for additional null checks or non-null assertions that often plague traditional error handling approaches.

Type Safety in Action

const result = await attempt(fetchUserData())

if ("error" in result) {
  console.log("Error occurred:", result.error)
  // TypeScript knows result is Failure here
  // result.data is not accessible
  return
}

// TypeScript has narrowed the type to Success<User>
// We can safely access data without optional chaining or type assertions
const user = result.data
console.log("User name:", user.name) // No TypeScript errors!

Function Overloads for Maximum Flexibility

The attempt function's versatility comes from its three function overloads, each designed to handle a different common scenario in modern TypeScript applications. The first overload accepts a function that returns a Promise, perfect for wrapping asynchronous operations like API calls or database queries. The second handles synchronous functions that might throw exceptions, such as parsing JSON or accessing potentially undefined properties. The third overload accepts a Promise directly, allowing you to wrap already-created Promises without defining an additional function. This flexibility means you can use the same consistent error-handling pattern regardless of whether you're working with synchronous or asynchronous code, making your codebase more uniform and predictable.

export function attempt<T, E = unknown>(
  fn: () => Promise<T>,
): Promise<Result<T, E>>

export function attempt<T, E = unknown>(fn: () => T): Result<T, E>

export function attempt<T, E = unknown>(
  promise: Promise<T>,
): Promise<Result<T, E>>

Implementation Details

The implementation of attempt handles all three overloads with a single function body. It first checks if the input is a function using a type guard. If it is, it executes the function within a try-catch block, capturing any synchronous exceptions. If the function returns a Promise, it recursively calls attempt on that Promise to handle asynchronous errors. For direct Promise inputs, it attaches .then() and catch handlers that transform the resolved value or rejection reason into our Result type. This unified approach ensures consistent error handling regardless of whether you're working with synchronous functions, asynchronous functions, or raw Promises, all while maintaining proper type information throughout.

export function attempt<T, E = unknown>(
  input: Promise<T> | (() => T) | (() => Promise<T>),
): Result<T, E> | Promise<Result<T, E>> {
  if (typeof input === "function") {
    try {
      const result = input()
      if (isPromise<T>(result)) {
        return attempt(result)
      }
      return { data: result } as Result<T, E>
    } catch (error) {
      return { error: error as E }
    }
  } else {
    return input.then(
      (data): Result<T, E> => ({ data }),
      (error): Result<T, E> => ({ error: error as E }),
    )
  }
}

Helper Functions

To support this implementation, we need a helper function that can reliably detect if a value is a Promise. The isPromise utility checks if a value has a then method, which is the defining characteristic of a Promise-like object.

export function isPromise<T>(value: unknown): value is Promise<T> {
  return !!value && typeof (value as any).then === "function"
}

Handling Fallbacks Elegantly

While the attempt function provides a structured way to handle errors, you'll often want to extract the successful data or use a default value when an operation fails—all in a single line of code. The withFallback utility is specifically designed to work with the Result type returned by attempt, creating a powerful composition pattern. It takes a Result object (or a Promise that resolves to one) and a fallback value, then either extracts the successful data or substitutes the fallback when an error occurs. This pattern is particularly useful for operations like parsing JSON where you want to provide a sensible default when parsing fails:

// Parse JSON with a fallback to the original value if parsing fails
const parsedConfig = withFallback(
  attempt(() => JSON.parse(value) as T),
  value as T,
)

The withFallback Implementation

Like attempt, withFallback handles both synchronous and asynchronous results through function overloads, maintaining the same functional approach to error handling throughout your codebase.

export function withFallback<T, E = unknown>(
  result: Result<T, E>,
  fallback: T,
): T
export function withFallback<T, E = unknown>(
  result: Promise<Result<T, E>>,
  fallback: T,
): Promise<T>
export function withFallback<T, E = unknown>(
  result: Result<T, E> | Promise<Result<T, E>>,
  fallback: T,
): T | Promise<T> {
  if (isPromise<Result<T, E>>(result)) {
    return result.then((res): T => {
      if ("error" in res) {
        return fallback
      }
      return res.data
    })
  }

  if ("error" in result) {
    return fallback
  }

  return result.data
}

I hope this video convinced you that the attempt and withFallback utilities are a powerful and flexible way to handle errors in TypeScript. We don't need to convince AI, let's just add a cursor rule so that AI will also always use attempt instead of try-catch.

Conclusion

The attempt pattern transforms error handling from a verbose, nested structure into a clean, functional flow that improves code readability and maintainability. By returning strongly-typed Result objects, it leverages TypeScript's type system to ensure errors are handled consistently throughout your application. I've found this approach so valuable that I've integrated it as a Cursor rule in my development workflow—ensuring that all error handling follows this pattern instead of traditional try-catch blocks.

---
description: "USE attempt utility WHEN handling errors INSTEAD OF try-catch blocks TO ensure consistent error handling"
globs: *.{ts,tsx,js,jsx}
alwaysApply: false
---

# Use attempt Utility Instead of try-catch

## Context

- Applies when handling errors in asynchronous or synchronous operations
- The codebase provides a utility function `attempt` in `lib/utils/attempt.ts`
- This utility provides a consistent way to handle errors with Result types

## Requirements

- Always use the `attempt` utility instead of try-catch blocks
- Return and handle Result objects with `data` and `error` properties
- Use `withFallback` when a default value is needed in case of error

## Examples

<example>
// Good: Using attempt utility for error handling
import { attempt } from '@lib/utils/attempt'

// For synchronous functions
const result = attempt(() => parseJSON(data))
if ('data' in result) {
// Handle success case
processData(result.data)
} else {
// Handle error case
logError(result.error)
}

// For asynchronous functions
const result = await attempt(() => fetchData())
if ('data' in result) {
// Handle success case
processData(result.data)
} else {
// Handle error case
logError(result.error)
}

// Using withFallback for default values
const data = withFallback(attempt(() => parseJSON(data)), defaultValue)
</example>

<example type="invalid">
// Bad: Using try-catch directly
try {
  const data = parseJSON(data)
  processData(data)
} catch (error) {
  logError(error)
}

// Bad: Using try-catch with async/await
try {
const data = await fetchData()
processData(data)
} catch (error) {
logError(error)
}
</example>

Building a Real-time EVM Gas Fee Calculator with React and Wagmi

Radzion Chachura — Mon, 14 Apr 2025 02:12:44 +0000

🐙 GitHub | 🎮 Demo

When making a transaction on an EVM chain such as Ethereum, you need to specify three key parameters: gas limit, max fee per gas, and max priority fee per gas. These parameters are crucial for determining transaction costs and priority. In this post, we'll explore how to efficiently calculate these values using Viem and Wagmi libraries. You can experiment with the live demo here, and review the complete source code here.

Building the Fee Calculator Interface

Let's explore a practical implementation of gas fee calculation by building a simple web page. We'll create a user interface that displays different components of the gas fee and analyze the code step by step to understand the underlying mechanics.

import { PageMetaTags } from "@lib/next-ui/metadata/PageMetaTags"
import styled from "styled-components"
import { centeredContentColumn } from "@lib/ui/css/centeredContentColumn"
import { verticalPadding } from "@lib/ui/css/verticalPadding"
import { WebsiteNavigation } from "@lib/ui/website/navigation/WebsiteNavigation"
import { ProductLogo } from "../product/ProductLogo"
import { VStack } from "@lib/ui/css/stack"
import { MaxPriorityFeePerGas } from "./maxPriorityFeePerGas/MaxPriorityFeePerGas"
import { MaxFeePerGas } from "./maxFeePerGas/MaxFeePerGas"
import { BaseFee } from "./baseFee/BaseFee"
import { MaxFee } from "./maxFee/MaxFee"

export const PageContainer = styled.div`
  ${centeredContentColumn({
    contentMaxWidth: 520,
  })}

  ${verticalPadding(80)}
`

export const FeePage = () => (
  <>
    <PageMetaTags
      title="EVM Gas Fee Calculator | Real-time Gas Price Monitoring"
      description="Monitor real-time Ethereum gas fees, including max priority fees, base fees, and max fees per gas. Get accurate estimates for your EVM transactions."
    />

    <WebsiteNavigation logo={<ProductLogo />}>
      <PageContainer>
        <VStack gap={40}>
          <MaxFee />
          <MaxPriorityFeePerGas />
          <MaxFeePerGas />
          <BaseFee />
        </VStack>
      </PageContainer>
    </WebsiteNavigation>
  </>
)

Understanding Priority Fees

Since the MaxFee component combines all fee components into a final value, we'll examine it last. Let's start by understanding the maxPriorityFeePerGas parameter, which is a crucial part of the overall transaction fee structure.

import { VStack } from "@lib/ui/css/stack"
import { PriorityOptions } from "./options/PriorityOptions"
import { FeeSection } from "../FeeSection"
import { MaxPriorityFeePerGasTitle } from "./MaxPriorityFeePerGasTitle"
import { FeeChart } from "./chart/FeeChart"

export const MaxPriorityFeePerGas = () => {
  return (
    <FeeSection title={<MaxPriorityFeePerGasTitle />}>
      <VStack gap={40}>
        <PriorityOptions />
        <FeeChart />
      </VStack>
    </FeeSection>
  )
}

Priority Fee Levels

MaxPriorityFeePerGas, often referred to as the "priority fee," is the extra tip users include in their transactions to incentivize miners to process them faster. Unlike the base fee—which is determined by the network to reflect current demand—the maxPriorityFeePerGas is set by the user to ensure quicker transaction confirmations, especially during periods of high congestion.

In most Web3 applications, when initiating a transaction, users are presented with priority options for their transaction fees. This feature allows users to strategically choose between lower fees for non-urgent transactions and higher fees when faster confirmation is needed. The priority selection directly influences the maxPriorityFeePerGas parameter, giving users control over their transaction costs and confirmation speed.

export const feePriorities = ["low", "medium", "high"] as const

export type FeePriority = (typeof feePriorities)[number]

export const feePriorityPercentiles: Record<FeePriority, number> = {
  low: 10,
  medium: 50,
  high: 90,
}

export const defaultFeePriority = "medium" as const

Historical Fee Analysis

To determine the maxPriorityFeePerGas value, we analyze the historical priority fees paid by users in the last 10 blocks. This approach gives us a reliable estimate based on recent network activity. We fetch this data using Wagmi's useFeeHistory hook, which retrieves fee information for different priority levels (low, medium, high). Each priority level corresponds to a specific percentile of fees paid - 10th percentile for low priority, 50th for medium, and 90th for high. This statistical approach ensures our estimates reflect the actual market conditions for transaction inclusion.

import { feePriorityPercentiles } from "../maxPriorityFeePerGas/core/FeePriority"

import { useFeeHistory } from "wagmi"
import { feePriorities } from "../maxPriorityFeePerGas/core/FeePriority"
import { useTransformQueryData } from "@lib/ui/query/hooks/useTransformQueryData"
import { GetFeeHistoryReturnType } from "viem"
import { shouldBePresent } from "@lib/utils/assert/shouldBePresent"
import { arraysToRecord } from "@lib/utils/array/arraysToRecord"

export type PriorityFeeTimeseries = Record<
  (typeof feePriorities)[number],
  bigint[]
>

const transform = ({
  reward,
}: GetFeeHistoryReturnType): PriorityFeeTimeseries =>
  arraysToRecord(
    feePriorities,
    shouldBePresent(reward).reduce(
      (acc, curr) => {
        return acc.map((value, index) => [...value, curr[index]])
      },
      feePriorities.map(() => [] as bigint[]),
    ),
  )

export const usePriorityFeeTimeseriesQuery = () => {
  const query = useFeeHistory({
    blockCount: 10,
    rewardPercentiles: feePriorities.map((key) => feePriorityPercentiles[key]),
  })

  return useTransformQueryData(query, transform)
}

The Wagmi hook returns a nested array structure representing fee history data. Each inner array corresponds to a specific priority level (low, medium, high). To make this data more accessible and type-safe, we transform it into a structured record. The resulting format is a Record where each key is a priority level (e.g., "low", "medium", "high") and the corresponding value is an array of bigint values. This array contains the historical priority fees for that level, making it easier to analyze trends and calculate estimates for each priority tier.

To handle the transformation of query results efficiently and safely, we've created a custom hook called useTransformQueryData. This hook is designed to transform raw query data into a more useful format while preserving the query's error handling capabilities. It's particularly useful when working with complex data structures like our fee history, where we need to reshape the data without losing the original query's metadata. The hook uses React's useMemo to optimize performance by memoizing the transformed result:

import { useMemo } from "react"
import { Query } from "../Query"

type QueryBase<T> = Pick<Query<T>, "data" | "error">

export const useTransformQueryData = <
  TInput,
  TOutput,
  TExtra extends object = {},
>(
  queryResult: QueryBase<TInput> & TExtra,
  transform: (data: TInput) => TOutput,
): QueryBase<TOutput> & Omit<TExtra, keyof QueryBase<TOutput>> => {
  return useMemo(() => {
    try {
      return {
        ...queryResult,
        data:
          queryResult.data !== undefined
            ? transform(queryResult.data)
            : undefined,
      }
    } catch (error) {
      return {
        ...queryResult,
        data: undefined,
        error,
      }
    }
  }, [queryResult, transform])
}

To display both historical and current priority fees, we need two data transformations. First, we use the hook to transform the raw fee history into a chart-friendly format. Second, to show the current fee for each priority level, we calculate the average of the historical values. This is accomplished by applying useTransformQueryData again, this time using recordMap to compute averages across each priority level's time series data. This dual transformation approach gives us both the temporal view needed for the chart and the current snapshot needed for immediate fee estimates.

import { recordMap } from "@lib/utils/record/recordMap"
import {
  PriorityFeeTimeseries,
  usePriorityFeeTimeseriesQuery,
} from "./usePriorityFeeTimeseriesQuery"
import { useTransformQueryData } from "@lib/ui/query/hooks/useTransformQueryData"
import { bigintAverage } from "@lib/utils/math/bigint/bigintAverage"

const transform = (timeseries: PriorityFeeTimeseries) =>
  recordMap(timeseries, bigintAverage)

export const usePriorityFeesQuery = () => {
  const query = usePriorityFeeTimeseriesQuery()

  return useTransformQueryData(query, transform)
}

For cases where we only need the fee for a specific priority level (defaulting to medium), the usePriorityFeeQuery hook provides a streamlined way to access a single priority fee value. This hook builds on top of usePriorityFeesQuery but extracts just the requested priority level's fee:

import { useTransformQueryData } from "@lib/ui/query/hooks/useTransformQueryData"
import {
  defaultFeePriority,
  FeePriority,
} from "../maxPriorityFeePerGas/core/FeePriority"
import { useCallback } from "react"
import { usePriorityFeesQuery } from "./usePriorityFeesQuery"

export const usePriorityFeeQuery = (
  priority: FeePriority = defaultFeePriority,
) => {
  const query = usePriorityFeesQuery()

  return useTransformQueryData(
    query,
    useCallback((result) => result[priority], [priority]),
  )
}

Having established our query infrastructure for priority fees, let's examine the first component in our implementation: the MaxPriorityFeePerGasTitle. This component serves as a section header that dynamically displays the current average priority fee. It leverages the MatchQuery component from RadzionKit for handling the asynchronous data state - rendering a Spinner during loading and the formatted fee value once available.

import { gwei } from "@lib/chain/evm/utils/gwei"
import { fromChainAmount } from "@lib/chain/utils/fromChainAmount"
import { Spinner } from "@lib/ui/loaders/Spinner"
import { MatchQuery } from "@lib/ui/query/components/MatchQuery"
import { formatAmount } from "@lib/utils/formatAmount"
import { usePriorityFeeQuery } from "../queries/usePriorityFeeQuery"
import { Text } from "@lib/ui/text"

export const MaxPriorityFeePerGasTitle = () => {
  const query = usePriorityFeeQuery()

  return (
    <>
      maxPriorityFeePerGas{" "}
      <MatchQuery
        value={query}
        pending={() => <Spinner />}
        success={(value) => (
          <Text as="span" color="contrast">
            {" = "}
            {formatAmount(fromChainAmount(value, gwei.decimals))} {gwei.name}
          </Text>
        )}
      />
    </>
  )
}

The next crucial component in our implementation is the PriorityOptions, which provides a visual representation of priority fee options. This component displays three priority levels (low, medium, high), each with its own color indicator and current fee value.

import styled from "styled-components"
import { feePriorities } from "../core/FeePriority"
import { HStack } from "@lib/ui/css/stack"
import { gwei } from "@lib/chain/evm/utils/gwei"
import { getFeePriorityColor } from "../utils/getFeePriorityColor"
import { Text } from "@lib/ui/text"
import { useTheme } from "styled-components"
import { formatAmount } from "@lib/utils/formatAmount"
import { fromChainAmount } from "@lib/chain/utils/fromChainAmount"
import { sameDimensions } from "@lib/ui/css/sameDimensions"
import { round } from "@lib/ui/css/round"
import { capitalizeFirstLetter } from "@lib/utils/capitalizeFirstLetter"
import { usePriorityFeesQuery } from "../../queries/usePriorityFeesQuery"
import { Spinner } from "@lib/ui/loaders/Spinner"
import { MatchQuery } from "@lib/ui/query/components/MatchQuery"

const Identifier = styled.div`
  ${sameDimensions(8)}
  ${round}
`

export const PriorityOptions = () => {
  const theme = useTheme()
  const query = usePriorityFeesQuery()

  return (
    <HStack
      fullWidth
      justifyContent="space-between"
      wrap="wrap"
      alignItems="center"
      gap={20}
    >
      {feePriorities.map((priority) => (
        <HStack alignItems="center" gap={8} key={priority}>
          <HStack alignItems="center" gap={6}>
            <Identifier
              style={{
                background: getFeePriorityColor(theme, priority).toCssValue(),
              }}
            />
            <Text color="supporting">{capitalizeFirstLetter(priority)}</Text>
          </HStack>
          <MatchQuery
            value={query}
            pending={() => <Spinner />}
            success={(value) => (
              <Text>
                {formatAmount(fromChainAmount(value[priority], gwei.decimals))}{" "}
                {gwei.name}
              </Text>
            )}
          />
        </HStack>
      ))}
    </HStack>
  )
}

To better understand fee trends, we can visualize how priority fees have fluctuated across the last 10 blocks using an interactive chart.

import { Spinner } from "@lib/ui/loaders/Spinner"
import { usePriorityFeeTimeseriesQuery } from "../../queries/usePriorityFeeTimeseriesQuery"
import { FeeChartContent } from "./FeeChartContent"
import { MatchQuery } from "@lib/ui/query/components/MatchQuery"
import { recordMap } from "@lib/utils/record/recordMap"

export const FeeChart = () => {
  const query = usePriorityFeeTimeseriesQuery()

  return (
    <MatchQuery
      value={query}
      pending={() => <Spinner />}
      success={(value) => {
        return (
          <FeeChartContent
            value={recordMap(value, (array) => array.map(Number))}
          />
        )
      }}
    />
  )
}

The FeeChartContent component handles the visualization of priority fee trends using our custom chart implementation. This component leverages various utility functions and styled components to create a responsive line chart. It normalizes the fee data arrays, generates appropriate Y-axis labels in Gwei units, and renders three overlapping line charts - one for each priority level (low, medium, high). Each line chart is color-coded to match its corresponding priority level and includes a gradient fill for better visual distinction. The chart is wrapped in an ElementSizeAware component to ensure proper responsiveness, and it includes horizontal grid lines for easier value comparison. For a detailed explanation of the chart implementation itself, you can refer to a dedicated line chart blog post here.

import { ElementSizeAware } from "@lib/ui/base/ElementSizeAware"
import { VStack } from "@lib/ui/css/stack"
import { normalizeDataArrays } from "@lib/utils/math/normalizeDataArrays"
import { generateYLabels } from "@lib/ui/charts/utils/generateYLabels"
import { ChartYAxis } from "@lib/ui/charts/ChartYAxis"
import { useTheme } from "styled-components"
import { ChartHorizontalGridLines } from "@lib/ui/charts/ChartHorizontalGridLines"
import { LineChart } from "@lib/ui/charts/LineChart"
import { ValueProp } from "@lib/ui/props"
import { formatUnits } from "viem"
import { feePriorities, FeePriority } from "../core/FeePriority"
import { feeChartConfig } from "./config"
import { ChartSlice } from "@lib/ui/charts/ChartSlice"
import { ChartLabel } from "@lib/ui/charts/ChartLabel"
import { getFeePriorityColor } from "../utils/getFeePriorityColor"
import { TakeWholeSpaceAbsolutely } from "@lib/ui/css/takeWholeSpaceAbsolutely"
import { gwei } from "@lib/chain/evm/utils/gwei"

type FeeChartProps = ValueProp<Record<FeePriority, number[]>>

export const FeeChartContent = ({ value }: FeeChartProps) => {
  const theme = useTheme()
  const yLabels = generateYLabels({ data: Object.values(value).flat() })

  const normalized = normalizeDataArrays({
    ...value,
    yLabels,
  })

  return (
    <ElementSizeAware
      render={({ setElement, size }) => {
        const contentWidth = size
          ? size.width - feeChartConfig.yLabelsWidth
          : undefined

        return (
          <VStack flexGrow gap={20} ref={setElement}>
            <ChartSlice yLabelsWidth={feeChartConfig.yLabelsWidth}>
              <ChartYAxis
                renderLabel={(index) => (
                  <ChartLabel key={index}>
                    {formatUnits(BigInt(yLabels[index]), gwei.decimals)}
                  </ChartLabel>
                )}
                data={normalized.yLabels}
              />
              <VStack
                style={{
                  position: "relative",
                  minHeight: feeChartConfig.chartHeight,
                }}
                fullWidth
              >
                {contentWidth &&
                  feePriorities.map((key) => {
                    const data = normalized[key]
                    return (
                      <TakeWholeSpaceAbsolutely key={key}>
                        <LineChart
                          key={key}
                          dataPointsConnectionKind="sharp"
                          fillKind={"gradient"}
                          data={data}
                          width={contentWidth}
                          height={feeChartConfig.chartHeight}
                          color={getFeePriorityColor(theme, key)}
                        />
                      </TakeWholeSpaceAbsolutely>
                    )
                  })}
                <ChartHorizontalGridLines data={normalized.yLabels} />
              </VStack>
            </ChartSlice>
          </VStack>
        )
      }}
    />
  )
}

Visualizing Fee Trends

To better understand fee trends, we can visualize how priority fees have fluctuated across the last 10 blocks using an interactive chart.

Maximum Fee Per Gas

Now that we understand how to calculate and visualize the priority fee, let's examine another crucial parameter in EVM transaction fees: the maxFeePerGas. This parameter represents the absolute maximum amount per unit of gas that a user is willing to pay for their transaction. It's calculated as the sum of the maxPriorityFeePerGas (the tip to validators) and the baseFee (the network's base cost). The MaxFeePerGas component below displays this relationship in a clear formula and provides additional context about how this parameter helps manage transaction costs:

import { ShyInfoBlock } from "@lib/ui/info/ShyInfoBlock"
import { Text } from "@lib/ui/text"
import { FeeSection } from "../FeeSection"
import { toPercents } from "@lib/utils/toPercents"
import { baseFeeMultiplier } from "../baseFee/config"

export const MaxFeePerGas = () => (
  <FeeSection
    title={
      <>
        maxFeePerGas
        <Text as="span" color="contrast">
          {" "}
          = maxPriorityFeePerGas + baseFee × {baseFeeMultiplier}
        </Text>
      </>
    }
  >
    <ShyInfoBlock>
      <Text color="supporting">
        We multiply the base fee by {baseFeeMultiplier} to account for the
        maximum allowed {toPercents(baseFeeMultiplier - 1)} increase in the base
        fee between blocks. This buffer helps ensure that your transaction
        remains competitive even if the network congestion causes the base fee
        to rise unexpectedly.
      </Text>
    </ShyInfoBlock>
  </FeeSection>
)

Base Fee Dynamics

In EVM-based networks, the baseFee is dynamically adjusted by the protocol based on network demand. When blocks are more than 50% full, the base fee increases by up to 12.5% per block, and when they're less than 50% full, it decreases by the same maximum percentage. This mechanism helps regulate network congestion by making transactions more expensive during high-demand periods and cheaper during low-demand periods. To account for this potential increase between blocks, web3 applications typically multiply the current baseFee by a safety factor. In our implementation, we use a multiplier of 1.125 (12.5%), which matches the maximum possible increase in base fee between blocks. This approach provides a buffer against base fee fluctuations, reducing the likelihood of transaction failures due to insufficient gas fees while the transaction is pending in the mempool.

export const baseFeeMultiplier = 1.125

Real-time Fee Monitoring

To monitor the current base fee, we've implemented the useBaseFeeQuery hook that leverages Wagmi's useBlock hook with the watch option enabled. This setup allows us to continuously track the base fee as new blocks are produced. The hook extracts the baseFeePerGas value from the latest block data, ensuring we always have access to the most up-to-date network fee information. Since the base fee is an optional parameter in some EVM chains, we use the shouldBePresent utility to handle type safety, ensuring our application only works with chains that implement EIP-1559 fee mechanics.

import { useBlock } from "wagmi"
import { useTransformQueryData } from "@lib/ui/query/hooks/useTransformQueryData"
import { shouldBePresent } from "@lib/utils/assert/shouldBePresent"
import { Block } from "viem"

const transform = (data: Block): bigint => {
  return shouldBePresent(data.baseFeePerGas)
}

export const useBaseFeeQuery = () => {
  const query = useBlock({
    watch: true,
  })

  return useTransformQueryData(query, transform)
}

Base Fee Component

The BaseFee component provides users with real-time visibility into the network's current base fee and explains its dynamic nature. Similar to our other fee components, it uses the FeeSection layout and displays the current base fee value in Gwei using the MatchQuery component for handling loading states. The component includes an informative description that helps users understand how the base fee automatically adjusts based on network demand, making it clear why transaction costs may vary over time.

import { FeeSection } from "../FeeSection"
import { MatchQuery } from "@lib/ui/query/components/MatchQuery"
import { Text } from "@lib/ui/text"
import { ShyInfoBlock } from "@lib/ui/info/ShyInfoBlock"
import { gwei } from "@lib/chain/evm/utils/gwei"
import { formatAmount } from "@lib/utils/formatAmount"
import { fromChainAmount } from "@lib/chain/utils/fromChainAmount"
import { useBaseFeeQuery } from "../queries/useBaseFeeQuery"
import { Spinner } from "@lib/ui/loaders/Spinner"

export const BaseFee = () => {
  const query = useBaseFeeQuery()

  return (
    <FeeSection
      title={
        <>
          baseFee
          <MatchQuery
            value={query}
            pending={() => <Spinner />}
            success={(value) => (
              <Text as="span" color="contrast">
                {" = "}
                {formatAmount(fromChainAmount(value, gwei.decimals))}{" "}
                {gwei.name}
              </Text>
            )}
          />
        </>
      }
    >
      <ShyInfoBlock>
        <Text color="supporting">
          The base fee is automatically determined by the network based on the
          demand for block space. When network activity increases, the base fee
          goes up to discourage congestion. When activity decreases, the base
          fee goes down to encourage network usage. This mechanism helps keep
          transaction fees at a reasonable level while ensuring network
          stability.
        </Text>
      </ShyInfoBlock>
    </FeeSection>
  )
}

Putting It All Together

Finally, let's bring all our fee calculations together in the MaxFee component to provide users with a practical example. This component calculates the total estimated cost for transferring 1 ETH on the Ethereum mainnet. It combines three key pieces of data: the current base fee (adjusted with our safety multiplier), the priority fee (using the medium priority level), and the estimated gas required for the transfer. Using Wagmi's useEstimateGas hook, we simulate the transaction to get an accurate gas estimate, while useAssetPriceQuery fetches the current ETH price to display the fee in USD. The component uses useTransformQueriesData to combine these data streams and calculate the total maximum fee, presenting it in both ETH and USD for better user understanding.

import { Text } from "@lib/ui/text"
import { formatAmount } from "@lib/utils/formatAmount"
import { useEstimateGas } from "wagmi"
import { MatchQuery } from "@lib/ui/query/components/MatchQuery"
import { useAssetPriceQuery } from "@lib/chain-ui/queries/useAssetPriceQuery"
import { toChainAmount } from "@lib/chain/utils/toChainAmount"
import { mainnet } from "viem/chains"
import { useBaseFeeQuery } from "../queries/useBaseFeeQuery"
import { useTransformQueriesData } from "@lib/ui/query/hooks/useTransformQueriesData"
import { usePriorityFeeQuery } from "../queries/usePriorityFeeQuery"
import { baseFeeMultiplier } from "../baseFee/config"
import { fromChainAmount } from "@lib/chain/utils/fromChainAmount"
import { Spinner } from "@lib/ui/loaders/Spinner"

const ethAmount = 1

export const MaxFee = () => {
  const baseFeeQuery = useBaseFeeQuery()
  const priorityFeeQuery = usePriorityFeeQuery()

  const gasQuery = useEstimateGas({
    account: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    to: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    value: toChainAmount(ethAmount, mainnet.nativeCurrency.decimals),
  })

  const priceQuery = useAssetPriceQuery({ id: "ethereum" })

  const maxFeeQuery = useTransformQueriesData(
    {
      baseFee: baseFeeQuery,
      priorityFee: priorityFeeQuery,
      gas: gasQuery,
    },
    ({ baseFee, priorityFee, gas }) =>
      fromChainAmount(
        (BigInt(Math.round(Number(baseFee) * baseFeeMultiplier)) +
          priorityFee) *
          gas,
        mainnet.nativeCurrency.decimals,
      ),
  )

  return (
    <Text
      color="contrast"
      height="l"
      as="h1"
      size={28}
      style={{ textTransform: "uppercase" }}
    >
      Estimated max fee to send {ethAmount} ETH:{" "}
      <MatchQuery
        value={maxFeeQuery}
        pending={() => <Spinner />}
        success={(maxFee) => {
          return (
            <>
              <Text as="span" color="primary">
                {formatAmount(maxFee)} ETH{" "}
                <MatchQuery
                  value={priceQuery}
                  success={(price) => {
                    return <>≈ ${formatAmount(price * maxFee)}</>
                  }}
                />
              </Text>
            </>
          )
        }}
      />
    </Text>
  )
}

Price Integration

To provide users with familiar cost references, we fetch the current Ethereum price from CoinGecko using the useAssetPriceQuery hook.

import { useQuery } from "@tanstack/react-query"
import {
  getAssetPrice,
  GetAssetPriceInput,
} from "../../chain/price/utils/getAssetPrice"

export const useAssetPriceQuery = (input: GetAssetPriceInput) => {
  return useQuery({
    queryKey: ["asset-price", input],
    queryFn: () => getAssetPrice(input),
  })
}

By combining Viem and Wagmi's powerful hooks with real-time data from the Ethereum network, we've created a comprehensive gas fee calculator that helps users make informed decisions about their transaction costs. The application not only provides current fee estimates but also visualizes historical trends and offers different priority levels to suit various transaction needs. This implementation demonstrates how modern web3 libraries can be leveraged to create intuitive interfaces for complex blockchain interactions.