Forem: Andrew Petersen

Rsvp to weddings with XState

Andrew Petersen — Fri, 19 Feb 2021 18:51:50 +0000

I am building the RSVP form for my wedding website and I want allow guests to look themselves up based on their street number.

Happy Path
On the wedding site, the happy path is something like this:

Ask for the Street Number
Perform the lookupGuest API call
When a guest is found by their street number, display the RSVP form
Guest fills out and submits the RSVP form
POST to the submitRsvp endpoint
Display a thank you message

Things seems pretty easy! I should be able to knock it out in an evening. But wait....

Complexities

What if we don't find a guest by street number?
If a guest has already submitted the RSVP, then they:
- should see how they previously responded.
- shouldn't be able to submit again.
Street number isn't guaranteed to be unique because we sent multiple invitations to the same address.
What if any of those API calls fail?

State Machines to the rescue!

In this walkthrough, I'll solve those complexities and more with an XState machine.

DavidKPiano has single handedly put state machines on the map in the front end community (I don't think he gets enough credit for it). Every time I consume his content I think, "Whoa! why isn't everyone doing this?!"
However, in practice I've reached for them a few times, and it always goes like this:

It takes me a while to remember how to shift my thinking (I get set in my imperative ways). Then it takes me a little bit to look up the syntax.
Once I do though, I LOVE it! It is so clean and maintainable.
But then, I go off onto another project that isn't using them and forget everything again.

State machines and XState don't have to be complicated monsters that require a CompSci PHD to wrangle. If you learn just the easiest 10%, you can solve 90% of your problems.

I'm writing this post to help cement my state machine habits, and to serve as a quick reference.

Define your states

First think through all the different states your UI could be in. For the RSVP scenario I'll have:

unknown - This is where I'll ask the guest to look themselves up by street number
finding - This will show a loading indicator while waiting for the /lookupGuest api call
choosing - This is where I'll show the guest a list of guests who match the entered street number.
checkingRsvp - This is a "transient" state. It's a router. Once a guest is chosen, it'll instantly check to see if that guest has already rsvp'd and route to responded or unresponded
unresponded - This will show the RSVP form
responded - This will show a readonly view of how the guest RSVPd. This is the last and final step.

Here is how you'd represent that with XState

const rsvpMachine = Machine({
  id: 'rsvp',
  initial: 'unknown',
  context: { },
  states: {
    unknown: {},
    finding: {},
    choosing: {},
    checkingRsvp: {},
    unresponded: {},
    submitting: {},
    responded: {
      type: "final"
    },
  }
});

If you want to follow along, try pasting this state chart into the XState Visualizer. I built the entire thing this way first, then copy/pasted it into my project.

Define the context

What data needs to stick around between states?

In my case, it will be the guest lookup results, and the chosen guest. I'll set them both to null to start. In an upcoming step, the state machine will pass the context to functions like checkHasResponded to decide which state to transition to.

const checkHasResponded = (context) => context.guest && context.guest.rsvp;
const checkHasNotResponded = (context) => context.guest && !context.guest.rsvp;
const checkAlreadyChosen = (context) => context.guest;

const rsvpMachine = Machine({
  id: 'rsvp',
  initial: 'unknown',
  context: {
    results: null,
    guest: null,
  },
  ...
});

Define the user driven events

For each state, what activities can the the user perform?

For example, you can FIND when in the unknown state, but you CAN'T FIND when in the submitting state.

When in the unknown state, a guest can FIND themselves by street number, and it should send them to the finding state
When in the choosing state, a guest can CHOOSE which lookup result is them, and it should send them to the checkingRsvp state.
Entering the checkingRsvp should automatically route to the responded or unresponded state.
When in the unresponded state a guest can SUBMIT their RSVP, transitioning them to the submitting state

There are 2 noticeable gaps in the state chart:

How do you get from finding to choosing ?
How do you get from submitting to responded?
Both of these are tied to API calls instead of an explicit user interaction.
I'll cover this in the next step.

Here is the full state machine so far. The events described above are setup with the on property.

The interesting one is checkingRsvp. There the event key is blank, which means it will automatically fire. Then, the blank event key is passed multiple targets, each with a condition so it can route accordingly. XState calls this a transient transition.

const checkHasResponded = (context) => context.guest && context.guest.rsvp;
const checkHasNotResponded = (context) => context.guest && !context.guest.rsvp;
const checkAlreadyChosen = (context) => context.guest;

const rsvpMachine = Machine({
  id: "rsvp",
  initial: "unknown",
  context: {
    results: null,
    guest: null,
  },
  states: {
    unknown: {
      on: {
        FIND: "finding",
      },
    },
    finding: {},
    choosing: {
      on: {
        CHOOSE: "checkingRsvp",
      },
    },
    checkingRsvp: {
      on: {
        "": [
          {
            target: "unresponded",
            cond: checkHasNotResponded,
          },
          {
            target: "responded",
            cond: checkHasResponded,
          },
        ],
      },
    },
    unresponded: {
      on: {
        SUBMIT: "submitting",
      },
    },
    submitting: {},
    responded: {
      type: "final",
    },
  },
});

Invoking services

The last big piece is figuring out how to make an API call when entering the finding or the submitting state. This is done via XState's invoke property.

To setup an invoke for for the finding state:

Use invoke.src to call an async function, lookupGuest
Setup onDone.target to transition to next state when the async call completes
Setup onDone.actions to assign the async result (found in event.data ) onto the context
- XState handles taking the result of the async function and putting it onto event.data

const rsvpMachine = Machine({
  ...
  states: {
    ...
    finding: {
      invoke: {
        id: "lookupGuest",
        // Call the async fn
        src: (context, event) => lookupGuest(event.lookupId),
        onDone: {
          // once the async call is complete 
      // move to the 'choosing' state
          target: 'choosing',
          // use xstate's assign action to update the context
          actions: assign({ 
            // store the results in context
            results: (_, event) => event.data,
            // if there was only one result, set the guest
            guest: (_, event) => event.data.length === 1 ? event.data[0] : null
          })
        }
      },
    },
    ...
  },
});

After implementing the same kind of thing for the submitting state I was done with the RSVP state machine!

Use it in the UI

You can take a state machine like this and use XState with your framework of choice (vanilla, React, Angular, Vue etc...).

Here's an example of what a React usage might feel like. You can see the current state with state.value and you can interact with the state machine by using send to trigger state transition events.

function Rsvp() {
  const [state, send] = useMachine(rsvpMachine);

  if (state.value === "unknown") {
    return (
      <GuestLookupForm
        onSubmit={(streetNumber) =>
          send({ type: "FIND", lookupId: streetNumber })
        }
      />
    );
  }

  if (state.value === "finding") {
    return <Loading />;
  }

  if (state.value === "choosing") {
    return (
      <ChooseGuest
        guests={state.context.results}
        onSelect={(guest) => send({ type: "CHOOSE", guest})}
      />
    );
  }

  // ...You get the gist
}

Conclusion

It took me an hour or two to build the state chart (all in the visualizer), but once it was done the UI literally just fell into place.

So while it seems like more work up front, it is SOOO worth it! You'd end up working through these complexities regardless. Tackling the logic problems before they are muddied by UI quirks make the solutions so much cleaner and maintainable.

This also just naturally solves problems like "What if I forget to disable the submit button on click, and the user repeatedly mashes on it. Will that submit a bunch of RSVPs?"

With a state machine, the first click would transition to submitting and after that, the user can send a SUBMIT action all they want, but submitting state will just ignore it.

Final Result

Here is the final version of the State Chart, with the additional START_OVER and onError capabilities.
This was generated with David's statecharts.io Inspector

Here is a codesandbox demo using the RSVP state machine in React. Take a peek at the source, machine.js, if you are curious what the final state machine code looks like.

New React Component Pattern? Compound Components w/ a Hook

Andrew Petersen — Wed, 10 Feb 2021 22:55:17 +0000

TL;DR

React Components == UI and React Hooks == Behavior
Often, UI is coupled to behavior. That's okay.
- isOpen, and closeModal (Behavior), feel pretty coupled to a Modal component (UI).
Sometimes the parent component needs access to that "behavior data".
- So should the parent own the "behavior data" even though it is coupled to the child component?
- Ex: The parent creating a Modal needs to know if a modal has closed so the parent can cancel an async request. So does the parent have to own the isOpen state and recreate the modal boilerplate every usage?
The big thesis: Expanding the Compound Components pattern to also return hooks could be an elegant solution.

Here is the final solution if want to jump straight into the code*.

https://codesandbox.io/s/compount-components-with-a-hook-txolo

*I am using a Material UI table here because this stemmed from a work project. However, the concepts should apply with or without a component library.

In this article I am building a Table component, but in a previous article, I ran into similar problems building a Modal. There, I experimented with returning a Component definition from a custom React hook. Here, I flip it and return the hook on the Component.

Coupled UI & Behavior

The fundamental problem is that you have UI and behavior that are tightly coupled. You need the "behavior data" inside the component to render, but you also need access to the "behavior data" outside/above the component.

For example you want a custom Table component that can:

Be used very simply just to encapsulate some brand styling.
Optionally, be configured to sort items, and display the column headers in a way that indicates which column is being sorted.

If the Table itself were to own the sorting behavior, the Table would need to be explicitly given the full set of items. But wait, how would you control what the table looks like then?

If the Table component were to own the sorting behavior, you'd have to pass it all your items

<Table items={myData} enableSort >
  {/* What do you map over to display table rows? */}
  {/* It's not 'myData' because that isn't sorted. */}
</Table>

You could try something like a renderRow prop, or use the "render as children" pattern.

Neither option feels right

// OPTION A: renderRow prop - This will to turn into prop sprawl 
// as we identify more render scenarios (or be very un-flexible)
<Table
  items={myData}
  enableSort
  renderRow={(item) => <tr><td>{item.name}</td/>...</tr>}
/>

// OPTION B: Render as children - this syntax just feels gross
<Table items={myData} enableSort>
  {({ sortedItems} ) => (
    {sortedItems.map((item) => (
      <tr>
        <td>{item.name}</td/>
        ...
      </tr>
    )}
  )}
</Table>

Besides the fact that it already smells, we'd still have to figure out how to render the Table Header.

How would the Table know which columns to use?
We could expose a renderHeader prop and let developers show whatever they want. But then we'd be forcing developers to handle the sorting UI (showing the correct Sort Icon) on their own too.
That feels like it defeats the purpose of the Table component!

We've already hit a wall and we've only discussed sorting. What if we also want to support paging? What about a textbox to filter table rows?

We don't want to force developers to implement those behaviors themselves.
But we also can't bake it into the component because we need to give them control over what it looks like.
Lastly, we want to provide "happy path" UI defaults to make the component really simple to use.

Compound Components w/ Hooks

My idea is to take the Compound Components Pattern and combine it with custom React Hook composition.

Take a look at this usage example, then scroll below to see a breakdown of the notable elements.

import React from "react";
import Table from "./table/table";
import users from "./data";


export default function SortingDemo() {
  // This is the interesting bit, the Component definition has
  // a custom hook attached to it.
  const { showingItems, sorting } = Table.useTable(users, {
    sortKey: "firstName",
    sortDir: "desc"
  });

  // The parent has access to behavior data
  console.log("You are sorting by: ", sorting.sortKey);

  return (
    <Table>
      {/* 
          Here, we take advantage the fact that the hook
          returns the behavior data, 'sorting', in the same
          shape needed for the Table.Header props.
      */}
      <Table.Header {...sorting}>
        <Table.Column id="firstName">First Name</Table.Column>
        <Table.Column id="lastName">Last Name</Table.Column>
        <Table.Column id="department">Department</Table.Column>
        <Table.Column id="jobTitle">Title</Table.Column>
      </Table.Header>

      <Table.Body>
        {/* Show the first 10 sorted items */}
        {showingItems.slice(0, 10).map((item) => (
          <Table.Row key={item.id}>
            <Table.Cell>{item.firstName}</Table.Cell>
            <Table.Cell>{item.lastName}</Table.Cell>
            <Table.Cell>{item.department}</Table.Cell>
            <Table.Cell>{item.jobTitle}</Table.Cell>
          </Table.Row>
        ))}
      </Table.Body>
    </Table>
  );
}

Things to note:

In addition to compound components like Table.Column and Table.Cell, the Table component also has a useTable hook attached to it.
The useTable hook returns a sorting object that:
- Provides the parent component access to the sorting behavior like the current sortKey.
- The sorting object is structured to overlap the prop signature of the Table.Header component so that it's really easy to use the built-in sorting UI if desired.
- <Table.Header {...sorting}> is all it takes to opt into the sorting UI.

The beauty of this pattern is it doesn't complicate the simple scenarios. We can use the Table for UI things without having to worry about any of the hook/behavior code.

A simple table w/ zero behavior

import React from "react";
import Table from "./table/table";
import users from "./data";

export default function SimpleDemo() {
  return (
    <Table>
      <Table.Header>
        <Table.Column>First Name</Table.Column>
        <Table.Column>Last Name</Table.Column>
        <Table.Column>Department</Table.Column>
        <Table.Column>Title</Table.Column>
      </Table.Header>

      <Table.Body>
        {users.slice(0, 5).map((item) => (
          <Table.Row key={item.id}>
            <Table.Cell width="120px">{item.firstName}</Table.Cell>
            <Table.Cell width="130px">{item.lastName}</Table.Cell>
            <Table.Cell width="170px">{item.department}</Table.Cell>
            <Table.Cell width="250px">{item.jobTitle}</Table.Cell>
          </Table.Row>
        ))}
      </Table.Body>
    </Table>
  );
}

This pattern can also scale to add more and more behavior without over complicating the usage.

We could add more behavior to our useTable hook

const { showingItems, sorting, paging, filtering, stats } = Table.useTable(
  users,
  {
    sortKey: "firstName",
    sortDir: "desc",
    filterKeys: ["firstName", "lastName", "department", "jobTitle"],
    pageSize: 10
  }
);

Because the behavior data comes from a hook we have it readily available to do whatever our application needs from a logic perspective, but we can also easily (and optionally) render it using the coupling between the built-in Table compound components and the useTable hook.


// Render the built-in paging controls
<Table.Paging {...paging} onChange={paging.goTo} />

// Render the built-in search box
<Table.Search
  value={filtering.filterText}
  onChange={filtering.setFilterText}
/>

// Render custom "stats" 
<div>
  Showing {stats.start} - {stats.end} of {stats.totalItems}
</div>

Isn't tight coupling bad?

You may have read "The sorting object is structured to overlap the prop signature of the Table.Header" and involuntarily shuddered at the tight coupling.

However, because hooks are so easy to compose, we can build the "core behaviors" totally decoupled, then compose them (in the useTable hook) in a way that couples them to the (Table) UI.

If you look at the implementation of useTable, you'll see it is mostly the composition of individual, decoupled behavior hooks, useFilteredItems, usePaging, and useSorting.

useTable.js is really just responsible for pulling in decoupled behavior hooks, and tweaking things to line up perfectly with the Table components.

import { useFilteredItemsByText } from "../hooks/useFilteredItems";
import { usePagedItems } from "../hooks/usePaging";
import { useSortedItems } from "../hooks/useSorting";

export function useTable(
  allItems,
  { filterKeys = [], sortKey, sortDir, pageSize }
) {
  pageSize = pageSize || allItems.length;
  const { filteredItems, ...filtering } = useFilteredItemsByText(
    allItems,
    filterKeys
  );
  const { sortedItems, ...sorting } = useSortedItems(filteredItems, {
    sortKey,
    sortDir
  });

  const [showingItems, paging] = usePagedItems(sortedItems, pageSize);

  const stats = {
    totalItems: allItems.length,
    start: (paging.currentPage - 1) * pageSize + 1,
    end: Math.min(paging.currentPage * pageSize, allItems.length)
  };

  return {
    showingItems,
    filtering,
    sorting,
    paging,
    stats
  };
}

In the end there is nothing really earth shattering here. We've already been building hooks like this, and we've already been building components like this. I'm just suggesting (for certain situations) to embrace the coupling and package them up together.

Thanks for making it this far. Let me know what you think in the comments. I haven't really seen anyone doing something like this yet so I am nervous I'm missing a tradeoff.

Here is the final codesandbox

React State Machine Hook

Andrew Petersen — Thu, 26 Nov 2020 07:30:22 +0000

This custom hook is meant to live somewhere in between the built-in useReducer and pulling in a 3rd party library like xstate.

let { state, status } = useStateMachine(
    stateChart, 
    initialState, 
    updaters,
    transitionEffects?
);

It's not quite useful/big enough to warrant an NPM package, so I created a code snippet and will document it here for the next time I reach for it.

1. Document the State and available Statuses

The State Machine will track 2 things,

status - the State Machine's state, called status to avoid confusing with React state.
state - The stateful data that should be tracked in addition to status. This is just like the state for useReducer.

export interface AuthState {
  error: string;
  currentUser: { 
    uid: string; 
    name: string; 
    email: string 
  };
}

const initialState: AuthState = {
  currentUser: null,
  error: ""
};

export type AuthStatus =
  | "UNKNOWN"
  | "ANONYMOUS"
  | "AUTHENTICATING"
  | "AUTHENTICATED"
  | "ERRORED";

2. Create the State Chart

For each status, what actions can be performed? If that action runs, to which status should it transition?

The names of the actions should match the names of the updaters in the next step.

const stateChart: StateChart<AuthStatus, typeof updaters> = {
  initial: "UNKNOWN",
  states: {
    UNKNOWN: {
      setCachedUser: "AUTHENTICATED",
      logout: "ANONYMOUS",
      handleError: "ERRORED"
    },
    ANONYMOUS: {
      loginStart: "AUTHENTICATING"
    },
    AUTHENTICATING: {
      loginSuccess: "AUTHENTICATED",
      handleError: "ERRORED"
    },
    AUTHENTICATED: {
      logout: "ANONYMOUS"
    },
    ERRORED: {
      loginStart: "AUTHENTICATING"
    }
  }
};

3. Implement the State Updaters

A state updater is a function that takes in the current state (a React state) and the triggered action, then returns the updated state. Just like a reducer.

(state, action) => updatedState

Under the covers, useStateMachine will bind the updaters to dispatch and return actions you can call like actions.handleError({ error }).
Some actions are triggered just to cause a State Machine status transition (like loginStart). In this case, the updater should return the state right back.

The names of the updaters should match the names of the actions in the State Chart.

const updaters = {
  loginSuccess: (state, { user }) => {
    cacheCurrentUser(user);
    return {
      error: "",
      currentUser: user
    };
  },
  setCachedUser: (state, { user }) => {
    return {
      error: "",
      currentUser: user
    };
  },
  logout: (state) => {
    cacheCurrentUser(null);
    return {
      error: "",
      currentUser: null
    };
  },
  handleError: (state, { error }) => {
    return {
      ...state,
      error: error.message
    };
  },
  loginStart: (state, { username, password }) => state
};

4. Use and Define Transition Effects

The last step is to use the hook.

You can also define effect functions to be run when the state machine transitions into a specified status. This is useful for doing async work.

The enter transition effect function is given the action that caused the transition as well as all the available actions.

In this example, when the user calls, loginStart, the status will transition to AUTHENTICATING, which will fire the transition effect to call api.login. Based on the result of login(), either the success or error action is triggered.

function useAuth() {
  let stateMachine = useStateMachine(stateChart, initialState, updaters, {
    AUTHENTICATING: {
      enter: async ({ action, actions }) => {
        try {
          let user = await api.login({
            username: action.username,
            password: action.password
          });
          actions.loginSuccess({ user });
        } catch (error) {
          actions.handleError({ error });
        }
      }
    },
    UNKNOWN: {
      enter: () => {
        let cachedUser = getCurrentUserFromCache();
        if (cachedUser && cachedUser.token) {
          stateMachine.actions.setCachedUser({ user: cachedUser });
        } else {
          stateMachine.actions.logout();
        }
      }
    }
  });

  // { actions, state, status }
  return stateMachine;
}

Here is the full login form example implemented in Code Sandbox.

New React Hooks Pattern? Return a Component

Andrew Petersen — Fri, 24 Apr 2020 05:28:20 +0000

I recently listened to a podcast where the creator of React Router, Michael Jackson mentioned a new pattern with hooks, returning a component.

At first, I couldn't grasp how this would differ from just calling a render function or another React component, and it seemed to go against the whole "Components for UI, hooks for behavior" mantra. But I think I've stumbled on a use case.

By the end of the article, I'll explain how I landed on this:

function ThingWithPanel() {

  let { Panel, panelProps, isOpen, openPanel, closePanel } = usePanel();

  return (
    <div>

      {!isOpen && <button onClick={openPanel}>Open Panel</button>}
      {isOpen && <button onClick={closePanel}>Close Panel</button>}

      <Panel {...panelProps}>
         <div>I am stuff in a panel</div>
      </Panel>

    </div>
  );
};

Instead of this

import { Panel } from "office-ui-fabric-react/lib/Panel";
import { IconButton } from "office-ui-fabric-react/lib/Button";
import styled from "styled-components";

function ThingWithPanel() {
  let [isOpen, setIsOpen] = useState(startOpen);
  let openPanel = useCallback(() => {
    setIsOpen(true);
  }, [setIsOpen]);

  let closePanel = useCallback(() => {
    setIsOpen(false);
  }, [setIsOpen]);

  // If dealing with IFrames in the Panel,
  // usually want to wire up a way for the Iframed page
  // to tell the Parent to close the panel
  useEffect(() => {
    let handler = (event) => {
      try {
        let msg = JSON.parse(event.data);
        if (msg.type === "CLOSE_PANEL") {
          closePanel();
        }
      } catch (err) {
        // Couldn't parse json
      }
    };
    window.addEventListener("message", handler, false);
    return () => {
      window.removeEventListener("message", handler);
    };
  });

  return (
    <div>
      {!isOpen && <button onClick={openPanel}>Open Panel</button>}
      {isOpen && <button onClick={closePanel}>Close Panel</button>}

      <Panel
        isOpen={isOpen}
        isLightDismiss={true}
        onDismiss={closePanel}
        {/* Override the default Panel Header */}
        onRenderNavigation={() => (
          <StyledClose>
            <IconButton iconProps={{ iconName: "ChromeClose" }} onClick={closePanel} />
          </StyledClose>
        )}
      >
        <div>I am stuff in a panel</div>
      </Panel>
    </div>
  );
}

const StyledClose = styled.div`
  position: absolute;
  top: 5px;
  right: 23px;
  z-index: 10;
  background: #ffffffbf;
  border-radius: 50%;
  opacity: 0.85;
  &:hover {
    opacity: 1;
  }
`;

Pain points working with Component Libraries

At work, I frequently leverage Microsoft's version of Material UI, Fluent UI. Overall, I enjoy using the library. However, the Panel component causes me a few pain points:

I always have to setup the useState to track whether the panel is open, then use that to create functions to open and close the Panel.
I have to remember the prop, isLightDismiss, that says "close this panel when the user clicks off the panel". It's off by default and I almost always turn it on.
The default Panel Header renders with a bunch reserved whitespace so the Panel Content has a weird looking top margin.
- So I override the header to absolute position it so my content shifts to the top of the panel
- Because I override the header, I am responsible for rendering my own Close button in the top right.
If the Panel is rendering an IFrame, I usually wire up a PostMessage listener so the IFramed page can tell the parent window to close the panel.

The longer code snippet above implements these details.

It's not THAT big of a deal, but it's annoying to think about all that boilerplate for every instance of a Panel. It's easy to screw up, and adds unnecessary friction.

BTW, I'm not knocking UI Fabric. Component Libraries have to optimize for flexibility and reuse, not for my application's specific preferences.

Hooks to the Rescue

In most cases I would encapsulate my preferences by baking them into a wrapper component. But the Panel is more complicated because isOpen,openPanel, and closePanel can't be baked in because the parent needs to use them to control when the Panel is open.

*Here baked a lot of stuff into MyPanel, but we still have to manage the isOpen state outside the MyPanel component.

import { MyPanel } from "./MyPanel";

function ThingWithPanel() {

  // Setup the isOpen boilerplate
  let [isOpen, setIsOpen] = useState(startOpen);

  let openPanel = useCallback(() => {
    setIsOpen(true);
  }, [setIsOpen]);

  let closePanel = useCallback(() => {
    setIsOpen(false);
  }, [setIsOpen]);

  return (
    <div>
      {!isOpen && <button onClick={openPanel}>Open Panel</button>}
      {isOpen && <button onClick={closePanel}>Close Panel</button>}

      {/* Use the custom MyPanel component */}
      <MyPanel isOpen={isOpen} onDismiss={closePanel}>
        <div>I am stuff in a panel</div>
      </MyPanel>
    </div>
  );
}

Refactoring, we could create a custom hook to handle the isOpen boilerplate.

import { MyPanel, usePanel } from "./MyPanel";

function ThingWithPanel() {
  // Use the custom hook to control the panel state
  let { isOpen, openPanel, closePanel } = usePanel();

  return (
    <div>
      {!isOpen && <button onClick={openPanel}>Open Panel</button>}
      {isOpen && <button onClick={closePanel}>Close Panel</button>}

      {/* Use the custom MyPanel component */}
      <MyPanel isOpen={isOpen} onDismiss={closePanel}>
        <div>I am stuff in a panel</div>
      </MyPanel>
    </div>
  );
}

This solution is close, but something still feels off.

What if the hook took care of providing all the Panel Props?

Then we can just spread those props on the Panel component and not force everyone to memorize the UI Fabric API.

What if the hook also returns the Panel component?

Then consumers don't need to worry about the import
We'd have the flexibility to choose to provide the default Fabric Panel or provide our own custom MyPanel component. All without affecting the hook's consumers.

function ThingWithPanel() {

  let { Panel, panelProps, isOpen, openPanel, closePanel } = usePanel();

  return (
    <div>

      {!isOpen && <button onClick={openPanel}>Open Panel</button>}
      {isOpen && <button onClick={closePanel}>Close Panel</button>}

      <Panel {...panelProps}>
         <div>I am stuff in a panel</div>
      </Panel>

    </div>
  );
};

That feels clean! All the boilerplate has been removed without sacrificing any flexibility.

One important thing to note. Though the hook is returning a Component, it is really just syntax sugar. The hook is NOT creating a new Component definition each time the hook function executes. This would cause the React reconciler to see everything as a new Component; state would be reset every time. Dan Abramov discusses the issue on this Reddit post.

Here is the full implementation of the usePanel hook

import React, { useState, useCallback, useEffect } from "react";
import styled from "styled-components";
import { IconButton } from "office-ui-fabric-react/lib/Button";
import { PanelType, Panel as FabricPanel, IPanelProps } from "office-ui-fabric-react/lib/Panel";
import IFramePanel from "./IFramePanel";

export type PanelSize = "small" | "medium" | "large" | number;

export interface PanelOptions {
  /** Defaults to false. Should the panel be open by default? */
  startOpen?: boolean;
  /** The size of the panel. "small", "medium", "large", or a Number */
  size?: PanelSize;
}
let defaults: PanelOptions = {
  startOpen: false,
  size: "medium",
};

export function usePanel(opts: PanelOptions = {}) {
  let { startOpen, size } = { ...defaults, ...opts };
  let [isOpen, setIsOpen] = useState(startOpen);
  let openPanel = useCallback(() => {
    setIsOpen(true);
  }, [setIsOpen]);

  let closePanel = useCallback(() => {
    setIsOpen(false);
  }, [setIsOpen]);

  useEffect(() => listenForPanelClose(closePanel));

  let panelProps = {
    isOpen,
    onDismiss: closePanel,
    isLightDismiss: true,
    type: getPanelType(size),
    customWidth: typeof size === "number" ? size + "px" : undefined,
    onRenderNavigation: () => (
      <StyledClose>
        <IconButton iconProps={{ iconName: "ChromeClose" }} onClick={closePanel} />
      </StyledClose>
    ),
  };

  return {
    isOpen,
    openPanel,
    closePanel,
    panelProps,
    Panel,
  } as UsePanelResult;
}

export interface PanelProps extends IPanelProps {
  url?: string;
}

export const Panel: React.FC<PanelProps> = function ({ url, ...panelProps }) {
  if (url) return <IFramePanel url={url} {...panelProps} />;

  return <FabricPanel {...panelProps} />;
};
export interface UsePanelResult {
  /** Whether the panel is currently open */
  isOpen: boolean;
  /** A function you can call to open the panel */
  openPanel: () => void;
  /** A function you can call to close the panel */
  closePanel: () => void;
  /** The props you should spread onto the Panel component */
  panelProps: IPanelProps;
  /** The hook returns the UI Fabric Panel component as a nicety so you don't have to mess with importing it */
  Panel?: any;
}

const getPanelType = (size) => {
  if (size === "small") {
    return PanelType.smallFixedFar;
  }
  if (size === "medium") {
    return PanelType.medium;
  }
  if (size === "large") {
    return PanelType.large;
  }
  if (typeof size !== "string") {
    return PanelType.custom;
  }
  return PanelType.medium;
};
const CLOSE_MSG_TYPE = "CLOSE_PANEL";

// The parent window should create a panel then wire up this function
// to listen for anyone inside the IFrame trying to close the panel;
export const listenForPanelClose = function (cb: () => void) {
  let handler = (event) => {
    try {
      let msg = JSON.parse(event.data);
      if (msg.type === CLOSE_MSG_TYPE) {
        cb();
      }
    } catch (err) {
      // Couldn't parse json
    }
  };
  window.addEventListener("message", handler, false);
  return () => {
    window.removeEventListener("message", handler);
  };
};

export const triggerPanelClose = function () {
  let msg = JSON.stringify({
    type: CLOSE_MSG_TYPE,
  });
  window.top.postMessage(msg, "*");
};

const StyledClose = styled.div`
  position: absolute;
  top: 5px;
  right: 23px;
  z-index: 10;
  background: #ffffffbf;
  border-radius: 50%;
  opacity: 0.85;
  &:hover {
    opacity: 1;
  }
`;

SharePoint Rest API Formatter

Andrew Petersen — Tue, 21 Apr 2020 04:55:45 +0000

Before stumbling across the article, Userscripts Are Fun And Are Still Very Much Relevant, I had never heard of Userscripts. They are pretty useful; kind of like a bare bones browser extension.

The first thing I created was a helper to format and syntax highlight the XML that comes back when navigating to a SharePoint REST endpoint in Chrome or Edge.

Userscript automatically kicks in on all REST API urls

Without it, it'd look like this

Previous Solutions/Attempts

I've installed Chrome Extensions to automatically format/syntax highlight XML, but they perform mediocre at best
I've experimented with Chrome Extensions to automatically set the request headers to application/json, but that inevitably causes problems when I forget to turn it off, and sometimes I prefer the ATOM/XML response because it shows you what child properties you can expand on.

Goals

Format and syntax highlight the XML response
Provide a toggle to switch between XML or JSON response

Install Steps

Install the ViolentMonkey Chrome Extension
- This is what manages all your Userscripts.
- It's a weird name, but it has worked great so far.
Add a new User Script from URL
- Open the ViolentMonkey extension Dashboard,
- Then click "New Script from Url" and paste in the following url.
- It's the raw url to this Gist, which is the result of my efforts. Definitely take a look at the code if you're interested.

https://gist.githubusercontent.com/DroopyTersen/7234e172ba004a5689910f05822a1b95/raw/a0a7e03c47daa55ef7a34ac433f6231fdb0e9bb5/REST%2520API%2520Formatter%2520Userscript

Cleaner Imports in SPFx Projects

Andrew Petersen — Thu, 26 Mar 2020 05:10:22 +0000

SharePoint Framework (SPFx) projects usually consist of multiple web parts, and a variety of shared components, services and utils. This leads to some gnarly imports.

Welcome to Dot City...

import ThemeColorPicker from "../../../ui-toolkit/components/ThemeColorPicker";
import { cachify } from "../../../utils/cache"

I find it very frustrating and disruptive to count folders every time I need a new import! Wouldn't it it be nice if you could just reference files relative to your /src folder?

With 5 minutes of setup, you can get clean imports like this

import ThemeColorPicker from "ui-toolkit/components/ColorPicker/ThemeColorPicker";
import { cachify } from "utils/cache"

SPFx projects are compiled in 2 steps.

TypeScript turns the /src/*.ts files into /lib/*.js
Webpack bundles /lib/*.ts into /dist/yourproject-bundle.js

With minor config changes to each tool, we can achieve the /src relative imports we desire.

TypeScript Setup

First, update the tsconfig.json file at the root of your SharePoint Framework project. Under compilerOptions, set "baseUrl":"src".

{
  ...
  "compilerOptions": {
    "baseUrl": "src",
    ...
   }
}

This is a quick change and immediately we can update our imports and see VS Code help us out with path completion.

Immediately after setting the baseUrl, sometimes VS Code will complain about the src relative imports. Restarting VS Code usually does the trick.

Webpack Setup (Gulp)

Because the imports don't start with a ./ anymore, Webpack will think they are node_modules. We need to update the Webpack config to setup some resolve aliases.

SPFx exposes a way to update the webpack.config inside of gulpfile.js (at the root of your project).

Paste this into your gulpfile.js somewhere before build.initialize(gulp)

build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    generatedConfiguration.resolve.alias = {
      // TODO: Setup your aliases here!!
      // -- START OF MY ALIASES (remove them if you copy paste this) --
      "ui-toolkit": path.resolve(__dirname, "./lib/ui-toolkit/"),
      "utils": path.resolve(__dirname, "./lib/utils/"),
      // -- END OF MY ALIASES --
    };
    return generatedConfiguration;
  },
});

In the example above, I created two aliases, ui-toolkit and utils. Both are folders directly under /src.

Gotchas

You have to create a separate alias for each folder under src that you want to directly reference.
You need to reference them from /lib, not /src.

That's it. No more Dot City!

BONUS: VS Code's "auto import" feature seems to work better with this setup too.

import Filmstrip from "ui-toolkit/components/Filmstrip";
import useAsyncData from "ui-toolkit/hooks/useAsyncData"
import { getTenant } from "utils/spUtils";

useDebouncedEffect Hook

Andrew Petersen — Tue, 24 Mar 2020 15:54:19 +0000

This hook is for when we want to track something that changes quickly (mouse moves, user typing, etc...), but wait to trigger the onChange until the updates stop streaming in. You'd typically do this when your onChange does something expensive, like a make network call.

In the following example, pretend onChange prop is a function that makes an API call to the server. Here's where we'll get by the end of the Post.

function SearchBox({ onChange, defaultValue = "" }) {
  // We store one value for the instant updates
  let [value, setValue] = useState(defaultValue);

  useDebouncedEffect(
    (debouncedValue) => {
      console.log("Firing onchange", debouncedValue);
      onChange(debouncedValue);
    },
    value,
    300
  );

  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
}

A simple first approach might be to leverage useEffect, but we'd be making a network call for every keystroke.

function SearchBox({ onChange, defaultValue = "" }) {
  // We store one value for the instant updates
  let [value, setValue] = useState(defaultValue);

  // Whenever the value changes, call the passed in 'onChange'
  useEffect(() => {
    console.log("Firing onchange", value);
    onChange(value);
  }, [value]);

  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
}

We want to create a way to only trigger the onChange once the value has stopped updating for a specified amount of time.

Lets create a custom hook, useDebouncedValue, that keeps track of a frequently changing value with state, but only updates the state once the value stops updating.

export function useDebouncedValue(value, delay) {
  // State and setters for debounced value
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    // Update state to the passed in value after the specified delay
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      // If our value changes (or the component unmounts), React will
      // run this cleanup function to cancel the state update.
      clearTimeout(handler);
    };
    // These are the dependencies, if the value or the delay amount
    // changes, then cancel any existing timeout and start waiting again
  }, [value, delay]);

  return debouncedValue;
}

Now we could use our new hook like so:

function SearchBox({ onChange, defaultValue = ""}) {
  // We store one value for the instant updates
  let [value, setValue] = useState(defaultValue);
  // We use our new hook to track a value that only changes
  // when the user stops typing
  let debouncedValue = useDebouncedValue(value, 300);

  // We perform an effect anytime the user stops typing
  useEffect(() => {
    console.log("Firing onchange", debouncedValue);
    onChange(debouncedValue);
  }, [debouncedValue]);

  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
}

That works. But what if we tried to get rid of some of the boilerplate with one more custom hook, useDebouncedEffect.

export function useDebouncedEffect(effectFn, value, delay = 250) {
  // Store the effect function as a ref so that we don't
  // trigger a re-render each time the function changes
  let effectRef = useRef(effectFn);
  // Leverage the hook we just created above 
  let debouncedValue = useDebouncedValue(value, delay);

  // Run an effect whenever the debounced value
  useEffect(() => {
    if (effectRef.current) {
      // Invoke the effect function, passing the debouncedValue
      return effectRef.current(debouncedValue);
    }
  }, [debouncedValue]);
}

The final solution feels very similar to the original useEffect strategy but we get the performance benefits of the debounce.

function SearchBox({ onChange, defaultValue = "" }) {
  // We store one value for the instant updates
  let [value, setValue] = useState(defaultValue);

  useDebouncedEffect(
    (debouncedValue) => {
      console.log("Firing onchange", debouncedValue);
      onChange(debouncedValue);
    },
    value,
    300
  );

  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
}

Build a Bare-Bones GraphQL Client w/ Fetch

Andrew Petersen — Sat, 20 Jul 2019 15:32:36 +0000

There are already plenty of great browser based GraphQL clients. Check out, Exploring GraphQL Clients, for a solid rundown of the existing options.

So why would you write your own GraphQL Client?

Maybe it's for a tiny thing and you don't want to deal with pulling in NPM packages and bundling code.
Or you're writing a Chrome Snippet
Maybe, like me, you just want to go through the motions to learn more about GraphQL.

The purpose of this post isn't to create a competing/better GraphQL client. The 10 minutes it takes to craft our own could never compete with the features and robustness of the existing libraries.

The Basics

At minimum, a client-side request to a GraphQL endpoint needs to be a POST, with a query property in the Request body. The GraphQL server will respond with JSON in the form of either { data } or { errors }.

GraphQL Request

HTTP POST
POST body contains a query property
query is a valid GraphQL string

GraphQL Response

JSON in the shape of { data, errors }
data, if success, will be an object that contains a property for each of the things you asked for in your GraphQL query.
errors, if there are any, will be an array of objects. Each error object should at least have a message property.

An example request

In this example we connect to a publicly available Pokemon GraphQL API and console.log the result of a query.

// Public Pokement API
const ENDPOINT = "https://graphql-pokemon.now.sh";
// Use a tool like GraphiQL to help you craft your query
const POKEMON_QUERY = `
  query TopFivePokemon {
    pokemons(first:5) {
      name
      image
    }
  }
`;

// Call fetch, first passing the GraphQL endpoint, then the Request Options
fetch(ENDPOINT, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  // The request body should be a JSON string
  body: JSON.stringify({ query: POKEMON_QUERY })
})
  // Handle a JSON response
  .then(res => res.json())
  .then(result => console.log(result));

In the above snippet we:

Use JavaScript string templates to make the GraphQL query readable
Tell the server we are sending JSON with the Content-Type header
Set our POST body to be the JSON string of our { query } object.
Expect the server to return JSON, and handle the response accordingly with res.json()

Console Output

{
  "data": {
    "pokemons": [
      {
        "name": "Bulbasaur",
        "image": "https://img.pokemondb.net/artwork/bulbasaur.jpg"
      },
      {
        "name": "Ivysaur",
        "image": "https://img.pokemondb.net/artwork/ivysaur.jpg"
      },
      {
        "name": "Venusaur",
        "image": "https://img.pokemondb.net/artwork/venusaur.jpg"
      },
      {
        "name": "Charmander",
        "image": "https://img.pokemondb.net/artwork/charmander.jpg"
      },
      {
        "name": "Charmeleon",
        "image": "https://img.pokemondb.net/artwork/charmeleon.jpg"
      }
    ]
  }
}

Basic Client Factory

The above snippet worked great, but let's enhance things slightly so that our GraphQL endpoint is configurable and we don't rely on some random ENDPOINT variable existing.

We want to create an instance of a GraphQL client that is tied to a specific endpoint.

The Factory Pattern is just a fancy way of saying, "make a function that creates instances of things". It's an alternative to new'ing up a class, createClient(endpoint) instead of new Client(endpoint)

Let's shoot for an API that looks like this:

// Create an instance of a GraphQL client by passing in your endpoint
let client = createClient("https://graphql-pokemon.now.sh");

// Make an actual GraphQL request by passing a GraphQL query 
// to the request method on the client
client.request(POKEMON_QUERY)
  .then(result => console.log(result));

To implement:

Take the fetch code from the first example and turn it into a function named request.
Wrap request with another function, createClient, to create a closure around our endpoint parameter.

function createClient(endpoint) {

  let request = function(query) {
    return fetch(endpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      // The request body should be a JSON string
      body: JSON.stringify({ query })
    }).then(res => res.json());
  };

  return { request };
};

Client Factory with Custom Headers

Now that our endpoint is configurable lets add a little more flexibility by allowing developers to pass in HTTP headers that should be included on all requests (common for an Authorization header).

We let our createClient function take in a second parameter for headers and default it to an empty object.
We spread the passed in headers onto the headers property of our Fetch options.

// Allow an optional second param for request headers
function createClient(endpoint, headers = {}) {

  let request = function(query) {
    return fetch(endpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        // spread the passed in headers
        ...headers
      },
      body: JSON.stringify({ query })
    }).then(res => res.json());
  };

  return { request };
}

GraphQL Variables

The last thing we want to support are variables to tokenize our GraphQL queries (and mutations). In the screenshot below you can see that the name is getting set via a variable.

This is actually pretty easy to support. All we need to do is add an additional property to our POST body named variables.

However, instead of only adding support for just variables, let's have request take in an optional second param, generically named queryOptions. Then we'll spread whatever queryOptions are given (in our case, variables) onto the POST body.

function createClient(endpoint, headers = {}) {

  // Take in an optional queryOptions object
  let request = function(query, queryOptions = {}) {
    return fetch(endpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        ...headers
      },
      // spread the passed in queryOptions onto the POST body
      body: JSON.stringify({ query, ...queryOptions })
    }).then(res => res.json());
  };

  return { request };
}

And that's it. Our final client factory can support configuring custom headers as well as GraphQL variables.

Final Usage example:

const POKEMON_BY_NAME_QUERY = `
query GetByName($name:String!) {
  pokemon(name:$name) {
    types 
    name
    image
    height {
      minimum
      maximum
    }
  }
}`;

let client = createClient("https://graphql-pokemon.now.sh", {
  Authorization: "Bearer ABC123"
});

async function getPokemonByName(name) {
  let {data,errors} = await client.request(POKEMON_BY_NAME_QUERY, { variables: { name } })
  if (errors) {
    console.log("Uh Oh!", errors.map(e => e.message));
  }
  return data.pokemon
}


getPokemonByName("Pikachu");

SPFx Developer: Working with MMS Values in SharePoint Search Results

Andrew Petersen — Tue, 09 Jul 2019 20:16:27 +0000

In this article I'll show how to use the Sharepoint Search Service to query by an MMS column. Then how to process the raw search result value in code in order to perform further logic on it (ex: group by tagged categories).

Managed Property Setup

Assumes...

You've already created a Managed Metadata Site Column
You've tagged some items with that Site Column
You've given the Search Service time to crawl that tagged content.

To query by our MMS column we need to setup the Search Managed Property in the SharePoint Admin Center.

https://YOURTENANT-admin.sharepoint.com/_layouts/15/searchadmin/ta_listmanagedproperties.aspx?level=tenant

Find and "Edit" the Managed Property that was automatically created when you setup your MMS Site Column. It should named like,owstaxIdCOLUMN_NAME.

Once you are on the Edit Screen for your Managed Property we need to:

Make it "Searchable", "Queryable" and "Retrievable"
Map the Crawled Properties
Setup an Alias

We typically map multiple crawled properties, one for just the term labels, and one for the full serialized term (GUID, label, termset etc...).

We also usually setup an alias that matches the Site Column's internal name. This makes the Search KQL query more readable.

Searching by an MMS Value

You can use the SharePoint Search Service REST api to query data. At Skyline, we use the SPScript library to help us make calls to SharePoint Rest endpoints.

If we had a managed property with an alias of AssetLocation, we can query for items with:

import SPScript from "spscript"

async function fetchByAssetLocation(location: string) {
  let ctx = SPScript.createContext();
  let queryText = "AssetLocation:" + location;
  let queryOptions: any = {
    selectProperties: ["AssetLocation", "Path", "Title"],
  };
  let searchResponse = await ctx.search.query(queryText, queryOptions);
  return searchResponse.items;
}

Parsing the Search Result MMS Value

Assuming...

The Managed Property was setup properly
The data tagged with the MMS value has been crawled
We've explicitly asked the Search Service to return our Managed Property via the selectproperties query option

We should expect to see our Search Result items having data for our MMS column in the following format.

Here is an item tagged with 2 categories, Leadership and Solving Smarter

Leadership

Solving Smarter

GP0|#0054b39a-0866-4e42-a1ba-ead38182a532

L0|#00054b39a-0866-4e42-a1ba-ead38182a532|Leadership

GTSet|#c69ac715-7977-4b11-8fdc-cf735f574607

GP0|#73bf5891-287a-498d-8e40-d8f7fafcf1e0

L0|#073bf5891-287a-498d-8e40-d8f7fafcf1e0|Solving Smarter

The data we need is all there but it is a little messy. It's just one big giant string. If we want to use tagged terms to perform any logic in code (ex: group items by their tag), we'll need to parse that raw string.

This is where regular expressions come in handy. I always get intimidated by Regex so I lean heavily on https://regex101.com.

Here is the thought process I used to build a regular expression that parses the raw search result MMS string.

Each line that starts with "L0" contains the Term Guid and the Term label. I want to just target those lines. Each "L0" line is in this format:

L0|#0<TERM_GUID>|<TERM_LABEL>

To build up the Regular expression...

First target the beginning of the line, LG|#0.

The | is a special character so we have to escape it with a backslash.
We add the /g flag so can grab all the matches instead of stopping once we find our first match.

let regex = /L0\|#0/g

Next grab everything up to the next '|' character.

[^\|] means a character that that ISN'T |
Adding a +, means if there are multiple characters in a row like the one previously described, grab them all.

let regex = /L0\|#0[^\|]+/g

To get the end of the line we expect a | and then a Term Label.

\|[^\n]+ means look for the pipe, followed by grabbing all characters that AREN'T a newline, \n

let regex = /L0\|#0[^\|]+\|[^\n]+/g

The last thing to do is add "groups" to our Regular Expression so that for each match we can quickly get the Term Guid and Term Label part of the match.

To add groups, we just wrap a section of the Regex with parenthesis

let regex = /L0\|#0([^\|]+)\|([^\n]+)/g

Now that we have a working Regular Expression, we can write a javscript function to execute our regular expression against the raw string value.

For each match, we want to create a new "Term" object in the shape of { id, label }.

function parseSearchResultMMSValue(value) {
  if (!value) return [];
  let regex = /L0\|#([^\|]+)\|([^\n]+)/g;
  let terms = [];
  let match;
  // repeatedly call 'exec' until we don't have anymore matches
  while ((match = regex.exec(value))) {
    // once we have a match, get at the group for the id and the label
    // index 0 is the full match, group1 is the guid, group2 is the label
    terms.push({
      id: match[1],
      label: match[2],
    });
  }
  return terms;
}

Reactify Vanilla JS Libraries with Hooks

Andrew Petersen — Tue, 02 Jul 2019 21:53:05 +0000

React Hooks make it really easy to wrap a vanilla javascript library with a React component so you can easily reuse throughout your app and stay in "React Mode".

In this walk through I'll be focusing on a single library, Shave.js, but the techniques and ideas should be applicable to any DOM updating javascript library.

Example Library: Shave.js

Open sourced by Dollar Shave Club, shave.js helps cut off multi-line text with an ellipses once you hit your specified height (this is a surprisingly complicated issue).

Shave.js cleanly figures out how many lines will fit given your styles and specified height.

Vanilla JS Usage

The first thing to do is figure out how to use the library without worrying about anything React'y.

Shave.js is nice and simple. Tell it which element to shave and give it a max height.

shave(".selector", maxHeight);

You can also pass a DOM element (instead of string selector). This will come in handy when in React land.

let elem = document.querySelector(".selector");
shave(elem, maxHeight);

The `Shave` React Component: Basic

Let's create a React component called Shave .

We'll let people put whatever content they want inside of Shave and have them pass in a maxHeight prop.

The usage would be something like this:

<Shave maxHeight={100}>
 Offal vice etsy heirloom bitters selvage prism. Blue bottle forage
 flannel bushwick jianbing kitsch pabst flexitarian mlkshk whatever you
 probably havent heard of them selvage crucifix. La croix typewriter
 blue bottle drinking vinegar yuccie, offal hella bicycle rights iPhone
 pabst edison bulb jianbing street art single-origin coffee cliche. YOLO
 twee venmo, post-ironic ugh affogato whatever tote bag blog artisan.
</Shave>

Component Boilerplate

We'll begin by creating a React function component. In React you can easily render whatever developers put inside your component by using the special children prop.

function Shave({ children, maxHeight }) {
    return (
      <div>{children}</div>
    )
}

Adding Behavior

At this point we have a component that takes in content, and renders it. Not super useful yet. What we really want to do is update the rendered div by calling shave on it (passing our maxHeight prop value).

Rephrasing, we want to force an effect on the div that we rendered.

The React hooks we'll need are:

useRef to get a reference to our div
useEffect to affect the div after we render it.

Lets start with the easy step, wiring up a reference to our DOM element container (the div).

Create a variable, elemRef, using the useRef hook
Set elemRef as the ref prop on the container div

function Shave({ children, maxHeight }) {
  // keep track of the DOM element to shave
  let elemRef = useRef();

  // apply our elemRef to the container div
  return <div ref={elemRef}>{children}</div>;
}

The next step is a little more... weird.

For myself, the hardest part of learning React Hooks has been useEffect and switching from a "lifecycle" mindset to a "keep the effect in sync" mindset.

It'd be tempting to say, "When our component first mounts, we want to run the shave function". But that's the old "lifecycle" way of thinking and doesn't scale with added complexity.

Instead let's say, "Our shave should always respect the passed in maxHeight, so anytime we have a new value for maxHeight, we want to (re)run our 'shave' effect".

On initial render, we go from nothing to something, so our effect will run (effectively componentDidMount)
If the maxHeight prop changes, our effect will run again (effectively componentDidUpdate)

useEffect is a function that takes in 2 arguments

A function - the actual code of the effect
An array - Anytime an item in the array changes, the effect will re-run.
- As a rule of thumb, anything your effect function code references should be specified in this array (some exceptions being globals and refs).

The "shave" effect

// Run a shave every time maxHeight changes
useEffect(() => {
  shave(elemRef.current, maxHeight);
}, [maxHeight]);

With the shave effect calling shave on our div ref, we have a working component!

The basic Shave component

function Shave({ children, maxHeight }) {
  // keep track of the DOM element to shave
  let elemRef = useRef();

  // Run an effect every time maxHeight changes
  useEffect(() => {
    shave(elemRef.current, maxHeight);
  }, [maxHeight]);

  // apply our elemRef to the container div
  return <div ref={elemRef}>{children}</div>;
}

You can play with a demo of the working basic Shave component in this CodeSandbox.

The `Shave` React Component: Advanced

The previous Shave component does it's job. We specify a max height and our component gets cutoff. But let's imagine after using it in a few different spots in our app, 2 new requirements emerge.

The tech lead mentions that it should probably allow developers to be more semantic. Instead of always rendering a div , the component should optionally allow the developers to specify a more semantic dom element (like article).
You are using the Shave component for the details section of a card'ish component and you need to toggle the "shave" on and off when the user clicks a "Read more" button.

Overriding the DOM element

We'll add an "element" prop to the Shave component (with a default value of "div"). Then, if developers want to specify a different html element they can with this syntax:

<Shave maxHeight={150} element="article">
  Multiline text content...
</Shave>

To update the Shave component:

Take in an additional destructured prop named element and default it to "div"
Create a variable name Element and use that as the container element in the returned JSX

function Shave({ children, maxHeight, element = "div" }) {
  // keep track of the DOM element to shave
  let elemRef = useRef();

  // Set our container element to be whatever was passed in (or defaulted to div)
  let Element = element;

  // Run an effect every time maxHeight changes
  useEffect(() => {
    shave(elemRef.current, maxHeight);
  }, [maxHeight]);

  // apply our elemRef to the container element
  return <Element ref={elemRef}>{children}</Element>;
}

What's slick about this solution is it actually supports both native HTML elements (as a string value) or you can pass a reference to a custom React component.

// Renders the default, a DIV
<Shave maxHeight={150}>
  Multiline text content...
</Shave>

// Renders an ARTICLE
<Shave maxHeight={150} element="article">
  Multiline text content...
</Shave>

// Renders a custom BodyText react component
<Shave maxHeight={150} element={BodyText}>
  Multiline text content...
</Shave>

Allow "shave" toggling

To support toggling in the Shave component:

Add an enabled prop, defaulted to true.
Update shave effect code to only shave if enabled.
Update the shave effect references array to include enabled so it will also re-run if enabled changes.
Add enabled as the key to our container element so that if a enabled changes, React will render a completely new DOM node, causing our "shave" effect will run again. This is the trick to "unshaving".

function Shave({ children, maxHeight, element = "div", enabled = true }) {
  // keep track of the DOM element to shave
  let elemRef = useRef();
  // Allow passing in which dom element to use
  let Element = element;

  // The effect will run anytime maxHeight or enabled changes
  useEffect(() => {
    // Only shave if we are supposed to
    if (enabled) {
      shave(elemRef.current, maxHeight);
    }
  }, [maxHeight, enabled]);

  // By using enabled as our 'key', we force react to create a
  // completely new DOM node if enabled changes.
  return (
    <Element key={enabled} ref={elemRef}>
      {children}
    </Element>
  );
}

Lastly we need to update the parent component to keep track of whether it should be shaved or not. We'll use the useState hook for this and wire up a button to toggle the value.

function ParentComponent() {
  // Keep track of whether to shave or not
  let [isShaved, setIsShaved] = useState(true);

  return (
    <div>
      <h1>I have shaved stuff below</h1>
      <Shave maxHeight={70} element="p" enabled={isShaved}>
        Mutliline content...
      </Shave>

      <button type="button" onClick={() => setIsShaved(!isShaved)}>
        Toggle Shave
      </button>
    </div>
  );
}

You can play with a demo of the working enhanced Shave component in this CodeSandbox.

Finally, if you are still here and interested in taking this further, here is another iteration of the Shave component that re-runs the shave every time the window resizes. It demonstrates how to properly clean up an effect by removing the resize event listener at the appropriate time.

1000 bonus points to anyone that comments with a link to a forked CodeSandbox that includes debouncing the resize event!