DEV Community: Fazza Razaq Amiarso

My Journey as a React.js Learning Facilitator for IDCamp 2023

Fazza Razaq Amiarso — Wed, 17 Jul 2024 19:48:32 +0000

In this post, I want to share my experience facilitating a scholarship program called IDCamp 2023 by Indosat Ooredoo Hutchison Digital Camp and Dicoding Indonesia for 4 months. It was my first time mentoring and I wanted to ensure my 25 students maximized their chances of passing.

Why I Became a Facilitator

As a self-taught developer, I struggled to learn without guidance. It made me realize how much easier learning can be with support and guidance. I also wanted to help others avoid the challenges I faced, like imposter syndrome, and the difficulty of gauging learning progress.

There's a quote by Richard Feynman that inspired me:

"The best way to understand something is to explain it to someone else."

Challenges and Solutions

Planning and Creating a Mentoring System

Since I was new to this, I wasn't sure where to start. I created a simple dashboard in Notion to organize resources, communication templates, and ideas. This proved valuable as the program progressed that allowed me to easily refer back to past information.

Communicating Effectively with Mentees

The program was online, which presented communication challenges. We primarily used a WhatsApp group, which can be asynchronous, leading to slow responses or students being hesitant to ask questions in a large group. So, I provided resources regularly to stimulate discussion and reached out to quieter students individually.

Encouraging Active Participation

Keeping students engaged was difficult at times. The group could get quiet with minimal responses. To address this, I introduced some friendly competition by providing weekly reports on group progress, keeping everyone motivated, and emphasizing that they could ask questions freely. This is an area I'd like to learn more about, as it's crucial for a positive mentee experience.

Tracking and Encouraging Mentee Progress

The goal was to ensure all students passed within the program timeline. My group had a mix of students: some who passed quickly, some who needed more help, and unfortunately, a few who went missing in action (AWOL). For struggling students, I reached out personally to understand the reason behind their slow progress. Some were busy with school or work, while others simply disappeared. This taught me the importance of considering students' personal lives.

Teaching and Explaining Coding Concepts Live

I was responsible for holding eight live study sessions where students could ask questions and discuss topics. I worried about what to do if students ran out of questions and how to keep the sessions valuable. Inspired by tech YouTubers like Primeagen and Theo, I decided to conduct live coding sessions after Q&A. We built real-world projects using FrontEndMentor. This was well-received by students and pushed my own understanding to the limit as I explained concepts on the fly. It also helped me identify any gaps in my knowledge.

Engaging Students in Live Sessions

I believe learning from mistakes is a powerful tool, and using a personal touch can boost engagement. Therefore, I incorporated live code reviews into some sessions. I reviewed student projects, focusing on refactoring, best practices, and bug fixes. Students appreciated these sessions as they could see where their approach went wrong when building their projects. This also made the learning more relevant as they could see how things work in production. Additionally, it increased their participation as they could pinpoint their areas of confusion.

Mentees Growth

Several mentees stepped outside their comfort zones by exploring new areas on their own like TypeScript and other technologies.
They gained valuable insights on how to learn and solve programming problems independently.
Some mentees even helped each other with concepts they learned.

The Rewards

Over the course of eight live sessions, my speech delivery improved significantly by constant feedback from my mentees. My understanding of related topics also deepened as I had to ensure clear explanations for my mentees. Lastly, I gained valuable connections with other facilitators and mentees.

Galleries

Looking Forward

My experience as a mentor in IDCamp2023 was incredibly rewarding. Witnessing my mentees' success and growth was truly fulfilling that make me eager to continue my journey as a mentor and meet new people. I'm committed to developing my skills in effective mentoring and communication to ensure an even more positive experience for future mentees. Also, I'm actively seeking new mentoring opportunities to put my learnings into practice.

I’m still far from being a great mentor, I deeply appreciate any insights and advice from you guys!

Hey!Sound: Upload and Vote for the Best Audios on the Internet

Fazza Razaq Amiarso — Mon, 13 May 2024 00:55:58 +0000

This is a submission for the Netlify Dynamic Site Challenge: Build with Blobs.

What I Built

An audio sharing app where users can upload their audio with maximum time limit of 30 seconds. Users can tag their audios into 3 categories: Podcast, Music, and Bites. Users can also vote or downvote an uploaded audio (without authentication).

Huge Credits to 50hacks.co for the app's inspiration.

Initially, I got delayed by one whole day because of production build that keep failing when using blobs. However, I'm really grateful that I didn't give up since I ended up learning a lot of interesting things while searching and hacking for the solutions 😉.

Useful Links

Demo: https://heysound.netlify.app/
Source code:https://github.com/fazzaamiarso/heysound

Platform Primitives

Filtering Blobs Metadata

The main feature of this app is sharing audio, so I utilize Netlify blobs to store audio with it's metadata to display in UI.

Since netlify blobs have filter by prefix to get blobs list, I used it to categorize the audios by prefixing it with <category>:<key>.

Here's the upload implementation

const store = () => getStore("sounds");

export async function uploadAudio(formData) {
  const audio = formData.get("sound");
  const category = formData.get("category");
  const description = formData.get("description");

  const key = `${category}:${nanoid()}`;

  if (!audio) return { error: "Audio not found" };

  await store().set(key, audio, {
    metadata: {
      category,
      description,
      type: audio.type,
      name: audio.name,
      createdAt: new Date().toISOString(),
    },
  });
}

Since I display the audios based on categories, I can conveniently filter them when calling the API with prefix

const store = () => getStore("sounds");

export async function getSoundsMetadata(prefixFilter) {
  const blobList = await store().list({ prefix: prefixFilter });

  const soundsData = await Promise.all(
    blobList.blobs.map(async (blob) => {
      const metadata = await store().getMetadata(blob.key);
      return { key: blob.key, metadata: metadata?.metadata };
    }),
  );

  return soundsData;
}

Another convenient thing is that, I have the options to only retrieve the metadata so I don't need to pass around blobs in the components (which isn't possible, right?).

Retrieving Audios Blob

To retrieve a blob is pretty simple and straight-forward.Although, I know there are better ways to send the blob back to client. Due to time constraints, I just use the simplest method

const store = () => getStore("sounds");

export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const key = searchParams.get("key");

  if (!key) throw new Error("Key not found!");

  const audioBlob = await store().get(key, {
    type: "stream",
    consistency: "strong",
  });

  return new NextResponse(audioBlob, {
    headers: {
      "Netlify-CDN-Cache-Control": "public, max-age=604800, immutable",
      "Netlify-Vary": "query",
    },
  });
}

Store Voting Data

The final way I use the blob storage is to store voting data. What I like the most is that the data is unstructured, that means I have a lot flexibility on how I want to store my data without strict constraints.

Here's the implementation

const store = () => getStore("votes");

const createVoteKeys = (key) => `${key}:votes`;

export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const key = searchParams.get("key");

  if (!key) return NextResponse.json({ count: 0 });

  const count = await store().get(createVoteKeys(key), { type: "json" });

  return NextResponse.json({ count: count ?? 0 });
}

export async function POST(request) {
  const data = await request.json();

  const { key, action } = data;

  const count = await store().get(createVoteKeys(key), { type: "json" });

  const newCount = count + votesAction

  await store().setJSON(createVoteKeys(key), newCount);

  return NextResponse.json({ message: `Successfully updated: ${key} count!` });
}

If you come until this far, I thank you for your time! I hope by reading this article, someone can find it useful.

Let's chat and connect on Linkedin 😀. I love talking and learning from new people.

Add TOC with Scroll Spy in Astro

Fazza Razaq Amiarso — Sun, 08 Jan 2023 17:00:00 +0000

Sometimes, there is a table of content to help us navigate through a blog more easily. When building a custom blog with remark and rehype, a standard solution is to use the rehype-toc plugin.

In Astro, we can build a table of content without extra plugins. Astro already provides us with the necessary property by default. As an extra touch, we will add a scroll spy to keep track of our current heading.

I use the Astro blog starter template as a starting point.

Create the Component

Let's create a new Astro component called TOC.astro and define the needed props.

---
export type Props = {
    pageHeadings : Array<{depth:number,text: string; slug: string }>
}

const { pageHeadings } = Astro.props;
---
<aside id="#toc">
    <ul>{pageHeadings.map(h => {
        return <li> <a href={`#${h.slug}`}>{h.text}</a></li>
    })}</ul>
</aside>

The pageHeadings props will be special headings props passed from the astro layout component. Astro automatically assigns an id to all headings in markdown, which become slug in headings props.

[{
    text : "Implement TOC",
    depth : 1,
    slug: "implement-toc"
},
{
    text : "Create Markup",
    depth : 2,
    slug: "create-markup"
}]

Insert the TOC into the blog layout and pass it to the special headings props

---
const {headings} = Astro.props;
---
<body>
    <Header />
        <main>
            <article>
            <h1>{content.title}<h1>
            <hr />
            <slot />
            <TOC pageHeadings={headings} />
            </article>
        </main>
    <Footer />
</body>

Let's add a little style to the TOC, so it's fixed to the right.

<style>
    #toc {
        position: fixed;
        top: 0;
        right: 5rem;
    }
    ul {
        list-style: none;
    }
    a {
        text-decoration: none;
    }
</style>

Here's the result.

The TOC is working and sufficient for most use cases. But, we will enhance it with a scroll spy to highlight the active heading.

Scroll Spy with Intersection Observer

We must let the TOC know which heading is intersecting by observing/spying on the heading with Intersection Observer.

Add an Observer Callback Function

Firstly, insert a script tag in the TOC file. Afterward, create the observer callback function responsible for detecting and setting the active state.

<script>
const setCurrentHeading : IntersectionObserverCallback = (entries) => {
    // loop to each entries (headings) in the page
    for (let entry of entries) {
    // equivalent to the slug returned from pageHeadings
    const { id } = entry.target;
    // get the TOC link's element for the current entry
    const tocLinkEl = document.querySelector(`#toc a[href='#${id}']`);
    if(!tocLinkEl) return;
    }
}
</script>

The above code loops through each entry and selects the link element. It also has a guard in case the link element doesn't exist, which is unlikely.

Then, add the active styling to the intersecting entry.

// check if the entry is intersecting
if (entry.isIntersecting) {
// remove active class from all links
document.querySelectorAll("#toc a").forEach((e) => e.classList.remove("active"));
// add active class to the currently active entry
tocLinkEl.classList.add("active");
}

Here's the active class for this example.

a.active {
    color: red;
    font-weight: 600;
}

Observer Option

Let's define the option for the observer.

const observerOptions = {
    threshold: 1,
    rootMargin : "0px 0px -66%"
}

Here's the explanation for the option.

threshold: 1 means we want to register the element as an entry when the element is fully visible.
rootMargin: "0px 0px -66%" means we crop the observer's viewport height by 66% at the bottom. So, our viewport have 33% of it's height. It's helpful because we want the entry to be active only when a user has scrolled enough past the heading.

Observe the Headings

We have all the pieces needed to create an observer instance to observe the headings.

const observer = new IntersectionObserver(setCurrentHeading, observerOptions);
// select all headings to observe
const elToObserve = document.querySelectorAll("article :is(h2,h3)")
// finally, observe the elements
elToObserve.forEach(el => observer.observe(el))

What the code does is select all headings that we want to observe. Then, loop through each heading and observe them by calling observe().

Here's the final result.

You can also see how I implement it in my blog with TailwindCSS and sticky positioning.

How to Send Invoice and Add Payment Reminder in Next.js with Courier API

Fazza Razaq Amiarso — Tue, 03 Jan 2023 16:22:36 +0000

Background

On the internet, a lot of open-source Invoice management apps are built with Laravel. As a Javascript developer, I want to build the “React Solution” for devs that are familiar with React and Javascript.

A problem I found when building with services in node.js is there is no built-in mailer. So, I have to search for a 3rd party service to do that for me.

In this article, I will be integrating Courier to send emails for this project.

Pre-requisites

As this article isn't your typical follow-along (more like "please sit tight and see how I do it"), it's not mandatory to be familiar with all technologies used. However, familiarity with Typescript and Next.js will be beneficial for quicker understanding.

Techs in this blog:

Typescript. Type-safety and auto-completion are the best, right?
Next.js. A production-ready framework to build a full-stack app, even for beginners.
Prisma. A great ORM to work with databases. We use Prisma because of its type-safety and auto-completion, providing great developer experience with typescript added.
Trpc. Enable us to easily build end-to-end type-safety between our Next.js client and server.
Courier API. A great service/platform to handle our notifications, such as email, SMS, and much more.

You can find the full source code here for reference.

Goals

Before building the features, let's define our goals.

Send invoice link to client's email.
Send a reminder a day before an invoice's due date.
Cancel an invoice due date reminder when the invoice is already paid.
Handling network errors.

Part 1: Setup Courier Platform

Let's head to Courier Dashboard. By default, it's in a production environment. Since I want to test things out, I'm going to change to the test environment by clicking the dropdown in the top-right corner.

We can copy all templates later to production or vice-versa.

Now, I will create a brand for my email notifications.

I'm just going to add a logo (beware that the logo width is fixed to 140px) on the header and social links on the footer.

The designer UI is pretty straightforward, so here is the final result.

Don't forget to publish the changes.

Part 2: Send Invoice to Email

Currently, the send email button on the UI is doing nothing.

I'm going to create a courier.ts file in src/lib/ to keep all Courier-related code. Also, I will use courier node.js client library which already abstracted all Courier API endpoints to functions.

Before I code the functionality, let's create the email notification design in courier designer and set up a Gmail provider.

On the email designer page, We will see that the created brand is already integrated. After that, let's design the template accordingly with the needed data. Here is the final result.

Notice the value with {} that becomes green, it means it's a variable that can be inserted dynamically. I also set the 'See Invoice' button (or action) with a variable.

Before I can use the template, I need to create a test event by clicking the preview tab. Then, it will show a prompt to name the event and set data in JSON format.

That data field is what will populate the value of the green {} variables (the data can be set from code also). Since it's a test event, I will fill it with arbitrary values.

Next, I publish the template so I can use it. Then, go to send tab. It will show the necessary code to send the email programmatically and the data will be populated with the previous test event that I created.

Backend

I will copy the test AUTH_TOKEN to the .env file and copy the snippet to src/lib/courier.ts.

const authToken = process.env.COURIER_AUTH_TOKEN;
// email to receive all sent notifications in DEVELOPMENT mode
const testEmail = process.env.COURIER_TEST_EMAIL;
const INVOICE_TEMPLATE_ID = <TEMPLATE_ID>;
const courierClient = CourierClient({
  authorizationToken: authToken,
});

Create a sendInvoice function that will be responsible for sending an email. To send an email from the code, I use the courierClient.send() function.

// src/lib/courier.ts
export const sendInvoice = async ({
  customerName,
  invoiceNumber,
  invoiceViewUrl,
  emailTo,
  productName,
  dueDate,
}: SendInvoice) => {
const recipientEmail = process.env.NODE_ENV === "production" ? emailTo : testEmail;

const { requestId } = await courierClient.send({
      message: {
        to: {
          email: recipientEmail,
        },
        template: INVOICE_TEMPLATE_ID,
        // Data for courier template designer
        data: {
          customerName,
          invoiceNumber,
          invoiceViewUrl,
          productName,
          dueDate,
        },
      },
    });
    return requestId
};

Define types for the sendInvoice function.

// src/lib/courier.ts
interface SendInvoice {
  productName: string;
  dueDate: string;
  customerName: string;
  invoiceNumber: string;
  invoiceViewUrl: string;
  emailTo: string;
}

Now that I can send the email, I will call it in the sendEmail trpc endpoint that resides in src/server/trpc/router/invoice.ts.

Just remember that trpc endpoint is a Next.js API route. In this case, sendEmail will be the same as calling the /api/trpc/sendEmail route with fetch under the hood. For more explanation https://trpc.io/docs/quickstart.

// src/server/trpc/router/invoice.ts
import { sendInvoice } from '@lib/courier';
import { dayjs } from '@lib/dayjs';
// .....SOMEWHERE BELOW
  sendEmail: protectedProcedure
    .input(
      z.object({
        customerName: z.string(),
        invoiceNumber: z.string(),
        invoiceViewUrl: z.string(),
        emailTo: z.string(),
        invoiceId: z.string(),
        productName: z.string(),
        dueDate: z.date(),
      })
    )
    .mutation(async ({ input }) => {
      const invoiceData = {
        ...input,
        dueDate: dayjs(input.dueDate).format('D MMMM YYYY'),
      };
      await sendInvoice(invoiceData);
    }),

For those who are unfamiliar with trpc, What I did is the same as handling a POST request. Let's break it down.

Trpc way of defining request input from client by validating with Zod. Here I define all data that are needed for the sendInvoice function.

.input(
      z.object({
        customerName: z.string(),
        invoiceNumber: z.string(),
        invoiceViewUrl: z.string(),
        emailTo: z.string(),
        invoiceId: z.string(),
        productName: z.string(),
        dueDate: z.date(),
      })
    )

Define a POST request handler (mutation).

// input from before
 .mutation(async ({ input }) => {
      const invoiceData = {
        ...input,
        // format a date to string with a defined format. 
        dueDate: dayjs(input.dueDate).format('D MMMM YYYY'), // ex.'2 January 2023'
      };
      // send the email
      await sendInvoice(invoiceData);
    }),

Frontend

Now, I can start to add the functionality to the send email button. I'm going to use the trpc.useMutation() function, which is a thin wrapper of tanstack-query's useMutation.

Let's add the mutation function. On successful response, I want to send a success toast on UI.

//src/pages/invoices/[invoiceId]/index.tsx
import toast from 'react-hot-toast';
const InvoiceDetail: NextPage = () => {
// calling the `sendEmail` trpc endpoint with tanstack-query.
  const sendEmailMutation = trpc.invoice.sendEmail.useMutation({
    onSuccess() {
      toast.success('Email sent!');
    }
  });
}

I can just use the function as an inline handler, but I want to create a new handler for the button.

//src/pages/invoices/[invoiceId]/index.tsx

 // still inside the InvoiceDetail component
 const sendInvoiceEmail = () => {
    const hostUrl = window.location.origin;
   // prevent a user from spamming when the API call is not done.
    if (sendEmailMutation.isLoading) return;
    // send input data to `sendEmail` trpc endpoint
    sendEmailMutation.mutate({
      customerName: invoiceDetail.customer.name,
      invoiceNumber: `#${invoiceDetail.invoiceNumber}`,
      invoiceViewUrl: `${hostUrl}/invoices/${invoiceDetail.id}/preview`,
      emailTo: invoiceDetail.customer.email,
      invoiceId: invoiceDetail.id,
      dueDate: invoiceDetail.dueDate,
      productName: invoiceDetail.name,
    });
  };

Now I can attach the handler to the send email button.

//src/pages/invoices/[invoiceId]/index.tsx
<Button
   variant="primary"
   onClick={sendInvoiceEmail}
   isLoading={sendEmailMutation.isLoading}>
   Send to Email
</Button>

Here's the working UI.

Part 3: Send Payment Reminder

I want to schedule a reminder that will be sent a day before an invoice's due date. To do that I'm going to use Courier Automation API.

First, let's design the email template in Courier designer. As I already go through the process before, here is the final result.

Before adding the function, define the types for the parameter and refactor the types.

// src/lib/courier
interface CourierBaseData {
  customerName: string;
  invoiceNumber: string;
  invoiceViewUrl: string;
  emailTo: string;
}
interface SendInvoice extends CourierBaseData {
  productName: string;
  dueDate: string;
}
interface ScheduleReminder extends CourierBaseData {
  scheduledDate: Date;
  invoiceId: string;
}

Now, I add the scheduleReminder function to src/lib/courier

//src/pages/invoices/[invoiceId]/index.tsx
// check if the development environment is production
const __IS_PROD__ = process.env.NODE_ENV === 'production';
const PAYMENT_REMINDER_TEMPLATE_ID = '<TEMPLATE_ID>';
export const scheduleReminder = async ({
  scheduledDate,
  emailTo,
  invoiceViewUrl,
  invoiceId,
  customerName,
  invoiceNumber,
}: ScheduleReminder) => {

  // delay until a day before due date in production, else 20 seconds after sent for development
  const delayUntilDate = __IS_PROD__
    ? scheduledDate
    : new Date(Date.now() + SECOND_TO_MS * 20);
  const recipientEmail = __IS_PROD__ ? emailTo : testEmail;

   // define the  automation steps programmatically
   const { runId } = await courierClient.automations.invokeAdHocAutomation({
     automation: {
       steps: [
         // 1. Set delay for the next steps until given date in ISO string
          { action: 'delay', until: delayUntilDate.toISOString() },
          // 2. Send the email notification. Equivalent to `courierClient.send()`
          {
            action: 'send',
            message: {
              to: { email: recipientEmail },
              template: PAYMENT_REMINDER_TEMPLATE_ID,
              data: {
                invoiceViewUrl,
                customerName,
                invoiceNumber,
              },
            },
          },
        ],
      },
    });
   return runId;
};

To send the reminder, I will call scheduleReminder after a successful sendInvoice attempt. Let's modify the sendEmail trpc endpoint.

// src/server/trpc/router/invoice.ts
sendEmail: protectedProcedure
    .input(..) // omitted for brevity
    .mutation(async ({ input }) => {
      // multiplier for converting day to milliseconds.
      const DAY_TO_MS = 1000 * 60 * 60 * 24;
      // get a day before the due date
      const scheduledDate = new Date(input.dueDate.getTime() - DAY_TO_MS * 1);
      const invoiceData = {..}; //omitted for brevity
      await sendInvoice(invoiceData);
      //after the invoice is sent, schedule the reminder
      await scheduleReminder({
        ...invoiceData,
            scheduledDate,
      });
    }

Now if I try to send an invoice by email, I should get a reminder 20 seconds later since I'm in the development environment.

Part 4: Cancel a reminder

Finally, all the features are ready. However, I got a problem, what if a client had paid before the scheduled date for payment reminder?

Currently, the reminder email will still be sent. That's not a great user experience and potentially a confused client.

Thankfully, Courier has an automation cancellation feature.

Let's add cancelAutomationWorkflow function that can cancel any automation workflow in src/lib/courier.ts.

export const cancelAutomationWorkflow = async ({
  cancelation_token,
}: {
  cancelation_token: string;
}) => {
    const { runId } = await courierClient.automations.invokeAdHocAutomation({
      automation: {
        // define a cancel action, that sends a cancelation_token
        steps: [{ action: 'cancel', cancelation_token }],
      },
    });
   return runId;
};

What is a cancelation_token? It's a unique token that can be set to an automation workflow, so it's cancelable by sending a cancel action with a matching cancelation_token.

Add cancelation_token to scheduleReminder, I use the invoice's Id as a token.

// src/lib/courier.ts
export const scheduleReminder = async (..) => {
  // ...omitted for brevity
  const { runId } = await courierClient.automations.invokeAdHocAutomation({
    automation: {
      // add cancelation token here
      cancelation_token: `${invoiceId}-reminder`,
      steps: [
        { action: 'delay', until: delayUntilDate.toISOString() },

  // ... omitted for brevity

I will call cancelAutomationWorkflow when an invoice's status is updated to PAID in the updateStatus trpc endpoint.

// src/server/trpc/router/invoice.ts
 updateStatus: protectedProcedure
    .input(..) // omitted for brevity
    .mutation(async ({ ctx, input }) => {
      const { invoiceId, status } = input;
      // update an invoice's status in database
      const updatedInvoice = await ctx.prisma.invoice.update({
        where: { id: invoiceId },
        data: { status },
      });
      // cancel payment reminder automation workflow if the status is paid.
      if (updatedInvoice.status === 'PAID') {
        //call the cancel workflow to cancel the payment reminder for matching cancelation_token.
        await cancelAutomationWorkflow({
          cancelation_token: `${invoiceId}-reminder`,
        });
      }
      return updatedStatus;
    }),

Here is the working UI.

Part 5: Error Handling

An important note when doing network requests is there are possibilities of failed requests/errors. I want to handle the error by throwing it to the client, so it can be reflected in UI.
On error, Courier API throws an error with CourierHttpClientError type by default. I will also have all functions' return value in src/lib/courier.ts consistent with the below format.

// On Success
type SuccessResponse = { data: any, error: null }
// On Error
type ErrorResponse = { data: any, error: string }

Now, I can handle errors by adding a try-catch block to all functions in src/lib/courier.ts.

try {
  // ..function code

  // modified return example
  return { data: runId, error: null };
} catch (error) {
  // make sure it's an error from Courier
  if (error instanceof CourierHttpClientError) {
      return { data: error.data, error: error.message };
    } else {
      return { data: null, error: "Something went wrong!" };
    }
}

Let's see a handling example on the sendEmail trpc endpoint.

// src/server/trpc/router/invoice.ts
  const { error: sendError } = await sendInvoice(..);
  if (sendError) throw new TRPCClientError(sendError);
  const { error: scheduleError } = await scheduleReminder(..);
  if (scheduleError) throw new TRPCClientError(scheduleError);

Part 6: Go To Production

Now that all templates are ready, I will copy all assets in the test environment to production. Here is an example.

Conclusion

Finally, all the features are integrated with Courier. We've gone through a workflow of integrating Courier API to a Next.js application. Although it's in Next.js and trpc, the workflow will be pretty much the same with any other technology.

I hope now you can integrate Courier into your application by yourself.

About the Author

I'm Fazza Razaq Amiarso, a full-stack web developer from Indonesia. I'm also an Open Source enthusiast. I love to share my knowledge and learning on my blog. I occasionally help other developers on FrontendMentor in my free time.

Connect with me on LinkedIn

Quick Links

🔗 Courier Docs
🔗 Contribute to Invoys
🔗 Invoys Motivation

Learn A11y with FrontendMentor: Interactive Pricing

Fazza Razaq Amiarso — Thu, 29 Dec 2022 17:30:16 +0000

Introduction

In this article, we're going to build a pricing card. Looking at the design, it may seem simple. However, implementing functional accessibility features to some elements is challenging.

Although I was having a rough time building them and finding resources, I can guide us in implementing them in this article.

Let's get started.

What are we building?

🔗 Github Repository

🔗 Live Demo

Pricing Range Slider

The first component we will build is this slider.

Don't be fooled by its looks. I'm guilty of it myself. Styling is challenging as there's yet to be a standard way to do it.

Firstly, let's create the markup.

<input type="range" name="pricing-slider" id="pricing-slider" class="slider" />
<label for="pricing-slider" class="sr-only">Price Range</label>

Notice that we hide the label because there's no visible label in the design. We use the sr-only utility class, which the previous two articles already covered.

Styling

We already set up the markup, so now we proceed to style the slider. Styling the slider can be complicated as there is no standard way to style it.

The most important thing when custom styling is removing the default appearance.

Important. We won't go too deep in styling as there're articles that explain it in detail better. Please see this article .

How to Fill the Track?

Using CSS background-image in combination with Javascript can give a filled line style when styling the slider.

We can give an arbitrary height and color to the input. It will create a custom track.

Unlike the browser's default styling, we can see no filled line to the left side. We can achieve that with Javascript.

We will set the background-image to create the filled track. The background-image will automatically be on top of the slider tracks.

Here is the CSS.

.slider {
  -webkit-appearance: none; /* Hides the slider so that custom slider can be made */
  appearance: none;
  width: 100%; /* Specific width is required for Firefox. */
  background-size: 50% 100%; /* Initial fill width in the center */
  background-repeat: no-repeat;
  background-image: linear-gradient(hsl(174, 77%, 80%), hsl(174, 77%, 80%));
}

We can modify the 'background-image' width and height with background-size. That means we can dynamically manipulate the filled track width based on our slider value with Javascript.

// Get the slider element
const pricingSlider = document.querySelector('input[type="range"]');

someEL.addEventListener("input", () => {
  // Get the value on change
  const formData = new FormData(form);
  const rangeVal = formData.get("pricing-slider") as string;

  // Extract the needed value for percenetage calculation
  const min = Number(pricingSlider.min);
  const max = Number(pricingSlider.max);
  const sliderVal = Number(pricingSlider.value);

  const sliderGradientPercentage = `${
    ((sliderVal - min) * 100) / (max - min)
  }% 100%`;

  // Set the `background-size` dynamically
  pricingSlider.style.backgroundSize = sliderGradientPercentage;
});

Here is the result

Clearer Slider Value with `aria-valuetext`

Our slider works as intended. However, we can further enhance it. However, the slider values are vague. It will announce whatever the value is in the HTML.

In our case, the slider should announce the price with the pageviews we get. For example, '500k pageviews for $16 per month'.

We can modify the announced values by using aria-valuetext. It will tell the text we set to it. So, we must dynamically update the aria-valuetext in Javascript when the slider's value changes.

In the guide, we must also set the ariaValueNow with the range actual value to use aria-valuetext.

Here is an example.

// inside an "input" event handler
pricingSlider.ariaValueNow = rangeVal;
pricingSlider.ariaValueText = `${pageViews} page views for ${price} per month`;

For more details, check it out on MDN

Billing Frequency Switch

The second element we will tackle is the switch.

Building a Switch with Radio Input?

Looking at the design, we expect to change the switch's state by receiving a mouse click or tap on the two labels on the opposite end.

My first instinct was to use switch role. It sounds reasonable but lacks the interactivity we need on both labels because the switch role only works with a single label.

Fortunately, I found a great article with the solution for our switch button. It styles <input type="radio"/> as a switch button, which makes sense and is accessible.

We must look out for challenging styling when using the radio. We must be creative in handling the radio's positioning and focus area to remain accessible.

I prefer the approach of this article that use an extra span inside the switch. It also means we have to hide the span from screen reader users.

Focus Ring

Currently, our switch is working great. However, we don't have any indication that we're interacting with the switch when we traverse by a keyboard.

We can improve the user experience. We should give an indicator, such as a border or outline on focus.

Since we only want the indicator visible when we use a keyboard, we use :focus-visible CSS state selector.

.switch-thumb:focus-visible {
  outline: 2px solid black;
  outline-offset: 4px;
}

Now, we have an excellent indicator and user experience improvement.

Discount Text

We can make another improvement. Let's look at the discount badge on the yearly billing label.

Currently, a screen reader will read the label as it is. 'Yearly Billing, -25%' gives few contexts. What is the '-25%'?

We can hide the badge's original text from assistive technologies and define the more informative text, which we hide visually.

<label for="yearly-radio" class=""
  >Yearly Billing /* Insert our more informative text */
  <span class="sr-only">with 25% discount</span>

  /* Hide the discount badge's text*/
  <span aria-hidden="true"> -25% <span>discount</span></span>
</label>

Now, screen readers will read the label as 'Yearly Billing with 25% discount'.

Bonus: Format Number and Currency with `Intl`

Some text has a particular format in the design, such as currency and pageviews.

Many developers hardcode the format or create logic to define it dynamically. Although their solutions work, it won't be easy to handle localization. So, there are better ways to tackle it.

Thankfully, Javascript has a built-in API that can handle basic to some advanced formatting tasks. It's called Intl. I will go through it quickly since it's a bonus.

Let's use it to format the currency.

const formatPrice = (price) => {
  Intl.NumberFormat("en-US", {
    // Set to "currency" for currency
    style: "currency",
    // Set the type of currency such as "USD", "JPY", and "CNY".
    currency: "USD",
    // Define how will we display the currency.
    currencyDisplay: "narrowSymbol",
  }).format(Number(price));
};

Format the pageviews too.

const formatViews = (views) =>
  Intl.NumberFormat("en-US", {
    // Define how we want to notate the number
    notation: "compact",
  }).format(views);

Finally, assign the formatted text to their respective elements.

const price = 1000;
const pageviews = 500000;

priceEl.innerText = formatPrice(price); // $1000
pageViewEl.innerText = formatViews(pageviews); // 500k

Recap

In this article, we've covered implementing accessibility to two complex interfaces. It can guide you to the right path when building such an interface.

To sum up:

Build a Pricing slider with Custom styling and Javascript.
Build a two-labeled switch with radio input.
Format currency and number with Intl API.

Learn A11y with FrontendMentor: Card Details

Fazza Razaq Amiarso — Mon, 19 Dec 2022 17:00:00 +0000

Introduction

In this article, we're going to implement and improve a credit/debit card detail form's accessibility. We're also going to use the browser's built-in validation API that's been around for a long time.

Sounds interesting? Let's start.

What we are building?

🔗 Github Repository

🔗 Live Demo

Working with decorator element

In the design below, the cards are responsible to reflect the form's input data.

When dealing with decorative interface, we should ask ourselves, do assistive technology users gain any value or more context with the interface?

In our case, the data are already available in the form itself. If we let assistive technologies detect the interface, isn't it redundant and repetitive?

We call this type of interface a Decorative Element. Decorative elements don't add value to our content.

So, we can add a presentation or none role to the container element. By adding a presentation role to the container, assistive technologies will also ignore its child.

<div role="presentation">// Childrens</div>

Should We Uppercase in CSS or HTML?

We can see that there are many uppercased texts in the design.

Uppercased texts in orange container

Some of us might think to type those uppercased texts in HTML. This isn't wrong per se, but it has its use case.

So, what's the problem? When we uppercase texts in HTML, screen readers will spell out each letter in a text. That isn't what we want, the text should be read normally.

The solution is to uppercase texts in CSS. Yep, CSS has a text-transform property that can transform text to various formats (e.g. uppercase, capitalize, and lowercase).

Here's how to uppercase in CSS.

text-transform: uppercase;

For more details, https://developer.mozilla.org/en-US/docs/Web/CSS/text-transform

Building an Accessible Form

In the previous article, we covered how to handle a form submission. However, it was a simple form with 1 input field. Now, we will deal with a significantly more complex form.

Number Input Field

Most of us (should) think that to create a number input field, we use <input type="number">. Which does make sense.

Weirdly, that's not the best solution for every use case. Some of the reasons are:

It's intended for incrementable integers. Credit card numbers and social security numbers are not incrementable integers.
It has an annoying number stepper/arrow. Users can accidentally click on the stepper and increment/decrement unknowingly.
It has no feedback for assistive technologies on the type it's accepting.

In our case, we ask users for credit card numbers and CVC. So, we will use the well-known method. Which is input with type="text" and extra HTML attributes.

Here is the markup.

<input type="text" inputmode="numeric" pattern="[0-9]*" />

Let's break it down.

inputmode="numeric" to prompt the user on a mobile device with a numeric keyboard.
pattern="[0-9]*" to make sure the input only accepts digits.

Although we define a pattern, users still can type anything. However, the browser will validate the form on submission. If you want, you can add javascript logic to prevent users from typing the wrong type. But, we won't do it.

For more details about input type numbers, check out the official UK government take on this matter here

Should We Provide an `Autocomplete` Attribute?

Based on Web Content Accessibility Guideline, there are benefits when using autocomplete on an input field. Especially, for people with cognitive disabilities and motor impairments.

In our case, it's appropriate to provide an autocomplete for input fields. Furthermore, there are various types of autocomplete that are available.

In the design, almost all fields have a suitable pre-defined autocomplete. Here are what we can use.

cc-name for the cardholder field.
cc-number for the card number field.
cc-exp-month for card expiry date field.
cc-exp-year for card expiry year field.

Lastly, the CVC field doesn't have an autocomplete because we shouldn't save a security number in the browser. Imagine that your friend browsing with your browser and then proceeding to use your auto-filled/saved card information.

We can safely turn off auto-completion by setting autocomplete="off" to the input.

Grouping Fields

Let's investigate this form section.

We can see that it has 2 input fields with 1 label. That's bad. A label can only connect to a single input field.

Fortunately, there's a way around labeling those inputs. If we think closely, it's just a group of 2 inputs, right?

There's an HTML element that can group input fields. It's none other than <fieldset>. So, the label becomes a <legend> element and those 2 inputs become independent.

<fieldset>
  <legend>Exp. Date (MM/YY)</legend>

  <label for="expiry-month">Expiry month</label>
  <input id="expiry-month" placeholder="MM" />

  <label for="expiry-year">Expiry year</label>
  <input id="expiry-year" placeholder="YY" />
</fieldset>

However, the input label is not visible in the design. In the previous article, we already handled visually hiding an element that's still accessible by assistive technology.

The trick is to add a couple lines of CSS to the element. Here, we create a utility class like tailwind.

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

Hinting an Input Format with a Placeholder

Continuing from the section before, we can see that the expiry dates field has a format hint beside the legend's text (i.e. MM/YY).

If it were a single input field, the format hinting would be correct. In our case, we have 2 separate input fields, so we should give them separate hints.

Firstly, remove the hint from the legend to avoid redundancy. After that, wrap the hint in a span and set aria-hidden="true" to hide it from assistive technologies.

<legend>Exp. Date <span aria-hidden="true">(MM/YY)</span></legend>

Secondly, create the input with format hinting. Following the design, we'll use the input's placeholder as a format hint. Similarly, giving hints directly on the label is also possible.

Why not both? because that will be redundant. Screen readers will announce something like this "Expiry month, MM, MM".

<fieldset>
    // legend from before
    <div>
        <div>
            <label for="expiry-month" class="sr-only">
            Expiry Month</label>
            <input type="text" pattern="[0-9]*"
                inputmode="numeric"
                autocomplete="cc-exp-month"
                id="expiry-month"
                name="expiry-month"
                placeholder="MM"
            />
        </div>
        <div>
            <label for="expiry-month" class="sr-only">
            Expiry Year</label>
            <input type="text" pattern="[0-9]*"
                inputmode="numeric"
                autocomplete="cc-exp-year"
                id="expiry-year"
                name="expiry-year"
                placeholder="YY"
            />
        </div>
    </div>
</fieldset

Handling Validation Error

We inevitably have to validate input and handle errors when dealing with forms. So, we're going to implement an accessible error message.

Important. We're going to cover the validation details in the next part.

Invalid Form

When dealing with input errors, the most important thing is setting the input's aria-invalid to true using javascript. This way, assistive technologies can detect invalid input.

Let's implement it to one of the inputs.

const ccName = document.querySelector("input#cc-number");

if (!ccName.validity.valid) {
  el.setAttribute("aria-invalid", "true");
}

Then, set it back to false when the input is valid. Here, the input is valid when there's an 'input' event.

form.addEventListener("input", (e) => {
  const targetEl = e.target;
  targetEl.setAttribute("aria-invalid", "false");
});

We can style invalid fields with CSS :invalid pseudo-class. Similarly, we can use the [aria-invalid] attribute selector when we control the attribute with Javascript.

p:invalid {
  color: red;
}
/* OR */
[aria-invalid="true"] {
  color: red;
}

Announcing the Error Message

Currently, when an error occurred, there isn't any indication of the error nor are the input fields aware of their error.

Based on the design. We will create the error message by:

Insert the error message below the input field
Set the error message's aria-live to assertive.
Connect the error message with the input using aria-describedby to the input.

Here is an example.

/* Notice that their id is the same */
<input id="expiry-month" aria-describedby="expiry-month-err" />
<p aria-live="assertive" id="expiry-month-err"></p>

Since aria-live will announce something when there's an addition to the element, we'll dynamically insert the error with Javascript.

Using the previous input validation example.

if(!ccName.validity.valid) {
    // get the error message element
    const errEl = document.querySelector("#cc-number-err");
    el.setAttribute("aria-invalid", "true");

    // required field error
    if (ccName.validity.valueMissing) {
        errEl.innerText = "Can't be blank!";
    }

Now, screen readers will be alerted when an error occurred. But, it's only going to work once, since there are no changes to the error text on the next validation.

To trigger the alert again, simply remove the error text when we set the aria-invalid to false.

Improving the Design's Error Message

In the challenge specification, some messages should be given for certain errors.

Empty field -> "Can't be blank".
Length is too short -> "Should be <number> characters long".
Wrong Pattern -> "Wrong format, numbers only".

Technically, the errors are fine. So, what can be improved? According to WCAG specification, an error message should contain the field that owns the error. In other words, the error is too general.

Therefore, we can improve the errors into:

Empty Field -> "Card number can't be blank".
Length is too short -> "Card number must contain 16 digits".
Wrong Pattern -> "Card number is in a wrong format, numbers only".

Managing Focus

When we submit a form, what do you think will happen to the focus? There is a lot that can happen.

However, when an error occurred, we want to guide users to the easiest way to fix the error.

We already implemented the error messages. But, the user experience isn't great since we don't know where the focus is located. Imagine a screen reader user that has to find where the invalid input's located with keyboard navigation.

Don't worry, we can fix that problem by focusing on the top-most field that is invalid. So, users can easily navigate back down to the submit button while going through the error.

Let's implement it in our submit listener.

// check form validity with Constraint Validation API
if (!form.checkValidity()) {
  // find the first and top-most invalid input inside the form
  const invalidInput = form.querySelector("input[aria-invalid='true']");

  // focus on the input
  invalidInput?.focus();
}

Here is the result.

More information on focus. https://web.dev/focus/

Validate Input with Constraint Validation API

We're going to use a browser's built-in validation API to validate input values, it's called Constraint Validation API. Although it's not well-known, it's simple and powerful.

It's powerful because it combines native HTML attributes such as required, pattern, and minLength to set the constraint and built-in javascript API. We just set the constraint in HTML and it'll be reflected in its validityState in Javascript.

Let's implement it on the credit card number input.

<input id="cc-number" pattern="[0-9*]" minlength="16" maxlength="16" required />

// Get the element we want to validate
const ccNumber = document.querySelector("#cc-number");

// check if the element is valid
if (!ccNumber.validity.valid) {
  let errorMessage = "";

  // check for empty field or `required`.
  if (ccNumber.validity.valueMissing)
    errorMessage = `Card number can't be blank`;

  // check for mismatched patterns defined in `pattern`
  if (ccNumber.validity.patternMismatch)
    errorMessage = `Card number is in a wrong format, numbers only`;

  // check if the length is less than the `maxLength`
  if (ccNumber.validity.tooShort)
    errorMessage = `Card number must have 16 digits`;
}

Here's a breakdown of the above example.

pattern -> validity.patternMismatch. Input must contain numbers only.
maxLength -> validity.tooLong. Input must be less than or equal to 16 characters.
minLength -> validity.tooShort. Input must be at least 16 characters.
required -> validity.valueMissing. Input Must have a value.

We can also trigger a validation by ourselves with checkValidity.

const formElement = document.querySelector("form");

if (formElement.checkValidity()) {
  // Do something when all form values are valid.
}

const inputEl = document.querySelector("input");
if (inputEl.checkValidity()) {
  // Do something when the input value is valid
}

Here's an old but gold article by Google on Constraint Validation API https://web.dev/constraintvalidation/. Interesting, right?

Recap

We've learned plenty about implementing accessibility, especially about forms. We also learned to implement validation with Constraint validation API.

I hope now you can solve similar accessibility problems or implement them by yourself.

Learn A11y with FrontendMentor: Interactive Rating

Fazza Razaq Amiarso — Tue, 13 Dec 2022 11:38:00 +0000

Series Introduction

I'd been using frontendmentor.io as a platform to practice building projects in my early learning phase. Although all of my solutions were painful to look at 😅, they gave me a nice stepping stone to learning many things.

As I gain experiences, I started to give feedback to other developers. I noticed many solutions are working fine, but they often missed relatively simple fixes or fundamentals, especially on accessibility. It's understandable since they use Frontendmentor for learning purposes.

So I came up with an idea to make a blog series that solve Frontendmentor challenges with fundamental web technologies (e.g. HTML, CSS, and JS). On top of that, I will solve them in a fully accessible way that others can study and reference.

To be honest, I'm not an accessibility expert, but I will learn them along the way by building and writing these articles.

What will we build?

🔗 Github Repository

🔗 Live Demo

I will not go in-depth on styling and markup. I will only focus on things related to accessibility implementation. Please refer to the GitHub repo for the details.

Tools We Use

We are going to use HTML, CSS, and Vanilla Typescript. Don't worry if you aren't familiar with Typescript, you can just ignore the Typescript part as the logic is still the same.

Building the Submission Page

The most important thing on this page is the rating selection. A lot of times, developers instinctively reach out to Javascript when dealing when making this custom selection with either button or div. Both of them work, but it will be weird for screen readers as there is no context when selecting them.

// ❌ Common non-accessible solution
<div>
  <button value="1">1</button>
  <button value="2">2</button>
  <button value="3">3</button>
  <button value="4">4</button>
  <button value="5">5</button>
</div>

Fret not, HTML has a native solution to deal with this kind of solution. Combined with CSS, it's straightforward.

Building an Accessible Rating Selection

Firstly, we need a <form> element as a submission handler. Now, what element fits for rating selection? <input type="radio">. You might think it's wrong since it doesn't come close to the reference, but semantic HTML + CSS can do wonders.

We want the radio to be in a <fieldset> to give group them in a context. We also need a <legend> to title the <fieldset> group. It may seem awkward to have the <legend>, right? In the design there is none, but on the other hand, it's important for assistive technologies.

Removing the styles from <fieldset> is simple, the problem is the <legend>. Fortunately, there is a workaround to hide the legend visually, but still accessible to a screen reader. We can do that using CSS.

Inspired by Tailwind, we can create a class called sr-only or visually-hidden or anything you like.

.sr-only {
  clip: rect(1px, 1px, 1px, 1px);
  clip-path: inset(50%);
  height: 1px;
  width: 1px;
  margin: -1px;
  overflow: hidden;
  padding: 0;
  position: absolute;
}

Here is the markup.

<form>
  <fieldset>
    <legend class="sr-only">Select Rating</legend>
  </fieldset>
</form>

Now, when screen readers enter the fieldset, it will announce the purpose (e.g. "select rating, group").

We can start building the radio itself. Remember to always give a value and couple the input with <label>.

To style it, I will hide the input and style the label only. Also, the input is still keyboard-focusable. Yes, this is why using semantics can help us tremendously. We can check/select an input by clicking its label, as long as the id is correct. Here is the markup.

<form>
  <fieldset>
    <legend class="sr-only">Select Rating</legend>
    <div class="rating-container">
      <div>
        <input type="radio" name="rating" id="rating-1" value="1" />
        <label for="rating-1">1</label>
      </div>
      <div>
        <input type="radio" name="rating" id="rating-2" value="2" />
        <label for="rating-2">2</label>
      </div>
      <div>
        <input type="radio" name="rating" id="rating-3" value="3" />
        <label for="rating-3">3</label>
      </div>
      <div>
        <input type="radio" name="rating" id="rating-4" value="4" />
        <label for="rating-4">4</label>
      </div>
      <div>
        <input type="radio" name="rating" id="rating-5" value="5" />
        <label for="rating-5">5</label>
      </div>
    </div>
  </fieldset>
  <button>Submit</button>
</form>

The trick is we will use input:checked and CSS sibling selector to style the label next to it. Here is an example.

form fieldset input:checked + label {
  background-color: var(--primary-orange);
}

It's all good, but we still missing something. When we navigate using a keyboard, there is no visual indication of what radio we are at.

This is where the focus ring comes into play.

We can add this line of css.

form fieldset input:focus-visible + label {
  outline: 2px solid white;
  outline-offset: 4px;
}

Notice that I use :focus-visible. I use it because I only need it to be visible when we use a keyboard to navigate.

Handle Submission with Javascript.

When using form and semantic HTML we can use a powerful API that many newer developers don't know. It's the FormData API.

We can listen to the submit event on the form and get the form data with FormData. Here is how.

const form = document.querySelector("form") as HTMLFormElement;
form.addEventListener("submit", (e) => {
  e.preventDefault();
  // Make sure it's a form element
  if (!(e.currentTarget instanceof HTMLFormElement)) return;
  // Create a new formData entries containing submitted data
  const formData = new FormData(e.currentTarget);
});

We can get the selected input value from a specific field using its name attribute, in our radio case, its rating. Therefore, we can set our selected rating to the thank you page.

// will return a string of our selected input value
const selectedRating = formData.get("rating");

Building the Thank You Page

Now that the submission is taken care of, we can directly show the thank you page with our result, right? Nope, it's true for a sighted user, but not for screen reader users.

What will happen, then? Let's see a demo.

As you can see, after we submit, the focus is thrown to the top of the page. At the same time, VoiceOver still thinks that we're in the submit button, but the button is gone.

It's a confusing behavior for screen reader users, it feels like we are being carried somewhere when we sleep and wake up wondering how we get there.

A good rule of thumb is to focus on an h1 as screen reader users mostly navigate with headings.

Let's add this line of code to the form listener from before

const mainPage = document.getElementById("rate") as HTMLElement;
const thankPage = document.getElementById("thank") as HTMLElement;
mainPage.classList.remove("active");
thankPage.classList.add("active");
// Select h1 from the thank you page and focus on it
thankPage.querySelector("h1")?.focus();

It's finished but lacks a thing, there is no immediate confirmation to screen reader users if their selection is good or not. To announce something to a screen reader, we can use a live region.

Simply put, a live region is used to announce something that is updated dynamically without page reload, the updated thing may be obvious for most users but not assistive technology.

In the design, there is an element that displays what the user has selected, which is You selected <SELECTED_RATING> out of 5. We want to announce it when the thank you page appears. To do that, we can add a visually hidden live region and insert the text when there is a submission.

Let's add a live region with role="status" and aria-live="polite". It's recommended to add role="status" for compatibility reasons, although aria-live alone is enough.

By setting aria-live="polite", we want the screen reader to announce the text but not disrupt an ongoing announcement.

<div id="rating-status" role="status" aria-live="polite" class="sr-only"></div>

In Javascript, we can dynamically insert the text provided to the selected rating text.

// In the form submit listener
const ratingStatus = document.getElementById("rating-status") as HTMLElement;
ratingStatus.innerText = `You selected ${selectedRating} out of 5`;

Now, when we submit the rating, screen readers will announce the selected rating text.

VoiceOver Paused When There is a Span Inside an Element

In the selected rating element, we use a span to insert a rating dynamically. However, it causes a problem where the VoiceOver will treat the text as segments and pause between them like this.

That is unwanted behavior and bad for a screen reader user's experience. On the internet, the recommendation is to add role="text" to the span that will treat the span as a text. Unfortunately, that doesn't work here.

Thankfully, I found that using role="presentation" works. In my opinion, it's the same as role="text" as they override semantics, but I don't know if it's the right way. Still, better than nothing.

Recap

Wow! Amazingly, you come this far. Thank you so much and I hope you can get something out of this article.

To sum up, here is what we cover:

Build a rating selection with custom radio semantically.
Use Live region to announce important changes.
Hide an element visually, but still accessible to screen readers.
Handling form submissions with FormData API.

Let me know in the comment section if I miss anything.

Webly, Find and Sell Online Webinar Tickets

Fazza Razaq Amiarso — Mon, 05 Dec 2022 14:14:24 +0000

What I built

A marketplace for webinars. Sell webinars ticket for hosts. Find and buy tickets for users.

Category Submission

Search No More

App Link

You can authenticate with an arbitrary email address as long as its format is valid.
https://webly.fzworld.xyz/shop

Demo

Some of data still come from faker-js/faker

Screenshots

Description

As a marketplace, Webly enables you to search and discover online webinars. If you are a webinar host, you can sell tickets for your webinars, whether free or paid.

Link to Source Code

https://github.com/fazzaamiarso/webly

Permissive License

MIT

Background

On the internet, information about webinars is scattered about on many different platforms. In my country, Indonesia, to buy webinar tickets we mostly go to Instagram and contact the admin directly via another messaging platform (e.g. Whatsapp, line).

Why not gather them in one place where we can sell and buy webinar tickets easily? This is where Webly comes into play.

How I built it

UI is deeply inspired by redbubble

Tech Stack:

Let's focus on how I built the search features.

Search bar with autocomplete.

Atlas search comes with autocomplete capability that will helps searching an item easier. The autocomplete recommendation comes from Atlas Search autocomplete aggregation.

Inspired by Linkedin and redbubble search UI, I merged the sellers and webinars autocomplete aggregation pipeline, enabling us to search both of them. To complete it, I add a neat delayed spinner UI coming from Kent C. Dodds blog.

Search Items with Sorting, Filtering, and Pagination.

Atlas search can do a lot of things, especially compound aggregation is powerful when searching a query with many conditions.

I also implement pagination using the skip and limit cursor methods. Although it's not the most performant way, it surely gets the job done.

Improvements

Choose either Prisma or MongoDB native driver (with mongoose, maybe?). Currently, Webly uses mostly Prisma for DB transactions and mongo native driver for the search feature.
As it's focused on building the search features, other core features, such as checkout and user profile are set aside for the time being.
Optimistic UI for a snappier user experience.
Currently, Webly isn't optimized for tablets and small-screen devices.
There isn't a seller dashboard yet, only a storefront with mock data.
Authentication is working, but not fully implemented yet for production.

Additional Resources/Info

Let's Fix It: Can't Use My Own Site

Fazza Razaq Amiarso — Sun, 27 Nov 2022 07:51:00 +0000

You might be wondering what I'm talking about. How could you make a site that you can't even use? What's the point of making it in the first place then? Relax... I'm talking about web accessibility. You can still access my site with a mouse without any problem.

The problem is when you use your keyboard, the main content is totally ignored. Let alone assistive device users (e.g. screen reader), What a mess😩.

That example is only the tip of the iceberg. There are a lot more problems even Lighthouse can't detect, deceivingly leading me to believe that my site is accessible. Fortunately, I got exposed to accessibility before, through videos and articles. I just didn't care enough back then.

So, I'm going to try to solve it and document it in this article. Hoping I can help someone get started.
Let's go!!

For your information, I am using

Remix (React framework)

Tailwind CSS (styling)

NVDA (screen reader)

AxeDevtools and Lighthouse (accessibility testing)

Color Contrast

Color contrast is relatively easy to fix and the most frequently fail on my site. However, it can be tricky to fix when you have to adhere to a brand color that doesn't have enough contrast.

On my site, I fix it by adjusting the color shade. A piece of advice on color contrast is to use off-white and off-black colors. The reason is that high contrast can cause eye strain during a long reading period.

Bypass Block or Skip Link

A need for skip link arises from screen reader users that use keyboards for navigation. Every page changes, user's keyboard focus is thrown to the top of the document, which means users must traverse through your site navigation to access the main content. It is tedious and repetitive.

The solution is to create a hidden link placed before the navigation, which is shown on focus by the keyboard. The link will navigate users straight to the place you intended, most likely the main content.

Here is my implementation

import { Link } from "remix" //same "Link" from react-router-dom
<body>
<Link className="fixed left-1/2 top-0 z-30  -translate-x-1/2 -translate-y-full bg-white px-3 py-1 underline  transition-transform focus:translate-y-0"
        to="#main">
  Skip to content
</Link>
<header>..</header>
...
<main id="main" >
//omitted for brevity
</main>

Page must contain a level-one heading (h1)

This rule is considered best practice. h1 allows screen readers to skip navigation directly to it using a keyboard shortcut. If there is no h1, screen reader users must listen to more of the site content to understand the site structure which wastes a lot of valuable time.

To solve the problem, put an h1 tag before the main content. You must only put a singleh1 on a page.

All Page Content Must be Contained by Landmarks

This rule is considered best practice. Landmarks allow screen reader users to navigate your page using landmarks. Landmark is high-level sectioning of your contents either by using semantic HTML or adding a role attribute to an HTML element. Some landmark examples are <main>, <header>, <form> and <footer>. Content outside a landmark is difficult to find and the purpose may be unclear.

On my site, I got a few of these problems. To fix it, I move all the content into landmarks that it supposes to belong.

Search Input Live Region

Search input has no indication of state changes for screen reader users. Therefore, when they are searching, they won't know whether the site is busy searching, done searching, or even fail.

To improve the search experience, I added a live region only available to screen readers. The live region will announce a message based on the search state.

 <span className="sr-only" aria-live="polite" role="status">
          {fetcher.state === 'submitting' || fetcher.state === 'loading'
            ? 'Searching...'
            : fetcher?.data?.length >= 0
            ? `${fetcher.data.length} songs found`
            : ''}
        </span>

Focus on Heading on Page Changes

On page changes, usually, we want to give focus to a focusable element that leads to action. For example, on the search page, we give the initial focus to the search input element.

The focus enables users to:

start typing immediately
save time from navigating

As a bonus, screen reader announce whatever we focus on, which give alert to visually impaired users on page change. However, there are some pages with no focusable element. To handle the problem, I created a useFocusToHeading hook.

import { useEffect } from 'react';
export const useFocusToHeading = () => {
  useEffect(() => {
    const headingElement = document.querySelector('h1');
    headingElement.focus();
  }, []);
};

The hook will find an h1 element on the page, then give it a focus. An important note, h1 isn't inherently focusable. So, we have to give h1 a tabindex='-1' attribute to make it focusable programmatically.

Pagination with Load More Button

While I was testing the pagination feature, I noticed a problem that can be detrimental to the user experience. When I click the load more button, the focus stays on the button even after the content is updated. For screen reader and keyboard users, the experience is annoying.

I thought it is better to focus on the first loaded content on the list, which means :

screen readers will announce the new content in the list.
keyboard users will be able to immediately traverse through the new content.

Hence, I created yet another hook called useFocusOnFirstLoadedContent.

const useFocusOnFirstLoadedContent = list => {
    useEffect(() => {
      if (list.length === 0 || !list) return;
      const listLengthDivided = Math.floor(list.length / 10) - 1;
      const contentToFocus =
        listLengthDivided === 0
          ? document.getElementById('link-0')
          : document.getElementById('link-' + String(listLengthDivided * 10 + 1));
      contentToFocus?.focus();
    }, [list]);
  };

Login and Registration Form

Initially, I handle my site login and registration form in a /login route. I use a fieldset with two radio buttons and a react state to switch between login and registration. I thought it was good as I didn't really care about form.

Ohh.. how wrong I was when I started researching how to make a form accessible.

Problem and Solution

`<Form>` Isn't Identified as a Landmark in the Accessibility Tree

The <Form> is identified as a 'section' which means screen readers can't tell users that they are inside a form. Users will arrive at a form field without knowing what the field's purpose is.

Fortunately, I just need to label the form with the h1 on the page.

import { Form } from "remix"
 <h1 id="form-name">Login</h1>
 <Form aria-labelledby="form-name" method="post">

aria-labelledby forms a relation between h1 and <Form>. Now, <Form> will have the name 'Login' and screen reader can access the form landmark.

Separating Login and Registration

When testing the login page with NVDA, It was confusing to switch forms using radio buttons.

Form type is ambiguous and it is hard to tell what the radio buttons' purpose is. So, I delete the radio buttons and create a new form on the /registration route.

Now, another problem emerges. How to switch between those two pages? Easy enough, I put a link next to the usual login page phrase 'Already have an account?' which will be placed under the submit button. However, after reading Form Design Patterns by Adam Silver, It's better to put the phrase before the form. Why? because visually impaired people who use screen readers will expect that the submit button marks the end of the form. Also, it tells them in advance that there are options.

Input Field Placeholder

In Form Design Patterns, there is a precaution on giving hints to users with placeholder. As you know, developers and designers love to use placeholder on an input field as a hint.

Things to consider when using placeholder:

Placeholder text contrast is deliberately lower, which can cause readability issues. If we increase the text contrast, it can be mistaken as an input.
Placeholder will be hidden when the field is focused. If we use placeholder as a hint (e.g. 'Password must be 8 characters long'), users can forget the hint as they are typing, forcing them to clear the input field. Especially for cognitively disabled users, remembering hints can be hard.
Placeholder text longer than the input field will be cut off to accommodate the width of the input field. For example, a responsive page that has an input field's width relative to the viewport's width.

In Form Design Patterns, Adam Silver suggested to remove the placeholder and put the hint inside the input's <label>, under the label's text as a <span>.

<label htmlFor='password' className='flex flex-col items-start'>
<span>Password</span>
<span>Must be at least 8+ characters</span>
</label>
<input type='text' id='password' />

NVDA will read the input field as 'Password, Must be at least 8+ characters, Input field, blank'

Initially, the solution was great because the hint is described upfront and as a bonus, the input's tap area is wider. But, I found it strange because <label> that contains too much information can be a hindrance to users.

Eventually, I choose an alternative given by the author which is to place the hint under the <label>, then connect the hint using aria-describedby.

<label aria-describedby='password-hint' htmlFor='password'> Password</label>
<p id='password-hint'>Must be at least 8+ characters</p>
<input type='text' id='password' />

The benefit of separating the hint from the label is that the label is more concise. Usingaria-describedby means that the hint will be read at the end as extra information.

NVDA will read the input field as 'Password, Input field, blank, Must be at least 8+ characters'

Form Validation Error

It is common to place an error message under the problematic field for validation. At first, that was enough. It turns out there is a lot more to handle an error message.

Here are considerations when creating an error message:

Give the invalid input field an aria-invalid attribute of 'true' on error.
Considering users with color blindness, we cannot rely on color and text alone as an error message. Colorblind users won't notice the difference immediately and might be confused. It is best to add an icon that indicates a warning (e.g. ⚠) to give the error message more visual representation.
Considering screen reader users, there is no way for them to get informed of the error message currently. My preferred way is to connect the error message with its input field using aria-errormessage which works the same as aria-describedby.
For the error message itself, add aria-live='polite' so screen reader users are informed when the invalid field's error message content is shown or changes.

Here is an example implementation.

import { ExclamationIcon } from '@heroicons/react/solid';
//a basic example
 <input
        name='email'
        id='email'
        type='email'
        required={true}
        aria-describedby='email-hint'
        aria-errormessage='email-error'
        aria-invalid={fieldError ? 'true' : 'false'}
      />
 <p aria-live="polite" role="status" id='email-error'>
    <ExclamationIcon className="h-4" aria-hidden="true" />
<span>Email is already registered<span>
    </p>

Input Focus Management On Error

Focus management is an important part that is often overlooked by developers. I felt guilty for not implementing focus management before I learn accessibility. Focus management is particularly helpful for screen reader and keyboard users.

As an example, on validation error, we want the user's focus to be on the invalid field, so they can fix the error right away. Proper focus ensures a comfortable user experience.

On my site, I want to focus on the first invalid field from the top. Therefore, I created a useFocusOnError hook.

import { useEffect } from 'react';
export const useFocusOnError = (ref, fieldErrors) => {
  useEffect(() => {
    const form = ref.current;
    if (!form || !fieldErrors) return;
    for (const fieldName of Object.keys(fieldErrors)) {
      if (fieldErrors[fieldName]) {
        const errorField = document.getElementById(fieldName);
        errorField?.focus();
        break;
      }
    }
  }, [ref, fieldErrors]);
};
...
//fieldErrors example
const fieldErrors  = {
password: 'Password must contains at least 8 characters', //there is an error
email: undefined //no error
}

As parameters, the hook received ref from a form and fieldErrors object. fieldErrors is a response from the server that contains all the fields with its error message (if any). When invoked, the hook will loop through fieldErrors, then focus on the first invalid field it came across.

Form's Final Look

Post Card Component

On my site, this component is the biggest problem as it is unreachable. By unreachable, I mean screen reader and keyboard users. I am shocked the first time I tested it, the keyboard tabbing just skip over it from the navbar straight to the footer.

Making an accessible card is notorious for its trickiness, especially a card with a lot of interactive elements in it. On the internet, there is various kind of solutions and all of them are still debatable.

In my case, the card contains two interactive elements inside it, a link and a menu. I couldn't find any concrete solutions on the internet. So, I just go to the best of my ability and knowledge.

Problems and Solutions

Card Is Not Tabable by Keyboard

Initially, I just want the link inside the card to be tabable. But, I figure that I also want screen readers to read other content inside the card. The solution is to simply add tabindex='0' to the card container (e.g. li and div). Now, we can tab through each card individually using the keyboard.

The Card's Link Is a Card too

Here is the tricky part, this particular card contains an image and text linked to the song's feed. On the internet, a lot of solutions use a as a container. It works well for the interactivity and click area.

But, it will lose the semantics by wrapping block-level elements such as div and p, in an a which is an inline element.

To fix the problem, I wrap the card contents in a div and the link itself goes to the card's title. I use a 'hack' by manipulating the a's :after pseudo-class to make the whole card a clickable area.

import { Link } from 'remix'
 <div className="relative mb-4 flex items-center gap-4 rounded-sm shadow-md ring-1 ring-slate-200 transition-all focus-within:ring-2 focus-within:ring-gray-300 hover:cursor-pointer hover:ring-2 hover:ring-gray-300">
          <img
            src={post.thumbnail}
            role="presentation"
            height="64px"
            width="64px"
            className="h-16"
          />
          <div className="pr-4">
            <Link
              to={`/track/${post.track_id}`}
              aria-label={`Go to ${post.title} by ${post.artist} feed`}
              className="block text-sm font-semibold after:absolute after:inset-0 after:z-10"
            >
              {post.title}
            </Link>
            <p className="text-xs">{post.artist}</p>
          </div>
        </div>

Conclusion

Learning and Improving accessibility helped me to become a more empathetic developer. It also makes my site robust and usable for everyone.

Implementing accessibility is fun. You don't need a lot to get started and it just works sometimes. I will continue to implement accessibility on all of my sites.

Feel free to drop a message if you think there is any misleading or incorrect information. I appreciate any feedback and suggestions.

Thank You for reading this blog post!!

What I learned from Building Invoys, an Open Source Invoice Management App

Fazza Razaq Amiarso — Sun, 13 Nov 2022 20:34:51 +0000

Originally posted on https://fazzaamiarso.me/projects/invoys/

Inspiration

On the internet, a lot of open-source Invoice management apps are built with Laravel. As a Javascript developer, I want to build the "React Solution" for devs that are familiar with React and Javascript.

Features

Freely customize the code.
Create invoice and manage clients.
Send Invoice link to email.
Download invoice to PDF.
Export datas to CSV.
Invite team members.
Magic Link Authentication.

Techs Used

Invoys is bootsrapped with create-t3-app which based on Next.js.

Next.js + Typescript
TRPC
Next-auth (Email Magic Link) with Nodemailer
Prisma
Planetscale (MySQL)
Tailwind CSS
Courier
Docker
Cypress + Vitest

Project Gallery

Demo

Challenges

Defining schema in Prisma and Making the Entity Relationship Diagram

Database is not my strong side although I have learned a bit before, my understanding is still hazy. I kept hitting foreign Key problem and ended up finding out that the problem is with the Prisma Planetscale support.

Planning and designing ERD is not an easy task for me, such as thinking about the relationship of tables, how is the best to connect fields, when to migrate or push a schema, and of course planning the architecture of the app.

Setup a Proper Open Source Repository

This is my first time setting up a repo in github properly. When using other's project, I took it for granted and didn't realize the efforts put into making a good repo for others to contribute.

Writing documentation id unexpectedly challenging as we must make sure contributors able to understand and contribute to our project properly regardless of environment. Setting up linting and styling rules is tedious because there are lot of configurations, rules, conventions, and opinions that make it hard to just implement. Now, I get it why developers created templates and plugins.

Creating and Manipulating Tables

In this project, I'm building tables and I need to make some of its row as an input field. After thinking and evaluating, it's not as easy as I would like, there a lot of states that changes often and need syncrhronization with server. Structuring the table content was pretty easy, the hard part comes when I need to manipulate and extract datas from the table. Fortunately, I found out about tanstack table that helped with managing datas. As a note, the API was kind of confusing for me, but it starts to make sense now.

Designing UI/UX

First of, I'm bad at design although decent at basic UI fundamentals. Picking colors and making things looking good is not my forte. So, I spent a lot of time searching for refrences and ideas on the internet.

Testing Complex Interface

Testing a fully authenticated and complex interactions is very difficult. I was stuck on working around network requests and database while E2E testing.

Testing Email Magic Link. I know how to test this flow, but it's confusing as I don't know how to verify the verification email in an automated testing environment.

Continuous Integration with Github Action

Another point of confusion was running the tests in CI. I had a rough idea on how to do it. Oh boy.. it's quite a journey until I can safely build the workflow environment and run all checks. It also come with some frustrated git commit message (sorry for future contributor 😅).

What I've Learned

Documenting project

Writing about how your projects built or works clearly is crucial, I had to revise and rethink a lot of time. Taking screenshots or GIF of UI/UX can boosts the understanding of your upcoming contributor or user. Guide users on steps to contribute and setup the project locally.

Managing Server State and Client State

By building things, I finally making sense what Kent C. Dodds meant in this blog post. A lot of times, data that we worked on only make sense in server side. Copying server state to client can lead to bugs, such as state out of sync. Separating both of them, leads to a more robust app.

Utilize Docker

I thought Docker wasn't a necessary technology for me to learn. Thankfully, I've been proven wrong as Docker helped me to develop with many kind of technologies. Especially for this project, docker helped to build isolated local and test database which enables me to test without mocking a database connection. I also learned that Github Actions is basically running a docker container, which blows my mind.

Testing with Cypress and Vitest

With the complexity of the project, I was able to learn to test users flows with all the interactions and network requests. Initially, I was testing with Playwright, but I couldn't get around on mocking login session. Frustrated, I switch to Cypress and still have the same problem, but I found a workaround that I am proud of.

Also, the environment needed in testing is different from development so it kinda throw me off, especially on mocking the database and mocking trpc's endpoint is still hard to do. I managed separate the database for different environments by switching from hosted database in Planetscale to Docker and it worked greatly.

Honestly, unit testing is not really hard, granted that I didn't test all of the components in this project, I still need to look into it. A benefit of unit testing that I really like is when I want to refactor a certain function, I am able to get feedback and catch bugs quickly.

Continuous Integration (CI).

I learned to setup testing suite in github action which I've given up before. Thankfully, I kept going for this project maintainablity. I learned a lot from Kent C. Dodds CI flow.

Tables and Virtualization

I never thought that table would be a beast to deal with. I think it's also because I use tanstack-table which is a headless library that gives me APIs that gives a lot of control, but require more setup and markup. I learned on how to manage states on table.

Virtualization is necessary as the table grows which can cause performance problem with loading and rendering a lot of items on a page.

Integrating with 3rd Party Vendor

This project integrates Courier API to send invoices to users email. I have to learn the Courier platform, connecting with the project, and making sure it works without a problem.

Building UI/UX

I learned a lot on building UI/UX by watching Gary Simon's Design Course. Watching him fixing UI and give feedback live gives me insights on how to think about designing accessible UI/UX that looks good. Designing an inclusive UX is also important to make sure users don't get confused while using an app. I took a lot of design inspiration from Tailwind UI.

Takeaway

An important takeaway is just try to build it first, if stuck then put it off for later. Before that, I was doing too much calculations before trying something (e.g. library), it turns out by trying I can learn and fail much faster.

Thank you for reading! Hope you become a contributor for Invoys!

DEV Community: Fazza Razaq Amiarso

My Journey as a React.js Learning Facilitator for IDCamp 2023

Why I Became a Facilitator

Challenges and Solutions

Planning and Creating a Mentoring System

Communicating Effectively with Mentees

Encouraging Active Participation

Tracking and Encouraging Mentee Progress

Teaching and Explaining Coding Concepts Live

Engaging Students in Live Sessions

Mentees Growth

The Rewards

Galleries

Looking Forward

Hey!Sound: Upload and Vote for the Best Audios on the Internet

What I Built

Useful Links

Platform Primitives

Filtering Blobs Metadata

Retrieving Audios Blob

Store Voting Data

Add TOC with Scroll Spy in Astro

Create the Component

Scroll Spy with Intersection Observer

Add an Observer Callback Function

Observer Option

Observe the Headings

How to Send Invoice and Add Payment Reminder in Next.js with Courier API

Background

Pre-requisites

Goals

Part 1: Setup Courier Platform

Part 2: Send Invoice to Email

Backend

Frontend

Part 3: Send Payment Reminder

Part 4: Cancel a reminder

Part 5: Error Handling

Part 6: Go To Production

Conclusion

About the Author

Quick Links

Learn A11y with FrontendMentor: Interactive Pricing

Introduction

What are we building?

Pricing Range Slider

Styling

How to Fill the Track?

Clearer Slider Value with aria-valuetext

Billing Frequency Switch

Building a Switch with Radio Input?

Focus Ring

Discount Text

Bonus: Format Number and Currency with Intl

Recap

Learn A11y with FrontendMentor: Card Details

Introduction

What we are building?

Working with decorator element

Should We Uppercase in CSS or HTML?

Building an Accessible Form

Number Input Field

Should We Provide an Autocomplete Attribute?

Grouping Fields

Hinting an Input Format with a Placeholder

Handling Validation Error

Invalid Form

Announcing the Error Message

Improving the Design's Error Message

Managing Focus

Validate Input with Constraint Validation API

Recap

Learn A11y with FrontendMentor: Interactive Rating

Series Introduction

What will we build?

Tools We Use

Building the Submission Page

Building an Accessible Rating Selection

Handle Submission with Javascript.

Building the Thank You Page

Clearer Slider Value with `aria-valuetext`

Bonus: Format Number and Currency with `Intl`

Should We Provide an `Autocomplete` Attribute?

`<Form>` Isn't Identified as a Landmark in the Accessibility Tree