1 of 100

DUKE

Site Navigation

Navigate my docs

Udemy

https://www.udemy.com/course/react-and-typescript-build-a-portfolio-project

Site Navigation

Multi Step Forms

Jira Tickets

DNT-2860 Go Green Calculator

New Features

New Simple Calculator Input Warning And Block Explanation**

The need for this ticket derives from a fictional unit of energy duke created called a block which is "100 kWh of 'green' energy". Because a block requires whole-number outputs that necessitates a minimum input value; which arguably needs to be explained to the user, and if the user fails to heed the instructions... have the warning change color to red if they input a lower number.

DNT-2843 EVCalculator

Controls:

Name

Description

Default

Control

inputs*

DNT-2657 Lists must be contained within semantically correct containers

src/components/MultiStepForm/components/ConfirmationStep/index.tsx

Description

Notes:

The information about call-time preference is visually displayed as a description list. In this case, it's a question and then an answer. This content is not marked up as a list.

When content is presented as a list, or a clearly related collection of items, marking it up using semantic list HTML elements helps assistive technology users to navigate and orient themselves within a page of content. Screen reader users can navigate to (or over) lists when they are correctly marked up. Also, when reading content in a list, assistive technology provides rich information about how long the list is and where the user is in the list. For example: "List, 9 items, Home, 1 of 9, About, 2 of 9".

This particular list is confusing because it is displayed even when there is no time indicated, like when a user chooses email as the preferred method of communication.

DNT-2658 Components must receive focus in an order that preserves meaning and operability

DNT-2658

Components must receive focus in an order that preserves meaning and operability

Docs

//Calculator/index.tsx

import React from "react";
import Input from "./inputComponents/Input";
import Stepper from "./inputComponents/Stepper";
import Slider from "./inputComponents/Slider";

const Calculator = () => (
  <section className="px-16 md:px-24 py-32 md:py-48">
    <div className="mb-48 items-center flex">
      <Slider
        prompt="Prompt goes here"
        defaultVal="88888"
        min="0"
        max="100000"
        label="Number Slider Title"
      />
    </div>
    <div className="flex flex-1">
      <Stepper prompt="Prompt goes here" defaultVal="1" />
      <Input
        prompt="Prompt goes here"
        defaultVal="500"
        label="per month"
        isInDollars={true}
      />
    </div>
  </section>
);

export default Calculator;

//src/components/Calculator/outputComponents/YearlySavings.tsx

import { YearlyOutputProps } from "../types";

const avgDaysInMonth = 30.437;
const avgDaysInYear = 365.25;

const formatMoney = (money: number) => {
  const roundedNum = Math.round(money * 100) / 100;
  const arr = roundedNum.toLocaleString().split(".");
  const cents = `${arr[1] || ""}00`.slice(0, 2);
  const dollars = arr[0];
  return {
    dollars,
    cents,
    full: `$${dollars}.${cents}`,
  };
};

const YearlySavings = ({
  dailySavings = 0,
  headline = "Total Yearly Savings",
  monthlyText = "Monthly Savings",
  dailyText = "Daily Savings",
  description,
}: YearlyOutputProps) => {
  const annual = formatMoney(dailySavings * avgDaysInYear);
  const monthly = formatMoney(dailySavings * avgDaysInMonth);
  const daily = formatMoney(dailySavings);

  return (
    <div>
      <h4 className="text-blue text-xl-fixed">{headline}</h4>
      {/* need to adjust line height to vertically top align */}
      <p
        className="text-blue my-12 text-2xl-fixed align-top"
        style={{ lineHeight: "55px" }}
      >
        $
        <span className="text-3xl-fixed align-top leading-none">
          {annual.dollars}
        </span>
        {`.${annual.cents}`}
      </p>
      <div className="flex flex-row justify-center">
        <div className="border-r px-32 border-gray">
          <p
            className="text-blue align-top text-lg-fixed"
            style={{ lineHeight: "25px" }}
          >
            $<span className="text-xl-fixed align-top">{daily.dollars}</span>
            {`.${daily.cents}`}
          </p>
          <p className="text-gray-dark text-xs">{dailyText}</p>
        </div>
        <div className="px-32">
          <p
            className="text-blue align-top text-lg-fixed"
            style={{ lineHeight: "25px" }}
          >
            $<span className="text-xl-fixed align-top">{monthly.dollars}</span>
            {`.${monthly.cents}`}
          </p>
          <p className="text-gray-dark text-xs">{monthlyText}</p>
        </div>
      </div>
      {description && (
        <p className="mt-32 text-gray-dark text-md">{description}</p>
      )}
    </div>
  );
};

export default YearlySavings;

//src/components/Calculator/test.tsx

import "@testing-library/jest-dom";
import Input from "src/components/Calculator/inputComponents/Input";
import Slider from "src/components/Calculator/inputComponents/Slider";
import YearlySavings from "./outputComponents/YearlySavings";
import { renderWithCTX, screen, fireEvent } from "src/lib/testWrappers";

const props: Parameters<typeof Input>[0] = {
  prompt: "Current Gas Price",
  defaultVal: "3.12",
  label: "per gallon",
  isInDollars: true,
};

describe("calculator input", () => {
  it("should render", () => {
    renderWithCTX(<Input {...props} />);
    const input = screen.getByRole("textbox", {
      name: `${props?.prompt} ${props?.label}`,
    });
    expect(input).toBeInTheDocument();
    expect(input).toHaveAttribute("value", props.defaultVal);
  });
  it("should prefix with $ if applicable", () => {
    const { rerender } = renderWithCTX(<Input {...props} />);
    let currency: HTMLElement | null = screen.getByText(/\$/i);
    expect(currency).toBeInTheDocument();
    rerender(<Input {...props} isInDollars={false} />);
    currency = screen.queryByText(/\$/i);
    expect(currency).not.toBeInTheDocument();
  });
});

describe("calculator slider input", () => {
  const props = {
    prompt: "How many miles do you drive daily?",
    defaultVal: "160",
    label: "Daily Miles",
    min: "0",
    max: "320",
    step: "1",
  };
  it("should render", () => {
    renderWithCTX(<Slider {...props} />);
    const slider = screen.getByRole("slider", {
      name: `${props.prompt} ${props.label}`,
    });
    const input = screen.getByRole("textbox", {
      name: `${props.prompt} ${props.label}`,
    });
    const label = screen.getByText(/daily miles/i);
    const heading = screen.getByRole("heading", {
      name: /how many miles do you drive daily\?/i,
    });
    expect(slider).toBeInTheDocument();
    expect(input).toBeInTheDocument();
    expect(label).toBeInTheDocument();
    expect(heading).toBeInTheDocument();
  });
  it("should default to midpoint between min and max when defaultVal is missing", () => {
    renderWithCTX(<Slider {...props} defaultVal="" min="100" max="300" />);
    const slider = screen.getByRole("slider", {
      name: `${props.prompt} ${props.label}`,
    });
    expect(slider).toHaveAttribute("value", "200");
  });
  it("should keep the same slider and text input values", () => {
    renderWithCTX(<Slider {...props} />);
    const slider = screen.getByRole("slider", {
      name: `${props.prompt} ${props.label}`,
    });
    const input = screen.getByRole("textbox", {
      name: `${props.prompt} ${props.label}`,
    });
    // slider changes input
    fireEvent.change(slider, { target: { value: 28 } });
    expect(input).toHaveAttribute("value", "28");
    // input changes slider
    fireEvent.change(input, { target: { value: 140 } });
    expect(slider).toHaveAttribute("value", "140");
  });
});

describe("yearly savings output", () => {
  const props = {
    headline: "Yearly Savings",
    monthlyText: "Monthly Savings",
    dailyText: "Daily Savings",
    dailySavings: 2.22,
  };
  it("should render", () => {
    renderWithCTX(<YearlySavings {...props} />);
    const heading = screen.getByRole("heading", { name: props.headline });
    const daily = screen.getByText(props.dailyText);
    const monthly = screen.getByText(props.monthlyText);
    expect(heading).toBeInTheDocument();
    expect(daily).toBeInTheDocument();
    expect(monthly).toBeInTheDocument();
  });
  it("should properly display rounded monetary amounts", () => {
    renderWithCTX(<YearlySavings dailySavings={7.998} />);
    const dollars = screen.getByText("8");
    const cents = screen.getByText(/\$\.00/i);
    expect(dollars).toBeInTheDocument();
    expect(cents).toBeInTheDocument();
  });
});

// Stepper Test.tsx



import '@testing-library/jest-dom';
import Input from 'src/components/Calculator/inputComponents/Input';
import Slider from 'src/components/Calculator/inputComponents/Slider';
import YearlySavings from './outputComponents/YearlySavings';
import { renderWithCTX, screen, fireEvent } from 'src/lib/testWrappers';

const props: Parameters<typeof Input>[0] = {
  prompt: 'Current Gas Price',
  defaultVal: '3.12',
  label: 'per gallon',
  isInDollars: true,
};

describe('calculator input', () => {
  it('should render', () => {
    renderWithCTX(<Input {...props} />);
    const input = screen.getByRole('textbox', {
      name: `${props?.prompt} ${props?.label}`,
    });
    expect(input).toBeInTheDocument();
    expect(input).toHaveAttribute('value', props.defaultVal);
  });
  it('should prefix with $ if applicable', () => {
    const { rerender } = renderWithCTX(<Input {...props} />);
    let currency: HTMLElement | null = screen.getByText(/\$/i);
    expect(currency).toBeInTheDocument();
    rerender(<Input {...props} isInDollars={false} />);
    currency = screen.queryByText(/\$/i);
    expect(currency).not.toBeInTheDocument();
  });
});

describe('calculator slider input', () => {
  const props = {
    prompt: 'How many miles do you drive daily?',
    defaultVal: '160',
    label: 'Daily Miles',
    min: '0',
    max: '320',
    step: '1',
  };
  it('should render', () => {
    renderWithCTX(<Slider {...props} />);
    const slider = screen.getByRole('slider', { name: `${props.prompt} ${props.label}` });
    const input = screen.getByRole('textbox', { name: `${props.prompt} ${props.label}` });
    const label = screen.getByText(/daily miles/i);
    const heading = screen.getByRole('heading', { name: /how many miles do you drive daily\?/i });
    expect(slider).toBeInTheDocument();
    expect(input).toBeInTheDocument();
    expect(label).toBeInTheDocument();
    expect(heading).toBeInTheDocument();
  });
  it('should default to midpoint between min and max when defaultVal is missing', () => {
    renderWithCTX(<Slider {...props} defaultVal="" min="100" max="300" />);
    const slider = screen.getByRole('slider', { name: `${props.prompt} ${props.label}` });
    expect(slider).toHaveAttribute('value', '200');
  });
  it('should keep the same slider and text input values', () => {
    renderWithCTX(<Slider {...props} />);
    const slider = screen.getByRole('slider', { name: `${props.prompt} ${props.label}` });
    const input = screen.getByRole('textbox', { name: `${props.prompt} ${props.label}` });
    // slider changes input
    fireEvent.change(slider, { target: { value: 28 } });
    expect(input).toHaveAttribute('value', '28');
    // input changes slider
    fireEvent.change(input, { target: { value: 140 } });
    expect(slider).toHaveAttribute('value', '140');
  });
});

describe('yearly savings output', () => {
  const props = {
    headline: 'Yearly Savings',
    monthlyText: 'Monthly Savings',
    dailyText: 'Daily Savings',
    dailySavings: 2.22,
  };
  it('should render', () => {
    renderWithCTX(<YearlySavings {...props} />);
    const heading = screen.getByRole('heading', { name: props.headline });
    const daily = screen.getByText(props.dailyText);
    const monthly = screen.getByText(props.monthlyText);
    expect(heading).toBeInTheDocument();
    expect(daily).toBeInTheDocument();
    expect(monthly).toBeInTheDocument();
  });
  it('should properly display rounded monetary amounts', () => {
    renderWithCTX(<YearlySavings dailySavings={7.998} />);
    const dollars = screen.getByText('8');
    const cents = screen.getByText(/\$\.00/i);
    expect(dollars).toBeInTheDocument();
    expect(cents).toBeInTheDocument();
  });
});



describe('calculator slider input', () => {
  const props = {
    prompt: 'How many miles do you drive daily?',
    defaultVal: '160',
    label: 'Daily Miles',
    min: '0',
    max: '320',
    step: '1',
  };
  it('should render', () => {
    renderWithCTX(<Slider {...props} />);
    const slider = screen.getByRole('slider', { name: `${props.prompt} ${props.label}` });
    const input = screen.getByRole('textbox', { name: `${props.prompt} ${props.label}` });
    const label = screen.getByText(/daily miles/i);
    const heading = screen.getByRole('heading', { name: /how many miles do you drive daily\?/i });
    expect(slider).toBeInTheDocument();
    expect(input).toBeInTheDocument();
    expect(label).toBeInTheDocument();
    expect(heading).toBeInTheDocument();
  });
  it('should default to midpoint between min and max when defaultVal is missing', () => {
    renderWithCTX(<Slider {...props} defaultVal="" min="100" max="300" />);
    const slider = screen.getByRole('slider', { name: `${props.prompt} ${props.label}` });
    expect(slider).toHaveAttribute('value', '200');
  });
  it('should keep the same slider and text input values', () => {
    renderWithCTX(<Slider {...props} />);
    const slider = screen.getByRole('slider', { name: `${props.prompt} ${props.label}` });
    const input = screen.getByRole('textbox', { name: `${props.prompt} ${props.label}` });
    // slider changes input
    fireEvent.change(slider, { target: { value: 28 } });
    expect(input).toHaveAttribute('value', '28');
    // input changes slider
    fireEvent.change(input, { target: { value: 140 } });
    expect(slider).toHaveAttribute('value', '140');
  });
});

describe('yearly savings output', () => {
  const props = {
    headline: 'Yearly Savings',
    monthlyText: 'Monthly Savings',
    dailyText: 'Daily Savings',
    dailySavings: 2.22,
  };
  it('should render', () => {
    renderWithCTX(<YearlySavings {...props} />);
    const heading = screen.getByRole('heading', { name: props.headline });
    const daily = screen.getByText(props.dailyText);
    const monthly = screen.getByText(props.monthlyText);
    expect(heading).toBeInTheDocument();
    expect(daily).toBeInTheDocument();
    expect(monthly).toBeInTheDocument();
  });
  it('should properly display rounded monetary amounts', () => {
    renderWithCTX(<YearlySavings dailySavings={7.998} />);
    const dollars = screen.getByText('8');
    const cents = screen.getByText(/\$\.00/i);
    expect(dollars).toBeInTheDocument();
    expect(cents).toBeInTheDocument();
  });
});

Description Lists

Using description lists

Important Information about Techniques

See Understanding Techniques for WCAG Success Criteria for important information about the usage of these informative techniques and how they relate to the normative WCAG 2.1 success criteria. The Applicability section explains the scope of the technique, and the presence of techniques for a specific technology does not imply that the technology can be used in all situations to create content that meets WCAG 2.1.

Applicability

HTML and XHTML

This technique relates to (Sufficient when used with ).

Description

The objective of this technique is to provide the description of names or terms by presenting them in a description list. The list is marked up using the dl element. Within the list, each term is put in a separate dt element, and its description goes in the dd element directly following it. Multiple terms can be associated with a single description, as can a single term with multiple descriptions, provided that semantic sequence is maintained. The title attribute can be used to provide additional information about the description list. Usage of description lists ensures that terms and their descriptions are semantically related even as presentation format changes, as well as ensuring that these terms and descriptions are semantically grouped as a unit.

Description lists are easiest to use when the descriptions are ordered alphabetically. A common use for description lists is a glossary of terms.

NOTE

In HTML5 the name "Description list" was introduced. In previous versions these lists were referred to as "Definition lists".

Examples

Example 1

A list of descriptions of nautical terms used on a Website about sailing.

Resources

Resources are for information purposes only, no endorsement implied.

Related Techniques

Tests

Procedure

For any set of terms and their associated descriptions:

Check that the list is contained within a dl element.
Check that each term in the list being described is contained within a dt element.
Check that when there is more than one term that shares the same decription that the dt

Expected Results

All checks above are true.

DNT-2423 Throttle scroll event listeners

    // TODO Throttle event listeners
    window.addEventListener('scroll', handleScroll, { passive: true });

    return () => {
      window.removeEventListener('scroll', handleScroll);
    };
  }, []);

  if (suppressNav || !hasSubPages) {
    return null;
  }

See: src/components/SecondaryNav/index.tsx - L:99

We probably don't need event fired for every single scroll.

Secondary Nav

/* eslint-disable complexity */
/* eslint-disable max-lines */
import React

Throtteling Event Listeners

Throttle

Using Throttling and Debouncing with React hooks - DEV Community

Excerpt

Throttling and debouncing techniques has been in use for past many years in javascript. In this post I'd like to share my knowledge on how we can use throttle and debounce functions with help of react hooks.

Consider below example with two routes / and /count rendering respective components.

Throttling Example with useEffect

Suppose we need to subscribe a scroll event on Count component on its mount and just increment the count on every scroll event.

Code without using throttle or debounce techniques will be like:

Suppose in practical applications you need to use throttle and wait for every 100ms before we execute increaseCount. I have used the lodash throttle function for this example.

Wait, no need to hurry. It will work if you are at /count route. The increaseCount function will be throttled and will increase the count after 100ms of intervals.

But as you move to the / route to render the Home component and unmount the Count component, and start scrolling on home page, you will notice a warning in console which warns about memory leak. This is probably because the scroll event was not cleaned properly. The reason is _.throttle(increaseCount, 100) is called again during unmount and returns another function which does not match that created during the mount stage. What if we create a variable and store the throttled instance.

like this

But it has problem too. The throttledCount is created on every render, which is not at all required. This function should be initiated once which is possible inside the useEffect hook. As it will now be computed only once during mount.

Debounce Example using useCallback or useRef

Above example is pretty simple. Let's look at another example where there is an input field and you need to increment the count only after user stops typing for certain time. And there is text which is updated on every keystroke which re renders the component on every input.

Code with debounce:

This will not work. The count will increase for every keystroke. The reason behind is that on every render, a new debouncedCount is created. We have to store this debounced function such that it is initiated only once like that in useEffect in above example. Here comes use of useCallback. useCallback will return a memoized version of the callback that only changes if one of the dependencies has changed - React docs Replace

with

and it will work. Because this time the function is evaluated only once at the initial phase.

Or we can also use useRef by doing this

One should always keep in mind that every render call of react functional component will lead to expiration of local variables and re-initiation unless you memoize them using hooks.

DNT-2785

/info/unindexed/dpa-conversion-business

The Image Slideshow component seems to have shrunk after JSS conversion. See it here: https://scprod-cms.duke-energy.com/info/unindexed/dpa-conversion-business, compared to pre-JSS: https://scdev28.duke-energy.com/info/unindexed/dpa-conversion-business. As you can see, it cuts off some of the image space and the description underneath is completely gone.

Modal.tsx

import React, { useRef, PropsWithChildren } from 'react';
import { createPortal } from 'react-dom';
import { a11yAction } from 'src/lib/helpers';
import { Placeholder } from '@sitecore-jss/sitecore-jss-react';
import SvgLoader from 'src/components/SvgLoader';
import Transition from 'src/lib/Transition';
import { useBodyContext } from 'src/components/ContentWrapper/context';
import { useExperienceEditor } from 'src/lib/useExperienceEditor';
import useMediaQuery from 'src/lib/useMediaQuery';
import usePreventBodyScroll from 'src/lib/usePreventBodyScroll';
import { ModalComponentTypes, ModalTypes } from './types';
import { useFocusTrap } from 'src/lib/useFocusTrap';

export default {
  title: "Components/Accordion",
  component: AccordionComponent,
  argTypes: {
    theme: {
      name: "Theme",
    },
    closeOthers: {
      name: "One Panel Open At A Time",
    },
  },
};

const Template = (args) => <AccordionComponent {...args} />;

export const Primary = Template.bind({});

Primary.args = {
  ...props,
};

argTypes: {
  title: {
    control: {
      type: 'text',
    },
  },
  subtitle: {
    control: {
      type: 'text',
    },
  },
  link: {
    control: 'boolean',
  },
  ctaType: {
    control: {
      type: 'inline-radio',
      options: ['ImageSlide', 'VideoSlide'],
    },
  },
},

import React from "react";
import MyComponent from "./index";
import { Data } from "./data";
import { MyComponent as MyComponentComposition } from "../../lib/composition";

const props = MyComponentComposition({ fields: Data });

export default {
  title: "Components/MyComponent",
  component: MyComponent,
  argTypes: {
    backgroundColor: {
      control: {
        type: "radio",
        options: ["white", "gray"],
      },
      defaultValue: "white",
    },
  },
};

const Template = (args) => <MyComponent {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  ...props,
};

...

export default {
  title: 'Components/MyComponent',
  component: MyComponent,
  argTypes: {
    backgroundColor: {
      control: {
        type: 'radio',
        options: ['white', 'gray'],
      },
      defaultValue: 'white',
    },
  },
};

...

...

import { storybookCustomArgs, createStoryOptions } from 'src/lib/helpers';


const props = BulletedOverviewComposition(Data);

const itemsToShow = createStoryOptions(props.items);

export default {
  title: 'Components/Bulleted Overview',
  component: BulletedOverview,
  argTypes: {
    ...storybookCustomArgs(props, BulletedOverview, [], false),
    items: {
      name: 'How many items?',
      control: {
        type: 'select',
        options: {
          ...itemsToShow,
        },
      },
    },
  },
};

...

export default function App() {
  return (
    <BrowserRouter>
      <div>
        <nav>
          <ul>
            <li>
              <Link to="/">Home</Link>
            </li>
            <li>
              <Link to="/count">Count</Link>
            </li>
          </ul>
        </nav>
        <Switch>
          <Route path="/count">
            <Count />
          </Route>
          <Route path="/">
            <Home />
          </Route>
        </Switch>
      </div>
    </BrowserRouter>
  );
}

function Count() {
  const [count, setCount] = useState(1);
  useEffect(() => {
    window.addEventListener('scroll', increaseCount);
    return () => window.removeEventListener('scroll', increaseCount);
  }, []);
  const increaseCount = () => {
    setCount(count => count + 1);
  }
  return <h2 style={{marginBottom: 1200}}>Count {count}</h2>;
}

function Count() {
  const [count, setCount] = useState(1);
  useEffect(() => {
    window.addEventListener('scroll', _.throttle(increaseCount, 100));
    return () => window.removeEventListener('scroll', _.throttle(increaseCount, 100));
  }, []);
  const increaseCount = () => {
    setCount(count => count + 1);
  }
  return <h2 style={{marginBottom: 1200}}>Count {count}</h2>;
}

const throttledCount = _.throttle(increaseCount, 100);
useEffect(() => {
    window.addEventListener('scroll', throttledCount);
    return () => window.removeEventListener('scroll', throttledCount);
  }, []);

useEffect(() => {
    const throttledCount = _.throttle(increaseCount, 100);
    window.addEventListener('scroll', throttledCount);
    return () => window.removeEventListener('scroll', throttledCount);
  }, []);

function Count() {
  const [count, setCount] = useState(1);
  const [text, setText] = useState("");
  const increaseCount = () => {
    setCount(count => count + 1);
  }
  const debouncedCount = _.debounce(increaseCount, 1000);
  const handleChange = (e) => {
    setText(e.target.value);
    debouncedCount();
  }
  return <>
    <h2>Count {count}</h2>
    <h3>Text {text}</h3>
    <input type="text" onChange={handleChange}></input>
  </>;
}

<dl title="Nautical terms">
  <dt>Knot</dt>
  <dd>
    <p>A <em>knot</em> is a unit of speed equaling 1
      nautical mile per hour (1.15 miles per hour or 1.852
      kilometers per hour).</p>
  </dd>
  <dt>Port</dt>
  <dd>
    <p><em>Port</em> is the nautical term (used on
      boats and ships) that refers to the left side
      of a ship, as perceived by a person facing towards
      the bow (the front of the vessel).</p>
  </dd>
  <dt>Starboard</dt>
  <dd>
    <p><em>Starboard</em> is the nautical term (used
      on boats and ships) that refers to the right
      side of a vessel, as perceived by a person
      facing towards the bow (the front of the vessel).</p>
  </dd>
</dl>

Analytics

Adding analytics to a component is pretty straightforward,

First set up your analytics object in your composition method:

const { compositionFunction, component } = Composition(NavCard)(({ fields, params }) => {

const items = fields?.items.reduce(
    (acc: Parameters<typeof NavCard>[0]['items'], curr: typeof fields) => {
      return [
        {
          ...
          analytics: {
            category: 'nav-card_rectangular',
            label: title?.value || '',
            action: [cta?.text?.value, cta?.href].filter(Boolean).join(' | '),
            guid: link?.value?.id || '',
            event: 'event-click',
          },
        },
      ];
    },
    []
  );

Then import the track object from src/lib/Analytics into your component, and grab the analytics data from the composition props. After that, simply attach a handler to the correct component node, to call the track.component method and send the data to analytics:

Testing Analytics

When not in production, analytics data will be sent to the console instead of to Google. To verify that your analytics are being setup and used correctly, simply open the console, trigger the analytics method, and you should see something similar to the following:

import track from 'src/lib/Analytics';
...

const ComponentName = ({
  ...
  analytics,
}: PropsType) => {

...
  <Button
    ...
    onClick={() => track.component(analytics)}
  >
    Click Me!
  </Button>

Unable to find an element with the text: Hello world.
This could be because the text is broken up by multiple elements.
In this case, you can provide a function for your text
matcher to make your matcher more flexible.

Sitecore

Component Creation - Sitecore

Table of Contents:

Intro
Technical Overview
Practical Overview
Definition of Done
Sitecore

Sitecore and You

In the context of our application, we treat Sitecore like a CMS for our React front end. We use it to tell our application where components should be and provide data and assets.

But Sitecore is not for the faint of heart. Many devs like to get their hands dirty by just "getting in there" and poking around. However, due to its terrible UI and grinding sluggishness, working within Sitecore can be maddening. To top it all off, as is so often the case, the documentation for Sitecore is substandard. God willing, you won't need to venture into Sitecore very often. But if you have exhausted all other options and you still find you need to work within it, it's better to go in with a clear gameplan of what you want to accomplish and how to accomplish it. This section aims to help you with that.

Sitecore Component Creation Overview

Once upon a time, new components were built by the front end team and then handed off to the Sitecore developers for integration into the application. These days, components built by the front end team stay within the front end application, making the workflow much more efficient. New components can then be integrated into the CMS for use by the content team, with editable fields intact.

While many components are already available for our application in Sitecore, if you find that you need to add a component to be edited within Sitecore, this document contains an overview to the process you will need to follow.

Before delving into that, it is helpful to understand at a high level how Sitecore is being used in our implementation.

A "page" such as /Home or /Billing consists of a collection of Renderings within Sitecore. A rendering could be viewed as a representation of a React component within Sitecore. These renderings are associated with data relevant to the component and placeholder info. A Placeholder is a way for content authors and marketing folks to specify where upon a page a component should be injected. In order for a rendering to be displayed upon a page, it will need to be assigned a placeholder.

When a page exists within Sitecore, it is made available to our application via something called the Layout Service, which exposes an endpoint that can be requested. This endpoint returns a serialized JSON payload of the rendering info from Sitecore. While a traditional Sitecore implementation would involve C# and Razor templates, this implementation makes it possible for us to use React on the front end.

Basic Instructions for Creating a Component

Navigate to [Sitecore](http: //scdev25.duke-energy.com/sitecore) and login. From there, expand "sitecore > Layout > Renderings > Custom > Common" and you can see the available renderings. If you need a rendering to map to your component that isn't already available here, you can create one.
Create a Rendering. Within the appropriate folder under /sitecore/layout/renderings, create a new Json Rendering. This will most likely be within the Custom/Common folder, and can be done either by right-clicking the folder and selecting Insert > Json Rendering or selecting the folder you want to create a rendering in and then pressing the Json Rendering button from the options.

< Previous

Installing Citrix Workspace on Chrome OS Devices

Installing, Configuring, and Uninstalling Citrix Workspace on Chrome OS Devices

Contents

****

Installing Citrix Workspace on Chrome OS Devices ............................................................. 2

Configuring Citrix Workspace on Chrome OS Devices.......................................................... 3

Secondary configuration of Citrix Workspace on Chrome OS Devices…………………. 6

Uninstalling Citrix Workspace on Chrome OS Devices ......................................................... 9

Installing Citrix Workspace on Chrome OS Devices

1. On the Chrome OS device, open the Chrome Web Store and search for ‘Citrix Workspace’. Select ‘Citrix Workspace for Chrome OS’. Click Add to Chrome and Add App When prompted.

****

Configuring Citrix Workspace on Chrome OS Devices

****

1. Upon installation, click the Launcher Icon and then click the Citrix Workspace icon. You may need to click on All Apps to see the Citrix Workspace icon.

****

2. You will be prompted to enter a server address: Enter

****

3. Next, enter your Username, Password and your Passcode when prompted. Click Log On once you’ve finished entering your information.

NOTE:

• When using a physical key fob, your Passcode is your unique PIN + RSA token ID.

• When using a soft token, the PIN is not included as part of the Passcode.

4. The available Citrix applications and desktops should now appear as icons. You have successfully installed the Citrix Workspace software on your computer.

5. To launch a virtual desktop, select the Desktops tab at the bottom of the screen and select the assigned desktop. And to launch a virtual application, select the Apps tab at the bottom of the screen and select the application.

****

Secondary configuration of Citrix Workspace on Chrome OS Devices

****

NOTE: If you have not set up an authentication method in O365, by using this job aid , please do so BEFORE adding the Multifactor Authentication Citrix Portal URL

****

- Be sure you set up a primary authentication method and a secondary authentication method.

****

o Choose your preferred primary authentication method from the drop-down box under “what’s your preferred option?”

****

1. Upon installation, click the Launcher Icon and then click the Citrix Workspace icon. You may need to click on All Apps to see the Citrix Workspace icon.

2. You will be prompted to enter a server address: Enter in order to setup the Citrix Portal that utilizes Multifactor Authentication. Afterwards, select Connect.

3. Next, enter your Username and Password when prompted. Click Log On once you’ve finished entering your information.

****

NOTE: You will be prompted to authenticate via the method that you setup within your Office 365 Authentication Profile:

· Via a call to a phone number you provided during setup (e.g., mobile phone number, secondary mobile phone number, or home phone number where you will be working)

· The Microsoft Authenticator application

****

4. To access your assigned virtual desktops or virtual applications, click either the DESKTOPS or APPS buttons at the top of the page.

****

Uninstalling Citrix Workspace on Chrome OS Devices

1. Open the Launcher (Magnifying glass) on your taskbar. Click the upward arrow to show all installed apps and locate the Citrix Workspace icon.

2. Right-click the Citrix Workspace Icon. If you are not using a mouse, then press the Alt key when you click on the Citrix Workspace icon to bring up the ‘right click’ menu options

3. Click Uninstall. Click Remove when asked to confirm removal.

****

<!--
  Hero Section wrapper
  - Component below hero is required to use a white background color
-->

<section class="relative 2xl:px-24 2xl:pt-24">

  <!--
    Hero Container
  -->

  <div class="relative container-5xl flex flex-col justify-center aspect-16/12 sm:aspect-16/9 md:aspect-16/7 lg:aspect-16/6 xl:aspect-16/5 px-24 sm:px-32 md:px-48 py-64 md:py-48">

    <!--
      - Leave alt attribute empty
      - Use 'srcset' and 'sizes' attributes to optimize the hero image
    -->

    <img
      class="absolute top-0 left-0 object-cover object-right w-full h-full 2xl:rounded-lg bg-gray-light"
      src="image.jpg?w=800&as=1&bc=ffffff"
      srcset="image.jpg?w=800&as=1&bc=ffffff 800w,
              image.jpg?w=1600&as=1&bc=ffffff 1600w"
      sizes="(min-width: 768px) 1600px, 800px"
      alt=""
      width="1600"
      height="500"
      loading="lazy"
    >

    <!--
      Overlay
      - Change background gradient colors based on theme of hero
      - Default - "from-blue-dark to-blue sm:via-blue"
    -->

    <div
      class="absolute top-0 left-0 h-full w-full 2xl:rounded-l-lg md:w-3/4 bg-gradient-to-tr md:bg-gradient-to-r md:to-transparent opacity-80"
      aria-hidden="true"
    ></div>

    <!--
      Content Container
    -->

    <div class="relative w-full container-xs md:container-4xl">

      <!--
        If dark theme/gradient, text is white
          - Use "text-white"
        If light theme/gradient, text can be gray or blue
          - Use "text-gray-dark" -or- "text-blue"
        Default
          - "text-white"
      -->

      <div class="w-full md:w-1/2 text-center md:text-left">

        <!-- Hero Title
          - If this is the page title, you should use an <h1> element
          - Use an <h2> element if you already have a page title on the page
        -->
        <h2
          class="text-3xl md:text-2xl-fixed xl:text-3xl"
          id="hero-title"
        >
          Hero Title
        </h2>

        <!-- Hero Short Description-->
        <p class="text-lg xl:text-xl mt-12 lg:mt-16">
          Description goes here.
        </p>

        <!-- Hero Actions -->
        <div class="flex justify-center md:justify-start gap-16 lg:gap-24 mt-16 lg:mt-24">
          <!--
            If dark theme/gradient
              - Use "btn-primary-reversed"
            If light theme/gradient
              - Use "btn-primary"
            Default
              - "btn-primary-reversed"
          -->
          <a
            class="btn btn-primary-reversed btn-md"
            href="#"
            id="hero-primary-action"
            aria-labelledby="hero-primary-action hero-title"
          >
            Primary Action
          </a>
          <!--
            If dark theme/gradient
              - Use "btn-secondary-reversed"
            If light theme/gradient
              - Use "btn-secondary"
            Default
              - "btn-secondary-reversed"
          -->
          <a
            class="btn btn-secondary-reversed btn-sm lg:btn-md"
            href="#"
            id="hero-secondary-action"
            aria-labelledby="hero-secondary-action hero-title"
          >
            Secondary Action
          </a>
        </div>
      </div>

    </div>

  </div>

</section>

// # TextMatch type accenpts function: https://testing-library.com/docs/queries/about/#textmatch
import { renderWithCTX, screen, Matcher } from "src/lib/testWrappers";
import userEvent from "@testing-library/user-event";
import "@testing-library/jest-dom";
import { Accordion, themeMap } from "./index";
import { compositionFunction } from "./composition";
import data from "./data";
import { stripHTMLTags } from "src/lib/helpers";
jest.mock("src/lib/useIntersection");
describe("Accordion", () => {
  const props = compositionFunction(data);
  it.skip("should render the correct items", () => {
    renderWithCTX(<Accordion {...props} />);
    for (let i = 0; i < props.items.length - 1; i++) {
      const accordionTitle = screen.getByText(
        props?.items[0]?.title?.value as string
      );
      expect(accordionTitle).toBeTruthy();
    }
  });
  it.skip("should render Accordion Component with image", () => {
    renderWithCTX(<Accordion {...props} />);
    const img = screen.getByRole("img", { name: /facebook/i });
    expect(img).toBeInTheDocument();
  });
  it("should reveal text when user clicks", async () => {
    renderWithCTX(<Accordion {...props} />);
    const accordionButton = screen.getByRole("button", {
      name: props.items[0].title?.value,
    });
    // # Full Manual Query:
    // (This is actually not good - getByText won't respect eg aria- attrs like getByRole so we aren't actually testing anything)
    // These are [not exposed to a11y tree](https://testing-library.com/docs/queries/about/#priority)
    // 👉
    // screen.getByText(
    //   /proin laoreet mauris vel urna tempor ultricies\. duis rhoncus lorem sed tellus egestas bibendum\. in aliquam mauris est, vel condimentum metus aliquet a\. nunc volutpat tincidunt nisl luctus pretium\. sagittis elit non, vestibulum metus\. mauris maximus vitae magna in mattis\. integer interdum maximus felis sed placerat\. nam lobortis tellus non felis fermentum, vitae venenatis ligula congue\. donec sit amet luctus odio\. magna commodo, sodales convallis ante scelerisque\. etiam ipsum lorem, rhoncus a sapien id, placerat consequat nunc\. curabitur in orci libero\. morbi tincidunt ante vel sem rutrum tempor\. cras ac purus quis urna maximus volutpat\./i
    // );
    // # We can still do a findByText,
    // but we need to check ourselves whether it is accessible:
    // 👉
    const hiddenText = await screen.findByText((content, element) => {
      const hasTextContent =
        element?.innerHTML === props?.items[0]?.text?.value;
      return hasTextContent;
    });
    expect(hiddenText).toBeInTheDocument();
    expect(hiddenText).toHaveAttribute("aria-hidden", "true");
    await userEvent.click(accordionButton);
    // # Compare against textContent stripHTMLTags:
    // (similar to https://polvara.me/posts/five-things-you-didnt-know-about-testing-library)
    // 👉
    // const noTag = stripHTMLTags(props?.items?.[0]?.text?.value as string);
    // const [revealedText] = await screen.findAllByText(
    //   // @ts-ignore
    //   // eslint-disable-next-line
    //   (content, element) => element?.textContent === noTag
    //   // ?  console.log('🔥', content) || true : false
    // );
    // expect(revealedText).toBeInTheDocument();
    // console.log('😳', noTag);
    // 😳 Proin laoreet mauris vel urna tempor ultricies. Duis rhoncus lorem sed tellus egestas bibendum. In aliquam mauris est, vel condimentum metus aliquet a. Nunc volutpat tincidunt nisl luctus pretium. Duis et ligula semper, sagittis elit non, vestibulum metus. Mauris maximus vitae magna in mattis. Integer interdum maximus felis sed placerat. Nam lobortis tellus non felis fermentum, vitae venenatis ligula congue. Donec sit amet luctus odio. Nam convallis justo vitae magna commodo, sodales convallis ante scelerisque. Etiam ipsum lorem, rhoncus a sapien id, placerat consequat nunc. Curabitur in orci libero. Morbi tincidunt ante vel sem rutrum tempor. Cras ac purus quis urna maximus volutpat.
    // # Find by innerHTML:
    // 👉
    const revealedText = await screen.findByText((content, element) => {
      const hasTextContent =
        element?.innerHTML === props?.items[0]?.text?.value;
      return hasTextContent;
    });
    expect(revealedText).toBeInTheDocument();
    expect(revealedText).toHaveAttribute("aria-hidden", "false");
  });
  // Overall, probably ultimately more durable / less error prone to use a testid and check aria- attrs
  it.skip("renders the correct default style", () => {
    const { rerender } = renderWithCTX(<Accordion {...props} />);
    const button = screen.getByRole("button", {
      name: /accordion trigger one/i,
    });
    expect(button).toHaveClass(themeMap.default.button);
    const altThemeProp = { ...props, theme: "footer" } as const;
    rerender(<Accordion {...altThemeProp} />);
    expect(button).toHaveClass(themeMap?.footer?.button);
  });
});

Types VS Interfaces

Types vs. interfaces in TypeScript - LogRocket Blog

Excerpt
It is very simple to get started with TypeScript, but sometimes we need to think more about the best use case for us. In this case, types or interfaces?

The idea of having static type-checking in JavaScript is really fantastic and the adoption of TypeScript is growing more every day.

You started to use TypeScript in your project, you created your first type, then you jumped to your first interface, and you got it working. You concluded that TypeScript, in fact, was helping your development and saving you precious time, but you might have made some mistakes and not followed the best practices when you started to work with types and interfaces in TypeScript.

This is the case for a lot of developers, they don't really know the real difference between type aliases and interfaces in TypeScript.

It is very simple to get started with TypeScript, but sometimes we need to think more about the best use case for us. In this case, types or interfaces?

Types and type aliases

Before we jump into the differences between types and interfaces in TypeScript, we need to understand something.

In TypeScript, we have a lot of basic types, such as string, boolean, and number. These are the basic types of TypeScript. You can check the list of all the basic types [here](https: //www.typescriptlang.org/docs/handbook/basic-types.html#table-of-contents). Also, in TypeScript, we have advanced types and in these [advanced types](https: //www.typescriptlang.org/docs/handbook/advanced-types.html), we have something called [type aliases](https: //www.typescriptlang.org/docs/handbook/advanced-types.html#type-aliases). With type aliases, we can create a new name for a type but we don't define a new type.

We use the type keyword to create a new type alias, that's why some people might get confused and think that it's creating a new type when they're only creating a new name for a type. So, when you hear someone talking about the differences between types and interfaces, like in this article, you can assume that this person is talking about type aliases vs interfaces.

We will use the [TypeScript Playground](https: //www.typescriptlang.org/play/index.html#) for code examples. The [TypeScript Playground](https: //www.typescriptlang.org/play/index.html#) allows us to work and test the latest version of TypeScript (or any other version we want to), and we will save time by using this playground rather than creating a new TypeScript project just for examples.

Types vs. interfaces

The difference between types and interfaces in TypeScript used to be more clear, but with the latest versions of TypeScript, they're becoming more similar.

Interfaces are basically a way to describe data shapes, for example, an object.

Type is a definition of a type of data, for example, a union, primitive, intersection, tuple, or any other type.

Declaration merging

One thing that's possible to do with interfaces but are not with types is declaration merging. Declaration merging happens when the TypeScript compiler merges two or more interfaces that share the same name into only one declaration.

Let's imagine that we have two interfaces called Song, with different properties:

interface Song { artistName: string; }; interface Song { songName: string; }; const song: Song = { artistName: "Freddie", songName: "The Chain" };

TypeScript will automatically merge both interfaces declarations into one, so when we use this Song interface, we'll have both properties.

Declaration merging does not work with types. If we try to create two types with the same names, but with different properties, TypeScript would still throw us an error.

Duplicate identifier Song.

Extends and implements

In TypeScript, we can easily extend and implement interfaces. This is not possible with types though.

Interfaces in TypeScript can extend classes, this is a very awesome concept that helps a lot in a more object-oriented way of programming. We can also create classes implementing interfaces.

For example, let's imagine that we have a class called Car and an interface called NewCar, we can easily extend this class using an interface:

class Car { printCar = () => { console.log("this is my car") } }; interface NewCar extends Car { name: string; }; class NewestCar implements NewCar { name: "Car"; constructor(engine:string) { this.name = name } printCar = () => { console.log("this is my car") } };

Intersection

Intersection allows us to combine multiple types into a single one type. To create an intersection type, we have to use the & keyword:

type Name = { name: "string" }; type Age = { age: number }; type Person = Name & Age;

The nice thing here is that we can create a new intersection type combining two interfaces, for example, but not the other way around. We cannot create an interface combining two types, because it doesn't work:

interface Name { name: "string" }; interface Age { age: number }; type Person = Name & Age;

Unions

Union types allow us to create a new type that can have a value of one or a few more types. To create a union type, we have to use the | keyword.

type Man = { name: "string" }; type Woman = { name: "string" }; type Person = Man | Woman;

Similar to intersections, we can create a new union type combining two interfaces, for example, but not the other way around:

interface Man { name: "string" }; interface Woman { name: "string" }; type Person = Man | Woman;

Tuples

[Tuples](https: //www.typescriptlang.org/docs/handbook/basic-types.html#tuple) are a very helpful concept in TypeScript, it brought to us this new data type that includes two sets of values of different data types.

type Reponse = [string, number]

But, in TypeScript, we can only declare tuples using types and not interfaces. There's no way we can declare a tuple in TypeScript using an interface, but you still are able to use a tuple inside an interface, like this:

interface Response { value: [string, number] }

We can see that we can achieve the same result as using types with interfaces. So, here comes the question that a lot of developers might have — should I use a type instead of an interface? If so, when should I use a type?

Let's understand the best use cases for both of them, so you don't need to abandon one for the other.

What should I use?

This question is really tricky, and the answer to it, you might guess, depends on what you're building and what you're working on.

Interfaces are better when you need to define a new object or method of an object. For example, in React applications, when you need to define the props that a specific component is going to receive, it's ideal to use interface over types:

interface TodoProps { name: string; isCompleted: boolean }; const Todo: React.FC<TodoProps> = ({ name, isCompleted }) => { ... };

Types are better when you need to create functions, for example. Let's imagine that we have a function that's going to return an object called, type alias is more recommended for this approach:

type Person = { name: string, age: number }; type ReturnPerson = ( person: Person ) => Person; const returnPerson: ReturnPerson = (person) => { return person; };

At the end of the day, to decide if you should use a type alias or an interface, you should carefully think and analyze the situation — what you're working on, the specific code, etc.

Interface work better with objects and method objects, and types are better to work with functions, complex types, etc.

You should not start to use one and delete the other. Instead of doing that, start to refactor slowly, thinking of what makes more sense to that specific situation.

Remember that you can use both together and they will work fine. The idea here is just to clarify the differences between types and interfaces, and the best use cases for both.

Conclusion

In this article, we learned more about the differences between types and interfaces in TypeScript. We learned that type aliases are advanced types in TypeScript, we learned the best use cases for both types and interfaces in TypeScript, and how we can apply both of them in real projects.

clone the project from https: //bitbucketp.duke-energy.com/projects/DUKCOM/repos/dxt-jss-public/browse 1. In your terminal (command line), run git clone https: //bitbucketp.duke-energy.com/scm/dukcom/dxt-jss-public.git

  1. Add:

     ```
     {
       "sitecore": {
         "instancePath": "",
         "apiKey": "{9F777224-3275-4D56-BD29-371FB3C00821}",
         "deploySecret": "",
         "deployUrl": "",
         "layoutServiceHost": "https:

// MyComponent/index.tsx

/** technically, you would want to provide types in a Typescript file,
 * but we're just trying to get some data here.
 */

const MyComponent = (scData) => {
  console.log(scData);
  return <div>{JSON.stringify(scData)}</div>;
};

// Now you can copy the payload from your browser and paste it into your brand new data file!

// story.js
import React from "react";
import MyComponent from "./index";
import { MyComponent as MyComponentComposition } from "../../lib/composition";
import Data from "./data";

/**
 * create a variable with data that is in the shape that your component will be
 * expecting, as it would be from your composition file.
 * Again, this is necessary since the composition function is not called by Storybook.
 */

const props = MyComponentComposition(Data);

const Template = (args) => <MyComponent {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  /* here you can spread those props into your Storybook file, making data
   * available to your component as it would be on the actual live page.
   */
  ...props,
};

Tailwind CSS

Tailwind CSS is a utility-based styling library. In order to streamline and standardize things like colors and spacing within our application, an Electron theme has been created to extend Tailwind's functionality, thus making it easy for us to access some standard Duke colors, fonts, etc. As a result, you will get most of the magic of Tailwind, but with most of the colors, text, and sizing options overwritten to reflect Duke's design system.

We won't talk too much about the decisions behind why we are using this implementation here, but Chris Greufe has already done an incredible job documenting the ins-and-outs of it [here](https: //electron.duke-energy.com/foundation/utilities/utility-first). If you want to know more of the granular aspects and philosophy to our approach, you are encouraged to give it a read.

Instead, this doc will mostly focus on how the dev team actually uses this implementation and a bit about our approach, as well as a proposed style guide.

Philosophy and Approach

Tailwind CSS is our primary way of styling within the DXT-JSS-Public React App. A lot of effort and resources have been put into making Tailwind and Electron do as much of the heavy lifting for us as possible, so for maintainability's sake, every effort should be made to find a solution to style your work with Tailwind. If you're hitting a wall trying to figure out an approach that works within Tailwind, don't hesitate to reach out to a teammate. If you find yourself in the rare situation where you encounter something that simply cannot be resolved using Tailwind, we use [Styled Components](https: //styled-components.com) as our fallback. If you find that you are creating a styled component often to deal with an edge case, it's probably worth documenting [here](https: //confluence.duke-energy.com/display/DEPW/Tailwind+requests).

Tooling

There's not a lot of tooling required for Tailwind but [the Tailwind CSS Intellisense VSCode plugin](https: //marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) can be pretty helpful. Once installed, it gives suggestions for Tailwind classes as well as Electron-specific ones. It also shows a preview of the CSS rules that the utility class utilizes.

Enabling Tailwind Properties

Although Tailwind provides the flexibility to apply a wide range of modifiers (called variants in Tailwind) to a variety of CSS rules, you may occasionally find that a Tailwind class is not behaving the way you expect in a responsive context, or upon hover. This may mean that you will need to edit the Tailwind config. [You can find more info about that here.](https: //tailwindcss.com/docs/configuring-variants) Please be careful to [extend the values](https: //v1.tailwindcss.com/docs/configuring-variants), rather than simply adding them to the variant object, which will overwrite all the defaults.

Key Differences

The main difference you'll find between Tailwind's approach and Electron's is that Duke doesn't need an extensive color library. As a result, you'll find that something like text-blue-800 or bg-yellow-200 does not behave as you'd expect. Most likely you will be looking for something like text-blue-dark or bg-yellow. So the color palette will be limited, and rather than a number to modify the color, there will either be no modifier, or a modifier of -light, -lighter, -dark, or -darker.

Style Guide

Because almost all of our styles exist within utility classes, there is often no need for traditional CSS classes to style a block. It's fairly unusual to need to add a class like wrapper or large BEM classes. Occasionally, you may need to add a class to make it easier for unit tests to search for a selector. In such a case, we suggest that you use a js- prefix, and that you place it at the beginning of your utility classes.

example:

Often, the amount of classes you need to style a complex element can be rather long. In this case, it is suggested that you group your classes conceptually. Since Tailwind is a mobile-first framework, it makes sense to start with "base" styles that will be present across all sizes of the component, immediately followed by the responsive counterparts, in ascending order (md, lg, xl, etc).

Of the base styles, start with sizing (height, width, padding, margin) and other fiddly rules so that they are easily accessible to you and anyone who may need to maintain your code in the future. Utility classes that represent rules that are easily identifiable at a glance, such as text color or background color, should come secondary.

That was a lot of words, so let's look at an example.

🚫 Bad

✅ Good

That may seem a lot to unpack, so let's examine that for a second. Note that the classes start with the width property and then are immediately followed by the responsive variant. This pattern follows as we move through the margin and into the padding, which is then followed by the display types, and onto more obvious styles like font and background colors, which don't require a check of the code in order to verify the values. Finally, the rules end with the transition and duration properties, which are often "set and forget" rules.

Resources

[Styled Components](https: //styled-components.com) - documentation in case you need to step outside the Tailwind garden
[Tailwind Requests](https: //confluence.duke-energy.com/display/DEPW/Tailwind+requests) - add to the Tailwind/Electron wishlist!
[Electron Docs](https: //electron.duke-energy.com/foundation/utilities/utility-first)

React | Typescript | Tailwind | Forms | Unit Tests

Storybook

Storybook is an open source tool for developing UI components in isolation. It essentially gives us a sandbox to showcase and test the components we'll use throughout our app.

It allows us to develop more efficiently (we can develop our components in isolation within Storybook, rather than developing on the page of the app), and also allows the design and UI teams to interact with our components as we build them. They can also change the values of the component's props to see how the component will react as it receives different data.

To get it up and running navigate to the app repo and, from the command line, enter:

Let's first discuss some of the core principles of Storybook (we'll use examples from our own app where possible), before then diving into the anatomy of a typical story.

Stories

A story, much like a React component, is a function that describes how to render a component.

You can have multiple stories per component, meaning Storybook gives us the power to describe multiple rendered states.

For a very simple example using the PushDownPanel component from our own app, we might first describe the component with it's default state, but then add a story that describes a different rendered state.

So here's how the initial default PushDownPanel might look:

And then we can add variations based on different states, for example a version that uses icons:

And the new stories will show up in the sidebar navigation, like so:

Args

Story definitions can be further improved to take advantage of Storybook's "args" concept.

A story is a component with a set of arguments (props), and these arguments can be altered and composed dynamically. This gives Storybook its power (they even refer to this as a superpower in their docs!), allowing us essentially to live edit our components.

Most of the time the type of arg will be [inferred automatically](https: //storybook.js.org/docs/react/api/argtypes#automatic-argtype-inference), however we can use ArgTypes to further configure the behavior of our args, constraining the values they can take and generating relevant UI controls.

Controls

Controls allow designers and developers to explore component behavior by mucking about with its arguments.

Storybook feeds the given args property into the story during render. Each of the args from the story function will now be live editable using Storybook's Controls panel, so we can dynamically change components in Storybook to see how they look with different settings and data:

This essentially evolves Storybook into an interactive documentation tool, allowing developers and stakeholders to stress test components, for example by adding huge strings of text that might help expose UI problems.

Controls can be configured to use UI elements that we deem most appropriate according to the data that we're trying to manipulate; some examples from our own components include a radio button for manipulating background color:

A select menu to control the number of items that render:

And for our Hero component, a mixture of text inputs, boolean switch and radio group (screen shot of how these controls render follows the code):

Addons are plugins that extend Storybook's core functionality, packaged as NPM modules. Once [installed and registered](https: //storybook.js.org/docs/react/addons/install-addons) they will appear in the addons panel, a reserved place in the Storybook UI below the main component.

One such addon we use is the Accessibility addon, which helps to make our UI components more accessible. Simply select the Accessibility tab from the aforementioned addons panel, and there you will see any Violations, Passes and Incomplete requirements pertaining to accessibility.

We also use the Viewport [toolbar](https: //storybook.js.org/docs/react/get-started/browse-stories#toolbar) item, which allows us to adjust the dimensions of the iframe our stories are rendered in, making it nice to test responsive UIs.

Anatomy of a Story

Stories exist alongside the other component files as stories.js.

Here's an example of how a typical story might take shape:

Let's break this down line by line:

Component Setup: So we start off with your normal component setup, standard stuff: importing React, importing your component and (if your component gets data from Sitecore) importing any data that might be required.

Data Composition: After the component setup, we next move on to the process of essentially distilling the data recieved from Sitecore into only the parts we need - you can read more about this process in not only one spot of our docs, but two! Here and here.

Exporting Stories: After composing the data, we move on to one of the key ingredients of a story: the default export that describes the component. It's a function that returns a component's state given a set of arguments; it describes how to render a component.

It's a story! Behold. Don't get them wet, don't expose them to bright light, and most importantly don't feed them after midnight!

Were we to add any other stories beyond the default, we would then add named exports that would describe the additional stories.

We can also add ArgTypes here if we need to configure our args beyond Storybook's automatically-generated UI controls.

In the example above, we're setting backgroundColor as a radio button so the user can choose between different background colors, and setting the default as white.

Template Definition: Now that our stories are exported, we move on to defining a master template (Template) for our component's stories, and passing in our args.

We can then reuse this template across stories. Template.bind({}) makes a copy of the function, reducing code duplication. This is a [standard JavaScript technique](https: //developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind) for making a copy of a function, and allows each exported story to set its own properties.

And finally we spread in our component's props (...props), making data available to our component as it would be in the regular app.

storybookCustomArgs

The way in which Storybook automatically infers a set of argTypes based on each component's props can often lead to a lot of unnecessary UI controls rendering.

We have a function for that! In the lib/helpers/index.ts file you can find a very cool function called storybookCustomArgs, which allows us to configure which props we would like to render controls for in the Storybook Controls panel.

createStoryOptions

Oftentimes our component data will come through to us a single array, but in order for Storybook to render the controls in our desired way, we need that data to be a multi-dimenstional array.

Again we have a nifty function for that! Here's an example of both storybookCustomArgs and createStoryOptions Storybook helper functions at work:

Resources

[Learn Storybook](https: //www.learnstorybook.com) - a guided tutorial through building a simple application with Storybook
[Component Driven User Interfaces](https: //www.componentdriven.org) - learn more about the component-driven approach that Storybook enables
[Storybook Addons](https: //storybook.js.org/addons) - supercharge Storybook with advanced features and new workflows

Typescript Interfaces

When we talk about a type in TypeScript, we mean a collection of things that you can do with a variable (or expression). You might be able to read or write a given property, call a function, use the expression as a constructor, or index into the object. Some objects (like Date) in JavaScript can do nearly all of those! In TypeScript, interfaces are the most flexible way of describing types.

You'll see interfaces used to describe existing JavaScript APIs, create shorthand names for commonly-used types, constrain class implementations, describe array types, and more. While they don't generate any code (and thus have no runtime cost!), they are often the key point of contact between any two pieces of TypeScript code, especially when working with existing JavaScript code or built-in JavaScript objects.

The only job of an interface in TypeScript is to describe a type. While class and function deal with implementation, interface helps us keep our programs error-free by providing information about the shape of the data we work with. Because the type information is erased from a TypeScript program during compilation, we can freely add type data using interfaces without worrying about the runtime overhead.

While that sounds like a simple, one-purpose task, interfaces role in describing types becomes manifest in a large variety of ways. Let's look at some of them and how they can be used in TypeScript programs.

Basics

To define an interface in TypeScript, use the interface keyword:

This defines a type, Greetable, that has a member function called greet that takes a string argument. You can use this type in all the usual positions; for example in a parameter type annotation. Here we use that type annotation to get type safety on the g parameter:

When this code compiles, you won't see any mention of Greetable in the JavaScript code. Interfaces are only a compile-time construct and have no effect on the generated code.

Interfaces: TypeScript's Swiss Army Knife

Interfaces get to play a lot of roles in TypeScript code. We'll go into more detail on these after a quick overview.

Describing an Object

Many JavaScript functions take a "settings object". For example, jQuery's $.ajax takes an object that can have up to several dozen members that control its behavior, but you're only likely to pass a few of those in any given instance. TypeScript interfaces allow optional properties to help you use these sorts of objects correctly.

Describing an Indexable Object

JavaScript freely mixes members (foo.x) with indexers (foo['x']), but most programmers use one or the other as a semantic hint about what kind of access is taking place. TypeScript interfaces can be used to represent what the expected type of an indexing operation is.

Ensuring Class Instance Shape

Often, you'll want to make sure that a class you're writing matches some existing surface area. This is how interfaces are used in more traditional OOP languages like C# and Java, and we'll see that TypeScript interfaces behave very similarly when used in this role.

Ensuring the Static Shape of a Class or constructor Object

Interfaces normally describe the shape of an instance of a class, but we can also use them to describe the static shape of the class (including its constructor function). We'll cover this in a later post.

Describing an Object

You can also use interfaces to define the shape of objects that will typically be expressed in an object literal. Here's an example:

Describing Simple Types

Note the use of the ? symbol after some of the names. This marks a member as being optional. This lets callers of createButton supply only the members they care about, while maintaining the constraint that the required parts of the object are present:

You typically won't use optional members when defining interfaces that are going to be implemented by classes.

Here's another example that shows an interesting feature of types in TypeScript:

Note that we didn't annotate pt in any way to indicate that it's of type Point. We don't need to, because type checking in TypeScript is structural: types are considered identical if they have the same surface area. Because pt has at least the same members as Point, it's suitable for use wherever a Point is expected.

Describing External Types

Interfaces are also used to describe code that is present at runtime, but not implemented in the current TypeScript project. For example, if you open the lib.d.ts file that all TypeScript projects implicitly reference, you'll see an interface declaration for Number:

Now if we have an expression of type Number, the compiler knows that it's valid to call toPrecision on that expression.

Extending Existing Types

Moreover, interfaces in TypeScript are open, meaning you can add your own members to an interface by simply writing another interface block. If you have an external script that adds members to Date, for example, you simply need to write interface Date { /*...*/ } and declare the additional members.*

* Note: There are some known issues with the Visual Studio editor that currently prevent this scenario from working as intended. We'll be fixing this limitation in a later release.

Describing an Indexable Object

A common pattern in JavaScript is to use an object (e.g. {}) as way to map from a set of strings to a set of values. When those values are of the same type, you can use an interface to describe that indexing into an object always produces values of a certain type (in this case, Widget).

Ensuring Class Instance Shape

Let's extend the Greetable example above:

We can implement this interface in a class using the implements keyword:

Now we can use an instance of Person wherever a Greetable is expected:

var g: Greetable = new Person();

Similarly, we can take advantage of the structural typing of TypeScript to implement Greetable in an object literal:

Typescript Types

Everyday Types

In this chapter, we'll cover some of the most common types of values you'll find in JavaScript code, and explain the corresponding ways to describe those types in TypeScript. This isn't an exhaustive list, and future chapters will describe more ways to name and use other types.

Types can also appear in many more places than just type annotations. As we learn about the types themselves, we'll also learn about the places where we can refer to these types to form new constructs.

We'll start by reviewing the most basic and common types you might encounter when writing JavaScript or TypeScript code. These will later form the core building blocks of more complex types.

The primitives:`string`,`number`, and`boolean`

JavaScript has three very commonly used [primitives](https: //developer.mozilla.org/en-US/docs/Glossary/Primitive): string, number, and boolean. Each has a corresponding type in TypeScript. As you might expect, these are the same names you'd see if you used the JavaScript typeof operator on a value of those types:

string represents string values like "Hello, world"
number is for numbers like 42. JavaScript does not have a special runtime value for integers, so there's no equivalent to int or float - everything is simply number

The type names String, Number, and Boolean (starting with capital letters) are legal, but refer to some special built-in types that will very rarely appear in your code. Always use string, number, or boolean for types.

Arrays

To specify the type of an array like [1, 2, 3], you can use the syntax number[]; this syntax works for any type (e.g. string[] is an array of strings, and so on). You may also see this written as Array<number>, which means the same thing. We'll learn more about the syntax T<U> when we cover generics.

Note that [number] is a different thing; refer to the section on [Tuples](https: //www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types).

`any`

TypeScript also has a special type, any, that you can use whenever you don't want a particular value to cause typechecking errors.

When a value is of type any, you can access any properties of it (which will in turn be of type any), call it like a function, assign it to (or from) a value of any type, or pretty much anything else that's syntactically legal:

The any type is useful when you don't want to write out a long type just to convince TypeScript that a particular line of code is okay.

`noImplicitAny`

When you don't specify a type, and TypeScript can't infer it from context, the compiler will typically default to any.

You usually want to avoid this, though, because any isn't type-checked. Use the compiler flag [noImplicitAny](https: //www.typescriptlang.org/tsconfig#noImplicitAny) to flag any implicit any as an error.

Type Annotations on Variables

When you declare a variable using const, var, or let, you can optionally add a type annotation to explicitly specify the type of the variable:

TypeScript doesn't use "types on the left"-style declarations like int x = 0; Type annotations will always go after the thing being typed.

In most cases, though, this isn't needed. Wherever possible, TypeScript tries to automatically infer the types in your code. For example, the type of a variable is inferred based on the type of its initializer:

For the most part you don't need to explicitly learn the rules of inference. If you're starting out, try using fewer type annotations than you think - you might be surprised how few you need for TypeScript to fully understand what's going on.

Functions

Functions are the primary means of passing data around in JavaScript. TypeScript allows you to specify the types of both the input and output values of functions.

Parameter Type Annotations

When you declare a function, you can add type annotations after each parameter to declare what types of parameters the function accepts. Parameter type annotations go after the parameter name:

When a parameter has a type annotation, arguments to that function will be checked:

Even if you don't have type annotations on your parameters, TypeScript will still check that you passed the right number of arguments.

Return Type Annotations

You can also add return type annotations. Return type annotations appear after the parameter list:

Much like variable type annotations, you usually don't need a return type annotation because TypeScript will infer the function's return type based on its return statements. The type annotation in the above example doesn't change anything. Some codebases will explicitly specify a return type for documentation purposes, to prevent accidental changes, or just for personal preference.

Anonymous Functions

Anonymous functions are a little bit different from function declarations. When a function appears in a place where TypeScript can determine how it's going to be called, the parameters of that function are automatically given types.

Here's an example:

Even though the parameter s didn't have a type annotation, TypeScript used the types of the forEach function, along with the inferred type of the array, to determine the type s will have.

This process is called contextual typing because the context that the function occurred within informs what type it should have.

Similar to the inference rules, you don't need to explicitly learn how this happens, but understanding that it does happen can help you notice when type annotations aren't needed. Later, we'll see more examples of how the context that a value occurs in can affect its type.

Object Types

Apart from primitives, the most common sort of type you'll encounter is an object type. This refers to any JavaScript value with properties, which is almost all of them! To define an object type, we simply list its properties and their types.

For example, here's a function that takes a point-like object:

Here, we annotated the parameter with a type with two properties - x and y - which are both of type number. You can use , or ; to separate the properties, and the last separator is optional either way.

The type part of each property is also optional. If you don't specify a type, it will be assumed to be any.

Optional Properties

Object types can also specify that some or all of their properties are optional. To do this, add a ? after the property name:

In JavaScript, if you access a property that doesn't exist, you'll get the value undefined rather than a runtime error. Because of this, when you read from an optional property, you'll have to check for undefined before using it.

Union Types

TypeScript's type system allows you to build new types out of existing ones using a large variety of operators. Now that we know how to write a few types, it's time to start combining them in interesting ways.

Defining a Union Type

The first way to combine types you might see is a union type. A union type is a type formed from two or more other types, representing values that may be any one of those types. We refer to each of these types as the union's members.

Let's write a function that can operate on strings or numbers:

Working with Union Types

It's easy to provide a value matching a union type - simply provide a type matching any of the union's members. If you have a value of a union type, how do you work with it?

TypeScript will only allow an operation if it is valid for every member of the union. For example, if you have the union string | number, you can't use methods that are only available on string:

The solution is to narrow the union with code, the same as you would in JavaScript without type annotations. Narrowing occurs when TypeScript can deduce a more specific type for a value based on the structure of the code.

For example, TypeScript knows that only a string value will have a typeof value "string":

Another example is to use a function like Array.isArray:

Notice that in the else branch, we don't need to do anything special - if x wasn't a string[], then it must have been a string.

Sometimes you'll have a union where all the members have something in common. For example, both arrays and strings have a slice method. If every member in a union has a property in common, you can use that property without narrowing:

It might be confusing that a union of types appears to have the intersection of those types' properties. This is not an accident - the name union comes from type theory. The union number | string is composed by taking the union of the values from each type. Notice that given two sets with corresponding facts about each set, only the intersection of those facts applies to the union of the sets themselves. For example, if we had a room of tall people wearing hats, and another room of Spanish speakers wearing hats, after combining those rooms, the only thing we know about every person is that they must be wearing a hat.

Type Aliases

We've been using object types and union types by writing them directly in type annotations. This is convenient, but it's common to want to use the same type more than once and refer to it by a single name.

A type alias is exactly that - a name for any type. The syntax for a type alias is:

You can actually use a type alias to give a name to any type at all, not just an object type. For example, a type alias can name a union type:

Note that aliases are only aliases - you cannot use type aliases to create different/distinct "versions" of the same type. When you use the alias, it's exactly as if you had written the aliased type. In other words, this code might look illegal, but is OK according to TypeScript because both types are aliases for the same type:

Interfaces

An interface declaration is another way to name an object type:

Just like when we used a type alias above, the example works just as if we had used an anonymous object type. TypeScript is only concerned with the structure of the value we passed to printCoord - it only cares that it has the expected properties. Being concerned only with the structure and capabilities of types is why we call TypeScript a structurally typed type system.

Differences Between Type Aliases and Interfaces

Type aliases and interfaces are very similar, and in many cases you can choose between them freely. Almost all features of an interface are available in type, the key distinction is that a type cannot be re-opened to add new properties vs an interface which is always extendable.

Extending an interface

Extending a type via intersections

| |

Adding new fields to an existing interface

A type cannot be changed after being created

You'll learn more about these concepts in later chapters, so don't worry if you don't understand all of these right away.

Prior to TypeScript version 4.2, type alias names [may appear in error messages](https: //www.typescriptlang.org/play?#code/PTAEGEHsFsAcEsA2BTATqNrLusgzngIYDm+oA7koqIYuYQJ56gCueyoAUCKAC4AWHAHaFcoSADMaQ0PCG80EwgGNkALk6c5C1EtWgAsqOi1QAb06groEbjWg8vVHOKcAvpokshy3vEgyyMr8kEbQJogAFND2YREAlOaW1soBeJAoAHSIkMTRmbbI8e6aPMiZxJmgACqCGKhY6ABGyDnkFFQ0dIzMbBwCwqIccabcYLyQoKjIEmh8kwN8DLAc5PzwwbLMyAAeK77IACYaQSEjUWZWhfYAjABMAMwALA+gbsVjoADqgjKESytQPxCHghAByXigYgBfr8LAsYj8aQMUASbDQcRSExCeCwFiIQh+AKfAYyBiQFgOPyIaikSGLQo0Zj-aazaY+dSaXjLDgAGXgAC9CKhDqAALxJaw2Ib2RzOISuDycLw+ImBYKQflCkWRRD2LXCw6JCxS1JCdJZHJ5RAFIbFJU8ADKC3WzEcnVZaGYE1ABpFnFOmsFhsil2uoHuzwArO9SmAAEIsSFrZB-GgAjjA5gtVN8VCEc1o1C4Q4AGlR2AwO1EsBQoAAbvB-gJ4HhPgB5aDwem-Ph1TCV3AEEirTp4ELtRbTPD4vwKjOfAuioSQHuDXBcnmgACC+eCONFEs73YAPGGZVT5cRyyhiHh7AAON7lsG3vBggB8XGV3l8-nVISOgghxoLq9i7io-AHsayRWGaFrlFauq2rg9qaIGQHwCBqChtKdgRo8TxRjeyB3o+7xAA), sometimes in place of the equivalent anonymous type (which may or may not be desirable). Interfaces will always be named in error messages.
Type aliases may not participate [in declaration merging, but interfaces can](https: //www.typescriptlang.org/play?#code/PTAEEEDtQS0gXApgJwGYEMDGjSfdAIx2UQFoB7AB0UkQBMAoEUfO0Wgd1ADd0AbAK6IAzizp16ALgYM4SNFhwBZdAFtV-UAG8GoPaADmNAcMmhh8ZHAMMAvjLkoM2UCvWad+0ARL0A-GYWVpA29gyY5JAWLJAwGnxmbvGgALzauvpGkCZmAEQAjABMAMwALLkANBl6zABi6DB8okR4Jjg+iPSgABboovDk3jjo5pbW1d6+dGb5djLwAJ7UoABKiJTwjThpnpnGpqPBoTLMAJrkArj4kOTwYmycPOhW6AR8IrDQ8N04wmo4HHQCwYi2Waw2W1S6S8HX8gTGITsQA).

For the most part, you can choose based on personal preference, and TypeScript will tell you if it needs something to be the other kind of declaration. If you would like a heuristic, use interface until you need to use features from type.

Type Assertions

Sometimes you will have information about the type of a value that TypeScript can't know about.

For example, if you're using document.getElementById, TypeScript only knows that this will return some kind of HTMLElement, but you might know that your page will always have an HTMLCanvasElement with a given ID.

In this situation, you can use a type assertion to specify a more specific type:

Like a type annotation, type assertions are removed by the compiler and won't affect the runtime behavior of your code.

You can also use the angle-bracket syntax (except if the code is in a .tsx file), which is equivalent:

Reminder: Because type assertions are removed at compile-time, there is no runtime checking associated with a type assertion. There won't be an exception or null generated if the type assertion is wrong.

TypeScript only allows type assertions which convert to a more specific or less specific version of a type. This rule prevents "impossible" coercions like:

Sometimes this rule can be too conservative and will disallow more complex coercions that might be valid. If this happens, you can use two assertions, first to any (or unknown, which we'll introduce later), then to the desired type:

Literal Types

In addition to the general types string and number, we can refer to specific strings and numbers in type positions.

One way to think about this is to consider how JavaScript comes with different ways to declare a variable. Both var and let allow for changing what is held inside the variable, and const does not. This is reflected in how TypeScript creates types for literals.

By themselves, literal types aren't very valuable:

It's not much use to have a variable that can only have one value!

But by combining literals into unions, you can express a much more useful concept - for example, functions that only accept a certain set of known values:

Numeric literal types work the same way:

Of course, you can combine these with non-literal types:

There's one more kind of literal type: boolean literals. There are only two boolean literal types, and as you might guess, they are the types true and false. The type boolean itself is actually just an alias for the union true | false.

Literal Inference

When you initialize a variable with an object, TypeScript assumes that the properties of that object might change values later. For example, if you wrote code like this:

TypeScript doesn't assume the assignment of 1 to a field which previously had 0 is an error. Another way of saying this is that obj.counter must have the type number, not 0, because types are used to determine both reading and writing behavior.

The same applies to strings:

In the above example req.method is inferred to be string, not "GET". Because code can be evaluated between the creation of req and the call of handleRequest which could assign a new string like "GUESS" to req.method, TypeScript considers this code to have an error.

There are two ways to work around this.

You can change the inference by adding a type assertion in either location:

// Change 1: const req = { url: "https: //example.com", method: "GET" as "GET" }; // Change 2handleRequest(req.url, req.method as "GET");Try

The as const suffix acts like const but for the type system, ensuring that all properties are assigned the literal type instead of a more general version like string or number.

`null`and`undefined`

JavaScript has two primitive values used to signal absent or uninitialized value: null and undefined.

TypeScript has two corresponding types by the same names. How these types behave depends on whether you have the [strictNullChecks](https: //www.typescriptlang.org/tsconfig#strictNullChecks) option on.

`strictNullChecks`off

With [strictNullChecks](https: //www.typescriptlang.org/tsconfig#strictNullChecks) off, values that might be null or undefined can still be accessed normally, and the values null and undefined can be assigned to a property of any type. This is similar to how languages without null checks (e.g. C#, Java) behave. The lack of checking for these values tends to be a major source of bugs; we always recommend people turn [strictNullChecks](https: //www.typescriptlang.org/tsconfig#strictNullChecks) on if it's practical to do so in their codebase.

`strictNullChecks`on

With [strictNullChecks](https: //www.typescriptlang.org/tsconfig#strictNullChecks) on, when a value is null or undefined, you will need to test for those values before using methods or properties on that value. Just like checking for undefined before using an optional property, we can use narrowing to check for values that might be null:

Non-null Assertion Operator (Postfix`!`)

TypeScript also has a special syntax for removing null and undefined from a type without doing any explicit checking. Writing ! after any expression is effectively a type assertion that the value isn't null or undefined:

Just like other type assertions, this doesn't change the runtime behavior of your code, so it's important to only use ! when you know that the value can't be null or undefined.

Enums

Enums are a feature added to JavaScript by TypeScript which allows for describing a value which could be one of a set of possible named constants. Unlike most TypeScript features, this is not a type-level addition to JavaScript but something added to the language and runtime. Because of this, it's a feature which you should know exists, but maybe hold off on using unless you are sure. You can read more about enums in the [Enum reference page](https: //www.typescriptlang.org/docs/handbook/enums.html).

Less Common Primitives

It's worth mentioning the rest of the primitives in JavaScript which are represented in the type system. Though we will not go into depth here.

bigint

From ES2020 onwards, there is a primitive in JavaScript used for very large integers, BigInt:

You can learn more about BigInt in [the TypeScript 3.2 release notes](https: //www.typescriptlang.org/docs/handbook/release-notes/typescript-3-2.html#bigint).

symbol

There is a primitive in JavaScript used to create a globally unique reference via the function Symbol():

You can learn more about them in [Symbols reference page](https: //www.typescriptlang.org/docs/handbook/symbols.html).

Types VS Interfaces

Object Types

In JavaScript, the fundamental way that we group and pass around data is through objects. In TypeScript, we represent those through object types.

As we've seen, they can be anonymous:

or they can be named by using either an interface

or a type alias.

In all three examples above, we've written functions that take objects that contain the property name (which must be a string) and age (which must be a number).

Property Modifiers

Each property in an object type can specify a couple of things: the type, whether the property is optional, and whether the property can be written to.

Optional Properties

Much of the time, we'll find ourselves dealing with objects that might have a property set. In those cases, we can mark those properties as optional by adding a question mark (?) to the end of their names.

In this example, both xPos and yPos are considered optional. We can choose to provide either of them, so every call above to paintShape is valid. All optionality really says is that if the property is set, it better have a specific type.

We can also read from those properties - but when we do under [strictNullChecks](https: //www.typescriptlang.org/tsconfig#strictNullChecks), TypeScript will tell us they're potentially undefined.

In JavaScript, even if the property has never been set, we can still access it - it's just going to give us the value undefined. We can just handle undefined specially.

Note that this pattern of setting defaults for unspecified values is so common that JavaScript has syntax to support it.

Here we used [a destructuring pattern](https: //developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) for paintShape's parameter, and provided [default values](https: //developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Default_values) for xPos and yPos. Now xPos and yPos are both definitely present within the body of paintShape, but optional for any callers to paintShape.

Note that there is currently no way to place type annotations within destructuring patterns. This is because the following syntax already means something different in JavaScript.

In an object destructuring pattern, shape: Shape means "grab the property shape and redefine it locally as a variable named Shape. Likewise xPos: number creates a variable named number whose value is based on the parameter's xPos.

Using [mapping modifiers](https: //www.typescriptlang.org/docs/handbook/2/mapped-types.html#mapping-modifiers), you can remove optional attributes.

`readonly`Properties

Properties can also be marked as readonly for TypeScript. While it won't change any behavior at runtime, a property marked as readonly can't be written to during type-checking.

Using the readonly modifier doesn't necessarily imply that a value is totally immutable - or in other words, that its internal contents can't be changed. It just means the property itself can't be re-written to.

It's important to manage expectations of what readonly implies. It's useful to signal intent during development time for TypeScript on how an object should be used. TypeScript doesn't factor in whether properties on two types are readonly when checking whether those types are compatible, so readonly properties can also change via aliasing.

Using [mapping modifiers](https: //www.typescriptlang.org/docs/handbook/2/mapped-types.html#mapping-modifiers), you can remove readonly attributes.

Index Signatures

Sometimes you don't know all the names of a type's properties ahead of time, but you do know the shape of the values.

In those cases you can use an index signature to describe the types of possible values, for example:

Above, we have a StringArray interface which has an index signature. This index signature states that when a StringArray is indexed with a number, it will return a string.

An index signature property type must be either ‘string' or ‘number'.

It is possible to support both types of indexers...

While string index signatures are a powerful way to describe the "dictionary" pattern, they also enforce that all properties match their return type. This is because a string index declares that obj.property is also available as obj["property"]. In the following example, name's type does not match the string index's type, and the type checker gives an error:

However, properties of different types are acceptable if the index signature is a union of the property types:

Finally, you can make index signatures readonly in order to prevent assignment to their indices:

You can't set myArray[2] because the index signature is readonly.

Extending Types

It's pretty common to have types that might be more specific versions of other types. For example, we might have a BasicAddress type that describes the fields necessary for sending letters and packages in the U.S.

In some situations that's enough, but addresses often have a unit number associated with them if the building at an address has multiple units. We can then describe an AddressWithUnit.

This does the job, but the downside here is that we had to repeat all the other fields from BasicAddress when our changes were purely additive. Instead, we can extend the original BasicAddress type and just add the new fields that are unique to AddressWithUnit.

The extends keyword on an interface allows us to effectively copy members from other named types, and add whatever new members we want. This can be useful for cutting down the amount of type declaration boilerplate we have to write, and for signaling intent that several different declarations of the same property might be related. For example, AddressWithUnit didn't need to repeat the street property, and because street originates from BasicAddress, a reader will know that those two types are related in some way.

interfaces can also extend from multiple types.

Intersection Types

interfaces allowed us to build up new types from other types by extending them. TypeScript provides another construct called intersection types that is mainly used to combine existing object types.

An intersection type is defined using the & operator.

Here, we've intersected Colorful and Circle to produce a new type that has all the members of Colorful and Circle.

Interfaces vs. Intersections

We just looked at two ways to combine types which are similar, but are actually subtly different. With interfaces, we could use an extends clause to extend from other types, and we were able to do something similar with intersections and name the result with a type alias. The principle difference between the two is how conflicts are handled, and that difference is typically one of the main reasons why you'd pick one over the other between an interface and a type alias of an intersection type.

Generic Object Types

Let's imagine a Box type that can contain any value - strings, numbers, Giraffes, whatever.

Right now, the contents property is typed as any, which works, but can lead to accidents down the line.

We could instead use unknown, but that would mean that in cases where we already know the type of contents, we'd need to do precautionary checks, or use error-prone type assertions.

One type safe approach would be to instead scaffold out different Box types for every type of contents.

But that means we'll have to create different functions, or overloads of functions, to operate on these types.

That's a lot of boilerplate. Moreover, we might later need to introduce new types and overloads. This is frustrating, since our box types and overloads are all effectively the same.

Instead, we can make a generic Box type which declares a type parameter.

You might read this as "A Box of Type is something whose contents have type Type". Later on, when we refer to Box, we have to give a type argument in place of Type.

Think of Box as a template for a real type, where Type is a placeholder that will get replaced with some other type. When TypeScript sees Box<string>, it will replace every instance of Type in Box<Type> with string, and end up working with something like { contents: string }. In other words, Box<string> and our earlier StringBox work identically.

Box is reusable in that Type can be substituted with anything. That means that when we need a box for a new type, we don't need to declare a new Box type at all (though we certainly could if we wanted to).

This also means that we can avoid overloads entirely by instead using [generic functions](https: //www.typescriptlang.org/docs/handbook/2/functions.html#generic-functions).

It is worth noting that type aliases can also be generic. We could have defined our new Box<Type> interface, which was:

by using a type alias instead:

Since type aliases, unlike interfaces, can describe more than just object types, we can also use them to write other kinds of generic helper types.

We'll circle back to type aliases in just a little bit.

The`Array`Type

Generic object types are often some sort of container type that work independently of the type of elements they contain. It's ideal for data structures to work this way so that they're re-usable across different data types.

It turns out we've been working with a type just like that throughout this handbook: the Array type. Whenever we write out types like number[] or string[], that's really just a shorthand for Array<number> and Array<string>.

Much like the Box type above, Array itself is a generic type.

Modern JavaScript also provides other data structures which are generic, like Map<K, V>, Set<T>, and Promise<T>. All this really means is that because of how Map, Set, and Promise behave, they can work with any sets of types.

The`ReadonlyArray`Type

The ReadonlyArray is a special type that describes arrays that shouldn't be changed.

Much like the readonly modifier for properties, it's mainly a tool we can use for intent. When we see a function that returns ReadonlyArrays, it tells us we're not meant to change the contents at all, and when we see a function that consumes ReadonlyArrays, it tells us that we can pass any array into that function without worrying that it will change its contents.

Unlike Array, there isn't a ReadonlyArray constructor that we can use.

Instead, we can assign regular Arrays to ReadonlyArrays.

Just as TypeScript provides a shorthand syntax for Array<Type> with Type[], it also provides a shorthand syntax for ReadonlyArray<Type> with readonly Type[].

One last thing to note is that unlike the readonly property modifier, assignability isn't bidirectional between regular Arrays and ReadonlyArrays.

Tuple Types

A tuple type is another sort of Array type that knows exactly how many elements it contains, and exactly which types it contains at specific positions.

Here, StringNumberPair is a tuple type of string and number. Like ReadonlyArray, it has no representation at runtime, but is significant to TypeScript. To the type system, StringNumberPair describes arrays whose 0 index contains a string and whose 1 index contains a number.

If we try to index past the number of elements, we'll get an error.

We can also [destructure tuples](https: //developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Array_destructuring) using JavaScript's array destructuring.

Tuple types are useful in heavily convention-based APIs, where each element's meaning is "obvious". This gives us flexibility in whatever we want to name our variables when we destructure them. In the above example, we were able to name elements 0 and 1 to whatever we wanted.
However, since not every user holds the same view of what's obvious, it may be worth reconsidering whether using objects with descriptive property names may be better for your API.

Other than those length checks, simple tuple types like these are equivalent to types which are versions of Arrays that declare properties for specific indexes, and that declare length with a numeric literal type.

Another thing you may be interested in is that tuples can have optional properties by writing out a question mark (? after an element's type). Optional tuple elements can only come at the end, and also affect the type of length.

Tuples can also have rest elements, which have to be an array/tuple type.

StringNumberBooleans describes a tuple whose first two elements are string and number respectively, but which may have any number of booleans following.
StringBooleansNumber describes a tuple whose first element is string and then any number of

A tuple with a rest element has no set "length" - it only has a set of well-known elements in different positions.

Why might optional and rest elements be useful? Well, it allows TypeScript to correspond tuples with parameter lists. Tuples types can be used in [rest parameters and arguments](https: //www.typescriptlang.org/docs/handbook/2/functions.html#rest-parameters-and-arguments), so that the following:

is basically equivalent to:

This is handy when you want to take a variable number of arguments with a rest parameter, and you need a minimum number of elements, but you don't want to introduce intermediate variables.

`readonly`Tuple Types

One final note about tuple types - tuples types have readonly variants, and can be specified by sticking a readonly modifier in front of them - just like with array shorthand syntax.

As you might expect, writing to any property of a readonly tuple isn't allowed in TypeScript.

Tuples tend to be created and left un-modified in most code, so annotating types as readonly tuples when possible is a good default. This is also important given that array literals with const assertions will be inferred with readonly tuple types.

Here, distanceFromOrigin never modifies its elements, but expects a mutable tuple. Since point's type was inferred as readonly [3, 4], it won't be compatible with [number, number] since that type can't guarantee point's elements won't be mutated.

Enums

Enums are one of the few features TypeScript has which is not a type-level extension of JavaScript.

Enums allow a developer to define a set of named constants. Using enums can make it easier to document intent, or create a set of distinct cases. TypeScript provides both numeric and string-based enums.

Numeric enums

We'll first start off with numeric enums, which are probably more familiar if you're coming from other languages. An enum can be defined using the enum keyword.

Above, we have a numeric enum where Up is initialized with 1 . All of the following members are auto-incremented from that point on. In other words, Direction.Up has the value 1 , Down has 2 , Left has 3 , and Right has 4 .

If we wanted, we could leave off the initializers entirely:

Here, Up would have the value 0 , Down would have 1 , etc. This auto-incrementing behavior is useful for cases where we might not care about the member values themselves, but do care that each value is distinct from other values in the same enum.

Using an enum is simple: just access any member as a property off of the enum itself, and declare types using the name of the enum:

Numeric enums can be mixed in [computed and constant members (see below)](https: //www.typescriptlang.org/docs/handbook/enums.html#computed-and- constant-members). The short story is, enums without initializers either need to be first, or have to come after numeric enums initialized with numeric constants or other constant enum members. In other words, the following isn't allowed:

String enums

String enums are a similar concept, but have some subtle [runtime differences](https: //www.typescriptlang.org/docs/handbook/enums.html#enums-at-runtime) as documented below. In a string enum, each member has to be constant-initialized with a string literal, or with another string enum member.

While string enums don't have auto-incrementing behavior, string enums have the benefit that they "serialize" well. In other words, if you were debugging and had to read the runtime value of a numeric enum, the value is often opaque - it doesn't convey any useful meaning on its own (though [reverse mapping](https: //www.typescriptlang.org/docs/handbook/enums.html#reverse-mappings) can often help). String enums allow you to give a meaningful and readable value when your code runs, independent of the name of the enum member itself.

Heterogeneous enums

Technically enums can be mixed with string and numeric members, but it's not clear why you would ever want to do so:

Unless you're really trying to take advantage of JavaScript's runtime behavior in a clever way, it's advised that you don't do this.

Computed and

constant members

Each enum member has a value associated with it which can be either _ constant_ or computed. An enum member is considered constant if:

It is the first member in the enum and it has no initializer, in which case it's assigned the value 0:

The enum member is initialized with a constant enum expression. A constant enum expression is a subset of TypeScript expressions that can be fully evaluated at compile time. An expression is a constant enum expression if it is:
1. a literal enum expression (basically a string literal or a numeric literal)
2. a reference to previously defined constant enum member (which can originate from a different enum)

In all other cases enum member is considered computed.

Union enums and enum member types

There is a special subset of constant enum members that aren't calculated: literal enum members. A literal enum member is a constant enum member with no initialized value, or with values that are initialized to

any string literal (e.g. "foo", "bar, "baz")
any numeric literal (e.g. 1, 100)

When all members in an enum have literal enum values, some special semantics come into play.

The first is that enum members also become types as well! For example, we can say that certain members can only have the value of an enum member:

The other change is that enum types themselves effectively become a union of each enum member. With union enums, the type system is able to leverage the fact that it knows the exact set of values that exist in the enum itself. Because of that, TypeScript can catch bugs where we might be comparing values incorrectly. For example:

In that example, we first checked whether x was not E.Foo . If that check succeeds, then our || will short-circuit, and the body of the ‘if' will run. However, if the check didn't succeed, then x can only be E.Foo , so it doesn't make sense to see whether it's equal to E.Bar .

Enums at runtime

Enums are real objects that exist at runtime. For example, the following enum

can actually be passed around to functions

Enums at compile time

Even though Enums are real objects that exist at runtime, the keyof keyword works differently than you might expect for typical objects. Instead, use keyof typeof to get a Type that represents all Enum keys as strings.

Reverse mappings

In addition to creating an object with property names for members, numeric enums members also get a reverse mapping from enum values to enum names. For example, in this example:

TypeScript compiles this down to the following JavaScript:

In this generated code, an enum is compiled into an object that stores both forward ( name -> value ) and reverse ( value -> name ) mappings. References to other enum members are always emitted as property accesses and never inlined.

Keep in mind that string enum members do not get a reverse mapping generated at all.

`

const` enums

In most cases, enums are a perfectly valid solution. However sometimes requirements are tighter. To avoid paying the cost of extra generated code and additional indirection when accessing enum values, it's possible to use const enums. const enums are defined using the const modifier on our enums:

const enums can only use constant enum expressions and unlike regular enums they are completely removed during compilation. const enum members are inlined at use sites. This is possible since const enums cannot have computed members.

in generated code will become

** const enum pitfalls**

Inlining enum values is straightforward at first, but comes with subtle implications. These pitfalls pertain to ambient const enums only (basically const enums in .d.ts files) and sharing them between projects, but if you are publishing or consuming .d.ts files, these pitfalls likely apply to you, because tsc --declaration transforms .ts files into .d.ts files.

For the reasons laid out in the [isolatedModules documentation](https: //www.typescriptlang.org/tsconfig#references-to- const-enum-members), that mode is fundamentally incompatible with ambient const enums. This means if you publish ambient const enums, downstream consumers will not be able to use [isolatedModules](https: //www.typescriptlang.org/tsconfig#isolatedModules) and those enum values at the same time.
You can easily inline values from version A of a dependency at compile time, and import version B at runtime. Version A and B's enums can have different values, if you are not very careful, resulting in [surprising bugs](https: //github.com/microsoft/TypeScript/issues/5219#issue-110947903), like taking the wrong branches of if statements. These bugs are especially pernicious because it is common to run automated tests at roughly the same time as projects are built, with the same dependency versions, which misses these bugs completely.

Here are two approaches to avoiding these pitfalls:

A. Do not use const enums at all. You can easily [ban const enums](https: //github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/linting/FAQ.md#how-can-i-ban-specific-language-feature) with the help of a linter. Obviously this avoids any issues with const enums, but prevents your project from inlining its own enums. Unlike inlining enums from other projects, inlining a project's own enums is not problematic and has performance implications. B. Do not publish ambient const enums, by de constifying them with the help of [preserve constEnums ](https: //www.typescriptlang.org/tsconfig#preserve constEnums). This is the approach taken internally by the [TypeScript project itself](https: //github.com/microsoft/TypeScript/pull/5422). [preserve constEnums ](https: //www.typescriptlang.org/tsconfig#preserve constEnums)emits the same JavaScript for const enums as plain enums. You can then safely strip the const modifier from .d.ts files [in a build step](https: //github.com/microsoft/TypeScript/blob/1a981d1df1810c868a66b3828497f049a944951c/Gulpfile.js#L144).

This way downstream consumers will not inline enums from your project, avoiding the pitfalls above, but a project can still inline its own enums, unlike banning const enums entirely.

Ambient enums

Ambient enums are used to describe the shape of already existing enum types.

One important difference between ambient and non-ambient enums is that, in regular enums, members that don't have an initializer will be considered constant if its preceding enum member is considered constant. By contrast, an ambient (and non- const) enum member that does not have an initializer is always considered computed.

Objects vs Enums

In modern TypeScript, you may not need an enum when an object with as const could suffice:

React

Folder and File Structure

Each component should have its own folder nested inside the /components folder. The name of this folder should match the name of the component itself. Inside this folder you should have the following files:

data.js
- contains a copy of the JSS fields object for this component. This will get imported in unit tests and Storybook stories. If the component doesn't get called from Sitecore and doesn't have JSS fields, then this file isn't needed.
index.tsx
- main React component
stories.js
- Storybook stories
styles.ts(x) (optional)
- if you use Styled Components for the component, they will live here
test.tsx
- Jest unit tests
types.ts
- Typescript types and interfaces the component

Composition File

Before working on the React component itself we first need to compose simpler props for it instead of parsing through the JSS fields object directly. The goal is to turn something like this:

into this:

The composition file is located at lib/composition/index.js and contains an exported function for each of the React components. The JSS fields object (and sometimes placeholder object) from Sitecore is passed in and destructured. Using the ComponentTypes global Typescript type both as a reference and consistent naming convention amongst all of the components, you will use these as keys to build your return object which will be passed in as the final props object to your component.

In the following example, the QuickLinks component will get a single items prop returned to it, which will consist of an array of objects

Optional Chaining

An important thing to note and best practice is to use optional chaining when reaching into an object. The (?.) operator allows you to reach as far down into a nested object without first having to validate that the previous step in the chain is valid and exists first.

[MDN - Optional Chaining](https: //developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining)

Function Components

We should always use function components with hooks over class components. Function components are 'stateless' and simple as they don't track state or have lifecycle and render methods like class components do. If you need to track state in your component, import the useState hook.

Use Short Syntax Over React Fragments

If your return content doesn't have a wrapping div you will need to create a fragment by using a short syntax element <> rather than a React <Fragment>. The only exception is if you need to use a key when using a map. In these instances you will need to use a <Fragment> [React Short Syntax](https: //reactjs.org/docs/fragments.html#short-syntax)

🚫 Bad

✅ Good

Use Implicit Returns

With ES6 and arrow functions you can omit the curly braces and the return keyword if your component is immediately returning something.

🚫 Bad

✅ Good

Use PascalCase and Export At The End Of The File

Component names should always be PascalCased and exported at the bottom of the file. If there is more than one component to export you need to declare which one is the default export:

Spread and Destructure

Where possible always destructure props and other objects/arrays where used. This will help in typing and keeping things clear and not hidden behind a root object. If you don't need to destructure out all of the properties of an object, use the ...rest keyword and pass that in instead like so:

🚫 Bad

✅ Good

If you're not transforming the props names from the parent to the child, then you can omit setting them directly on the child and instead just spread them in with the {...rest} property.

Small, Focused and DRY

Our components should be broken down into small, reusable functions instead of one gigantic component.

🚫 Bad

✅ Good

Each component should do only one thing and only be responsible for the logic for that one thing. If your function is growing in size, it's probably time to refactor it into smaller, more focused components. This will also help in making our components more reusable, consistent and TESTABLE.

React | Typescript | Tailwind | Forms | Unit Tests

Accessability

Understanding Techniques for WCAG Success Criteria

Introduction to Web Accessibility | Web Accessibility Initiative (WAI) | W3C

Excerpt
The Website of the World Wide Web Consortium’s Web Accessibility Initiative.

Page Contents

Accessibility in Context

The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect.

The Web is fundamentally designed to work for all people, whatever their hardware, software, language, location, or ability. When the Web meets this goal, it is accessible to people with a diverse range of hearing, movement, sight, and cognitive ability.

Thus the impact of disability is radically changed on the Web because the Web removes barriers to communication and interaction that many people face in the physical world. However, when websites, applications, technologies, or tools are badly designed, they can create barriers that exclude people from using the Web.

Accessibility is essential for developers and organizations that want to create high-quality websites and web tools, and not exclude people from using their products and services.

What is Web Accessibility

Web accessibility means that websites, tools, and technologies are designed and developed so that people with disabilities can use them. More specifically, people can:

perceive, understand, navigate, and interact with the Web
contribute to the Web

Web accessibility encompasses all disabilities that affect access to the Web, including:

auditory
cognitive
neurological

Web accessibility also benefits people without disabilities, for example:

people using mobile phones, smart watches, smart TVs, and other devices with small screens, different input modes, etc.
older people with changing abilities due to ageing
people with “temporary disabilities” such as a broken arm or lost glasses

For a 7-minute video with examples of how accessibility is essential for people with disabilities and useful for everyone in a variety of situations, see:

Accessibility is Important for Individuals, Businesses, Society

The Web is an increasingly important resource in many aspects of life: education, employment, government, commerce, health care, recreation, and more. It is essential that the Web be accessible in order to provide equal access and equal opportunity to people with diverse abilities. Access to information and communications technologies, including the Web, is defined as a basic human right in the United Nations Convention on the Rights of Persons with Disabilities (UN ).

The Web offers the possibility of unprecedented access to information and interaction for many people with disabilities. That is, the accessibility barriers to print, audio, and visual media can be much more easily overcome through web technologies.

Accessibility supports social inclusion for people with disabilities as well as others, such as:

older people
people in rural areas
people in developing countries

There is also a strong business case for accessibility. As shown in the previous section, accessible design improves overall user experience and satisfaction, especially in a variety of situations, across different devices, and for older users. Accessibility can enhance your brand, drive innovation, and extend your market reach.

Web accessibility is required by law in many situations.

Making the Web Accessible

Web accessibility depends on several components working together, including web technologies, web browsers and other "user agents", authoring tools, and websites.

The W3C Web Accessibility Initiative () develops technical specifications, guidelines, techniques, and supporting resources that describe accessibility solutions. These are considered international standards for web accessibility; for example, WCAG 2.0 is also an ISO standard: ISO/IEC 40500.

Making Your Website Accessible

Many aspects of accessibility are fairly easy to understand and implement. Some accessibility solutions are more complex and take more knowledge to implement.

It is most efficient and effective to incorporate accessibility from the very beginning of projects, so you don’t need go back and to re-do work.

Evaluating Accessibility

When developing or redesigning a website, evaluate accessibility early and throughout the development process to identify accessibility problems early, when it is easier to address them. Simple steps, such as changing settings in a browser, can help you evaluate some aspects of accessibility. Comprehensive evaluation to determine if a website meets all accessibility guidelines takes more effort.

There are evaluation tools that help with evaluation. However, no tool alone can determine if a site meets accessibility guidelines. Knowledgeable human evaluation is required to determine if a site is accessible.

Examples

Alternative Text for Images

Images should include (alt text) in the markup/code.

If alt text isn’t provided for images, the image information is inaccessible, for example, to people who cannot see and use a screen reader that reads aloud the information on a page, including the alt text for the visual image.

When equivalent alt text is provided, the information is available to people who are blind, as well as to people who turn off images (for example, in areas with expensive or low bandwidth). It’s also available to technologies that cannot see images, such as search engines.

Keyboard Input

Some people cannot use a mouse, including many older users with limited fine motor control. An accessible website does not rely on the mouse; it makes . Then people with disabilities can use that mimic the keyboard, such as speech input.

Transcripts for Audio

Just as images aren’t available to people who can’t see, audio files aren’t available to people who can’t hear. Providing a text transcript makes the audio information accessible to people who are deaf or hard of hearing, as well as to search engines and other technologies that can’t hear.

It’s easy and relatively inexpensive for websites to provide transcripts. There are also that create text transcripts in HTML format.

For More Information

W3C WAI provides a wide range of resources on different aspects of web accessibility , , , . We encourage you to explore this website, or look through the list.

Excerpt

WCAG 2.1 guidelines and success criteria are designed to be broadly applicable to current and future web technologies, including dynamic applications, mobile, digital television, etc. They are stable and do not change.

WCAG 2.1 guidelines and success criteria are designed to be broadly applicable to current and future web technologies, including dynamic applications, mobile, digital television, etc. They are stable and do not change.

Specific guidance for authors and evaluators on meeting the WCAG success criteria is provided in techniques, which include code examples, resources, and tests. W3C's document is updated periodically, about twice per year, to cover more current best practices and changes in technologies and tools.

The three types of guidance in are explained below:

Sufficient techniques
Advisory techniques
Failures

Also explained below:

General and technology-specific techniques - which can be sufficient or advisory
Other techniques - beyond what is in W3C's published document
Technique tests

provides related information, including on .

Techniques are Informative

Techniques are informative—that means they are not required. The basis for determining conformance to WCAG 2.1 is the success criteria from the WCAG 2.1 standard—not the techniques.

Note 1: W3C cautions against requiring W3C's sufficient techniques. The only thing that should be required is meeting the WCAG 2.1 success criteria. To learn more, see:

in the WCAG 2 FAQ

Note 2: uses the words "must" and "should" only to clarify guidance within the techniques, not to convey requirements for WCAG.

Sufficient Techniques

Sufficient techniques are reliable ways to meet the success criteria.

From an author's perspective: If you use the sufficient techniques for a given criterion correctly and it is for your users, you can be confident that you met the success criterion.
From an evaluator's perspective: If web content implements the sufficient techniques for a given criterion correctly and it is for the content's users, it conforms to that success criterion. (The converse is not true; if content does not implement these sufficient techniques, it does not necessarily fail the success criteria, as explained in below.)

There may be other ways to meet success criteria besides the sufficient techniques in W3C's document, as explained in below. (See also above.)

Numbered Lists, "AND"

The W3C-documented sufficient techniques are provided in a numbered list where each list item provides a technique or combination of techniques that can be used to meet the success criterion. Where there are multiple techniques on a numbered list item connected by "AND" then all of the techniques must be used to be sufficient. For example, has: "G115: Using semantic elements to mark up structure AND H49: Using semantic markup to mark emphasized or special text (HTML)".

Advisory Techniques

Advisory techniques are suggested ways to improve accessibility. They are often very helpful to some users, and may be the only way that some users can access some types of content.

Advisory techniques are not designated as sufficient techniques for various reasons such as:

they may not be sufficient to meet the full requirements of the success criteria;
they may be based on technology that is not yet stable;
they may not be in many cases (for example, assistive technologies do not work with them yet);

Authors are encouraged to apply all of the techniques where appropriate to best address the widest range of users' needs.

Failures

Failures are things that cause accessibility barriers and fail specific success criteria. The documented failures are useful for:

Authors to know what to avoid,
Evaluators to use for checking if content does not meet WCAG success criteria.

Content that has a failure does not meet WCAG success criteria, unless an alternate version is provided without the failure.

If anyone identifies a situation where a documented failure is not correct, please so that it can be corrected or deleted as appropriate.

General and Technology-specific Techniques

General techniques describe basic practices that apply to all technologies. Technology-specific techniques apply to a specific technology.

Some success criteria do not have technology-specific techniques and are covered only with general techniques. Therefore, both the general techniques and the relevant technology-specific techniques should be considered.

Publication of techniques for a specific technology does not imply that the technology can be used in all situations to create content that meets WCAG 2.1 success criteria and conformance requirements. Developers need to be aware of the limitations of specific technologies and provide content in a way that is accessible to people with disabilities.

Other Techniques

In addition to the techniques in W3C's document, there are other ways to meet WCAG success criteria. W3C's techniques are not comprehensive and may not cover newer technologies and situations.

Web content does not have to use W3C's published techniques in order to conform to WCAG 2.1.__(See also above.)

Content authors can develop different techniques. For example, an author could develop a technique for HTML5, , or other new technology. Other organizations may develop sets of techniques to meet WCAG 2.1 success criteria.

Any techniques can be sufficient if:

they satisfy the success criterion, and
all of the are met.

Submitting Techniques

The WCAG Working Group encourages people to submit new techniques so that they can be considered for inclusion in updates of the document. Please submit techniques for consideration using the .

Testing Techniques

Each technique has tests that help:

authors verify that they implemented the technique properly, and
evaluators determine if web content meets the technique.

The tests are only for a technique, they are not tests for conformance to WCAG success criteria.

Failing a technique test does not necessarily mean failing WCAG, because the techniques are discrete (that is, they address one specific point) and they are not required.
Content can meet WCAG success criteria in different ways other than W3C's published sufficient techniques.
Content that passes the sufficient techniques for a specific technology does not necessarily meet all WCAG success criteria. Some success criteria have only general techniques, not technology-specific techniques.

Thus while the techniques are useful for evaluating content, evaluations must go beyond just checking the sufficient technique tests in order to evaluate how content conforms to WCAG success criteria.

Failures are particularly useful for evaluations because they do indicate non-conformance (unless an alternate version is provided without the failure).

User Agent and Assistive Technology Support Notes

Some techniques require that web content users have specific browsers or assistive technologies in order for the technique to be . The User Agent and Assistive Technology Support Notes sections of individual techniques include some information to help determine accessibility support.

Support Notes Change Over Time

As time passes, the versions of user agents (browsers, etc.) or assistive technologies listed may not be the current versions. The Working Group may not update most of these notes as new versions are released. Authors should test techniques with the user agents and assistive technologies currently available to their users. See also .

Using the Techniques

is not intended to be used as a stand-alone document. Instead, it is expected that content authors will usually use to read the WCAG success criteria, and follow links from there to specific topics in Understanding WCAG 2.1 and to specific techniques.

Alternatives must meet success criteria

Some techniques describe how to provide alternate ways for users to get content. For example, mentions a transcript as an alternative for an audio file. Some alternatives must also conform to WCAG. For example, the transcript itself must meet all relevant success criteria.

Example Code

The code examples in the techniques are intended to demonstrate only the specific point discussed in the technique. They might not demonstrate best practice for other aspects of accessibility, usability, or coding not related to the technique. They are not intended to be copied and used as the basis for developing web content.

Many techniques point to "working examples" that are more robust and may be appropriate for copying and integrating into web content.

Typescript

`Global types`

In typescript global types can be declared in a .d.ts file and used anywhere without explicitly importing them. Our project's .d.ts file is named project.d.ts.

project.d.ts

It contains:

Some library types in the form of [triple slash directives](https: //www.typescriptlang.org/docs/handbook/triple-slash-directives.html). These need to be placed at the top of the file.
Some library module declarations (usually these are included because these libs don't have typings but we still need to use them).
Our own global types.

Typescript provides many [Utility Types](https: //www.typescriptlang.org/docs/handbook/utility-types.html) which are useful for manipulating the base types in the global ComponentTypes interface.

Utility Types

TypeScript: Documentation - Utility Types

Excerpt

Types which are globally included in TypeScript

TypeScript provides several utility types to facilitate common type transformations. These utilities are available globally.

A few basic ones to know:

`Pick<Type, Keys>`

Only use the specified Keys from the Type.

`Partial<Type>`

Allows the type to be optional (undefined)

`Required<Type>`

Opposite of Partial, the type must be defined

Using the stategies above you can select types from the global source and compose them to create a representation of the props in a specific component. While the global types live in project.d.ts, component level types should generally be placed in a types.ts file within the component directory and imported for use.

Although ComponentTypes is a ✅ _Good starting place, some components may require a type that is more specific and not usefully included in the global declaration._

`Naming`

`class`

🧑‍🔬 PascalCase

🚫 Bad

✅ Good

For memebers/methods use 🐪 camelCase

🚫 Bad

✅ Good

`enum`

🧑‍🔬 PascalCase

🚫 Bad

✅ Good

`interface`

🧑‍🔬 PascalCase

🚫 Bad

✅ Good

For memebers use 🐪 camelCase

🚫 Bad

✅ Good

`namespace`

🧑‍🔬 PascalCase

🚫 Bad

✅ Good

`type`

🧑‍🔬 PascalCase

🚫 Bad

✅ ✅ Good

`variable and function`

🐪 camelCase

🚫 Bad

✅ Good

React | Typescript | Tailwind | Forms | Unit Tests

// composition/index.js

const QuickLinks = ({ fields }) => {
  const items = fields?.QuickLinkItems?.reduce(
    (acc, curr) => [
      ...acc,
      {
        image: { ...curr.Icon?.value },
        link: curr.Link?.value?.href,
        title: curr.Title?.value,
        id: curr.Id,
      },
    ],
    []
  );
  return { items };
};

// components/QuickLinks/index.tsx

const QuickLinks = ({ items }: { items: Array<ComponentTypes> }) => (
  <QuickLinksWrapper>
    {items?.map(({ id, ...rest }, index) => (
      <QuickLinksItem index={index} length={items.length} key={id} {...rest} />
    ))}
  </QuickLinksWrapper>
);

{
  componentName: 'ContentMain',
  content: [{
      uid: '',
      componentName: 'Single Step Form',
      dataSource: '',
      fields: {
          ModelJson: {
              value: '[ { "title":"Form Name", "fields":{ "Name":{ "label":"Form Name", "type":"input", "value":"Form Name", "name":"Name" }, "Id":{ "label":"Id", "type":"hidden", "value":"", "name":"Id" } }, "fresh":true }, { "title":"Text Input", "fields":{ "FormId":{ "label":"FormId", "type":"hidden", "value":"stepOne", "name":"FormId" }, "Name":{ "label":"Name", "type":"hidden", "value":"textinput", "name":"Name" }, "Id":{ "label":"Id", "type":"input", "value":"fixtureName", "name":"Id" }, "Label":{ "label":"Label", "type":"input", "value":"Fixture Selection", "name":"Label" }, "BackEndLabel":{ "label":"BackEnd Label", "type":"input", "value":"Fixture Selection", "name":"BackEndLabel" }, "Value":{ "label":"Default Value", "type":"input", "value":"", "name":"Value" }, "DefaultValueSource":{ "label":"Default Value Source", "type":"select", "value":[ { "value":"None", "selected":false, "label":"None" }, { "value":"cookie", "selected":true, "label":"Cookie" } ], "name":"DefaultValueSource" }, "DefaultValueKey":{ "label":"Default Value Source Key", "type":"input", "value":"fixtureName", "name":"DefaultValueKey"}]
          }
      }
  }]
}

- `createdFields` is memoized to cache the original value and keep it from re-rendering each cycle
- The `false` parameter signifies that its not to return a multidimensional array, just a single array

5. `createFormInit()` is a 'factory' for both `<SingleStepForm />` and `<MultiStepForm />`. We will focus on what happens if this is called from `<SingleStepForm />`.

```typescript

const createFormInit: {
  (arr: Array<ParsedFormModel>, multi: true): CFReturnType[][];
  (arr: Array<ParsedFormModel>, multi: false): CFReturnType[];
} = (arr: Array<ParsedFormModel>, multi: boolean): any => {
  return multi ? multiStepFormFields(arr) : parseFields(arr);
};

const parseFields = (arr: Array<ParsedFormModel>) => {

const items = arr.reduce((acc: Array<CFReturnType | null>, curr) => {

const formField = createForm(curr);
    return [...acc, formField];
  }, []);

// filter out any null values due to early returns from hidden fields
  return items.filter(Boolean) as Array<CFReturnType>;
};

- `dataMap`

  - `dataMap` is an object with `inputMap` values as the key and related props as the value. All of these will contain a 'file' value. This is the name of the React component that will be dynamically imported, and some of them will contain a 'props' value. Props is an object that contains more details for that particular input type such as type, icon, masking function etc..

    ```javascript

    ```

const dataMap: CFMappingType["dataMap"] = {

// ...
input: {
file: "Input",
props: { type: "text" },
},
phone: {
file: "Input",
props: {
type: "tel",
icon: "phone",
mask: masks.tel,
},
},
radio: {
file: "RadioGroup",
},

// ...
};

2. Inside `createForm()` it will take the incoming field name and use it to index `inputMap`. At this point one of three things will happen:
   - It will find a match and return that input type
   - It will return a null value (these are currently hidden fields or unimportant fields)
   - It will return undefined\
     \
     If it returns a type we will continue, if it returns a null we return a null out of createForm(), if its undefined we then assume and assign this field with a type 'input'
3. Now that we have the field type (the `inputType` value), we use this to index `dataMap` and return the file and or props from that

   - We take this file name and dynamically import that component (ie: 'Input', 'Heading', 'RadioGroup', 'Tabs', etc..)

   ```javascript

4. We then now build our return object which gets added to the array in `parseFields()` and gets sent back to `<SingleStepForm />`

```javascript
return {
  Component,
  data: getData(fields, title),
  file,
  formName: fields?.FormId?.value,
  id: uid(32),
  props: {
    columns: getColumnWidth(fields.ColumnWidth?.value),
    ...props,
  },
  validations: getValidations(file, fields, props?.type),
};

const getData: GetDataProps = ({ fields, title }) => ({
  customValidationErrorMsg:
    fields?.CustomValidationErrorMsg?.value || "field is required",
  items: parseItems(fields?.InputItems?.value),
  label: fields?.Label?.value || "",
  maxLength: parseInt(fields?.MaximumLength?.value) || 524288,
  minLength: parseInt(fields?.MinimumLength?.value) || 0,
  name: fields?.Name?.value,
  placeholder: fields?.PlaceholderText?.value,
  required: fields?.Required?.value || false,
  tabs: fields?.Tabs?.value.split("\n") || [],
  title,
  toolTipText: fields?.TooltipText?.value,
});

const getValidations: GetValidationProps = (file, fields, regex = "") => {
  const skipValidation = ["Heading", "Recaptcha", "Tabs"];
  let pattern;

  if (file && skipValidation.includes(file)) return null;

  // Validations will usually come through as a string value from sitecore

  // but can also come through as an array of objects, these have the type 'select'

  // We first need to parse through this array and grab the value of the selected validation pattern
  if (fields?.ValidationPattern?.type === "select") {
    pattern = getSelectedValue(fields.ValidationPattern.value);
  } else {
    pattern = fields?.ValidationPattern?.value;
  }

  return {
    shouldConfirm: fields?.AppearsOnFormConfirmation?.value,
    validationPattern:
      // 1. by regex in mapping props (phone, ssn)

      // 2. by named regex pattern coming from Sitecore
      regexMap[regex] || regexMap[pattern],
  };
};

   return (
     <div className="relative">
       <InputText {...propData} />
       <div className="hidden lg:block absolute top-0 right-0 mt-4 lg:-mr-48">
         <Tooltip error={Boolean(errors[name])} message={toolTipText} />
       </div>
     </div>
   );
 };
 ```

const formModel: Array<ParsedFormModel> = JSON.parse(modelJson.value);

const createdFields = useMemo(() => createFormInit(formModel, true), []);

const createdFieldsWithoutTabs = [...createdFields.slice(1), []];

const createdFieldsOnlyTabFields = [
  ...createdFields[0][0].data.tabs,
  "Confirmation",
];

// ... return
<FormComponent onSubmit={handleFormSubmit}>
  <FormStepper activeIndex={activeIndex} content={createdFieldsOnlyTabFields} />
  {createdFieldsWithoutTabs.map((innerArray, index) =>
    innerArray.map(
      ({ Component, data, id, props, validations, ...rest }: CFReturnType) => {
        return (
          <FieldWrapper
            className={index === activeIndex ? "block" : "hidden"}
            columns={props?.columns}
            key={id}
          >
            <Component
              register={register({
                pattern: regexPattern(validations),
                required: isRequired(data),
                validate: {
                  match: (value: string) =>
                    matchingEmails(
                      name.toLowerCase(),
                      value,
                      getValues(["email", "emailconf"])
                    ),
                },
              })}
              {...{ data, errors, name, props, ...rest }}
            />
          </FieldWrapper>
        );
      }
    )
  )}
  {isLastStep && <ConfirmationStep data={confirmedValues} {...{ fields }} />}
  <ButtonWrapper />
</FormComponent>;

DUKE

Site Navigation

hashtag🗺 Site Navigation

hashtag

Udemy

Site Navigation

hashtagMulti Step Forms

Jira Tickets

DNT-2860 Go Green Calculator

DNT-2843 EVCalculator

hashtagControls:

DNT-2657 Lists must be contained within semantically correct containers

DNT-2658 Components must receive focus in an order that preserves meaning and operability

DNT-2658

Docs

Jira Tickets

DNT-2843 EVCalculator

hashtagControls:

DNT-2860 Go Green Calculator

Udemy

Site Navigation

hashtag🗺 Site Navigation

hashtag

DNT-2657 Lists must be contained within semantically correct containers

Site Navigation

hashtagMulti Step Forms

DNT-2658 Components must receive focus in an order that preserves meaning and operability

DNT-2658

Docs

hashtagStories

hashtagArgs

hashtagControls

hashtagA11y and Other Addons

hashtagAnatomy of a Story

hashtagstorybookCustomArgs

hashtagcreateStoryOptions

hashtagResources

hashtagDuke Training:

hashtagTable of contents

hashtagGeneral Info

hashtagSitecore

hashtagRelated Links

DNT-2930 Hero Component

hashtagHero

hashtagUsage Guidance

hashtagSay Yes to Renewables

hashtagAccessibility

DNT-2423 Throttle scroll event listeners

Throtteling Event Listeners

DNT-2785

Code Review:

hashtag

DNT-2659 A meaningful image must have a text alternative that serves the equivalent purpose

Duke Company

hashtagPortal Guide - Home

Personal

DNT-2724 Accordion Testing

hashtagState of the Code Review

hashtagWhy Improve Code Review?

hashtagGoing Forward

hashtagGeneral suggestions:

hashtagThings to think about and maybe discuss:

hashtagFor the 20% currently doing 80% of the reviewing:

hashtagFor the 80%:

Typescript Tricks

Component Creation

README

Analytics

hashtagTesting Analytics

hashtagPortal Site Managers

hashtagPORTAL GUIDE

hashtagManage Your Information

hashtagPORTAL GUIDE

hashtagAccessing the Portal Remotely

hashtagPORTAL GUIDE

hashtagIntranet Design Awards

hashtagPORTAL GUIDE

hashtagBitLocker keys for LAPTOP-9LGJ3JGS

DefinitionOfDone

hashtagComponent Creation - Definition of Done

🗺 Site Navigation

Multi Step Forms

Controls:

Controls:

🗺 Site Navigation

Multi Step Forms

Stories

Args

Controls

A11y and Other Addons

Anatomy of a Story

storybookCustomArgs

createStoryOptions

Resources

Duke Training:

Table of contents

General Info

Sitecore

Related Links

Hero

Usage Guidance

Say Yes to Renewables

Accessibility

Portal Guide - Home

State of the Code Review

Why Improve Code Review?

Going Forward

General suggestions:

Things to think about and maybe discuss:

For the 20% currently doing 80% of the reviewing:

For the 80%:

Testing Analytics

Portal Site Managers

PORTAL GUIDE

Manage Your Information

PORTAL GUIDE

Accessing the Portal Remotely

PORTAL GUIDE

Intranet Design Awards

PORTAL GUIDE

BitLocker keys for LAPTOP-9LGJ3JGS

Component Creation - Definition of Done

Our "Definition of Done" for a Component

Checklist

Component Creation - Sitecore

Sitecore and You

Sitecore Component Creation Overview

Basic Instructions for Creating a Component

Component Creation - Technical Overview

Component Creation - Intro

Component Creation - Practical Overview

Creating the FormField

Introduction

Types vs. interfaces in TypeScript - LogRocket Blog

Types and type aliases

Types vs. interfaces

Declaration merging

Extends and implements

Intersection

Unions

Tuples

What should I use?

Conclusion

Workflow - A Practical Overview

The Approach

Checklist

A Technical Overview

Generate Component Factory

Passing Down Data Via Composition

Adding files for your component

`Index.tsx`

`Test.tsx`

`Types.ts`

`Stories.js`

`Data.js`

The folder

Side note: Important info

Inside the FormField

MultiStepForm

Philosophy and Approach