Small Dog Energy

Keyboard Shortcuts for the Rest of the World

2024-03-06T23:50:09.925Z

If you’re a native English speaker, you probably don’t think too much about the special role that the English language plays in computer infrastructure. Programming languages use English keywords, domain names use Latin letters, terminal command names are based on English words...

If you don’t have a way to type in Latin characters, you’ll have a hard time using a computer at all. At the same time, there are many languages out there with alphabets that aren’t based on Latin. How the “rest of the world” deals with this is often a blind spot for developers used to Latin scripts. And sometimes this leads to a worse user experience.

Mostly, I want this article to cover a specific problem that comes up a lot when handling keyboard shortcuts in web applications: handling non-QWERTY layouts. So I’m going to put a snippet with a proper solution right here:

const actions = {
  "alt + shift + e": (event) => {},
  // any other keyboard shortcuts...
};

window.addEventListener("keydown", (event) => {
  const modifiers = ["meta", "ctrl", "alt", "shift"].filter(
    (key) => event[`${key}Key`]
  );

  let key = event.key.toLowerCase();

  if (
    /^\p{Ll}$/u.test(key) &&
    !/^[a-z]$/.test(key) &&
    /^Key[A-Z]$/.test(event.code)
  ) {
    key = event.code.at(3).toLowerCase();
  }

  const hotkey = [...modifiers, key].join(" + ");
  const action = actions[hotkey];

  if (action) {
    event.preventDefault();
    action(event);
  }
});

Now that that’s out of the way, if you want to dive a little bit deeper, let’s start with the basics.

Disclaimer. Although I use two (and sometimes three) languages in my daily life, they all use simple phonetic LTR scripts, don’t use diacritics, don’t require input method editors — so I probably have my own blind spots!

Localized Keyboards

Your keyboard probably has keys with letters and symbols printed on them (oh yes, we’re starting with the very basics). When you press a key, the keyboard sends a numeric code that corresponds to the key you pressed — it’s called a scan code. The scan codes are assigned to each key by the keyboard hardware itself.

Scan codes on a typical keyboard.
Here and throughout the article keyboard layout diagrams are provided by the brilliant kbdlayout.info.

You’ll find that the position of the control keys like Ctrl, Alt, and Enter doesn’t vary much from country to country, but other keys may have different letters printed on them. In the US, the first six letters on the keyboard spell QWERTY, but in France they sometimes spell AZERTY, or in Germany QWERTZ.

Keyboard layouts come in all shapes and colors: AZERTY, QWERTZ...

The Russian alphabet is completely different, with the first six letters spelling ЙЦУКЕН:

However, the physical keyboard doesn’t care about the symbols printed on its keycaps. Pressing Q on a US QWERTY keyboard, A on a French AZERTY keyboard, or Й on a Russian ЙЦУКЕН keyboard sends out the same scan code. It’s up to the operating system to interpret it correctly.

Keyboard Layouts

That’s why operating systems support different keyboard layouts — mappings between the scan codes and the actual keys.

So if you have a QWERTZ keyboard, you can tell your operating system that you want to use the QWERTZ layout, and then there will be no mismatch between the keys you press on the keyboard and the characters you see on the screen.

Things get a little trickier if your alphabet is not Latin-based. If you want to be able to type both your local non-Latin characters and regular Latin, you’ll have to use two keyboard layouts.

For the most of my life, my keyboard looked like this:

Notice how it has two sets of characters printed on each key. One set is the regular QWERTY layout, and the second one is the Russian ЙЦУКЕН layout. I’ve never seen a dual-layout keyboard where one of the layouts was not QWERTY.

When you add two keyboard layouts in your operating system settings, an additional icon appears that shows which layout is currently active. You can click it (or better yet, use a special keyboard shortcut, like Win + Space) to switch layouts.

Layout switcher on Windows

The important things to remember are:

Each key has at least two codes: a software-level code that depends on the current layout, and a hardware-level code that does not.
Even for Latin-based scripts, the default keyboard layout is not always QWERTY.
For the rest of the world, users usually have a dual layout setup, with QWERTY as the second layout.

Keyboard Shortcuts

Keyboard shortcuts are yet another thing deeply rooted in the English language. All the standard shortcuts, such as copy (Ctrl + C), paste (Ctrl + V), and undo (Ctrl + Z), were designed with the US QWERTY keyboard in mind.

Because shortcuts are embedded in our physical memory, we should be very careful about changing them. For this reason, keyboard shortcuts should not be a subject to internationalization. Even if I change the UI language of my operating system to Russian, all shortcuts will still use Latin characters:

Even though the rest of the UI is in Russian, keyboard shortcuts still refer to the Latin letters.

And since almost every keyboard has Latin characters (whether it’s just QWERTY, or QWERTY alongside some non-Latin layout), even if I type in Russian using the ЙЦУКЕН layout, I should still be able to look down at my keyboard, find the key with the letter Z printed on it, and press Ctrl + Z (which is actually Ctrl + Я in ЙЦУКЕН) to undo. I shouldn’t have to remember my current layout in order to invoke a shortcut.

This should still work as undo, no matter what the current layout is.

But that doesn’t mean we should rely solely on layout-independent codes (like scan codes) for keyboard shortcuts!

If I’m using a non-QWERTY Latin layout, it would be extremely confusing to me if the undo shortcut wasn’t Ctrl + Z, even though Z might be in an “unusual” place on my keyboard. Pressing Ctrl + Z with the Z in the top row of the AZERTY keyboard should also work as undo.

So there are really two cases:

Either we are using a Latin keyboard layout (not necessarily QWERTY): then we should rely on layout-dependent code to figure out exactly which key was pressed;
Or we are using a non-Latin layout: then it makes sense to assume that QWERTY is the secondary layout, and we should rely on layout-independent code to figure out which key it would have been in QWERTY.

Browser Keyboard Events

This sounds complicated, but the actual implementation is quite simple.

For keyboard events, the browser provides two event properties:

event.code is layout-independent. It is not a scan code per se, but rather a normalized name based on the scan code of the key: "ControlLeft", "ShiftRight", "Numpad0", and so on.

The convenient, if slightly confusing, thing is that for letter keys, event.code has a name derived from the QWERTY layout: "KeyQ", "KeyW", and so on. And since this code is layout-independent, pressing the Й key on the ЙЦУКЕН keyboard still results in event.code equal to "KeyQ".

event.key is layout-dependent. If the key pressed is a printable character, event.key is the character that would normally have been printed by pressing that key. Otherwise, it contains one of the predefined values, such as "Control" or "Shift".

Implementation

And now we are ready to revisit the implementation from the beginning of this article:

const actions = {
  "alt + shift + e": (event) => {},
  // any other keyboard shortcuts...
};

window.addEventListener("keydown", (event) => {
  const modifiers = ["meta", "ctrl", "alt", "shift"].filter(
    (key) => event[`${key}Key`]
  );

  let key = event.key.toLowerCase();

  if (
    /^\p{Ll}$/u.test(key) &&
    !/^[a-z]$/.test(key) &&
    /^Key[A-Z]$/.test(event.code)
  ) {
    key = event.code.at(3).toLowerCase();
  }

  const hotkey = [...modifiers, key].join(" + ");
  const action = actions[hotkey];

  if (action) {
    event.preventDefault();
    action(event);
  }
});

First, the event handler looks at the layout-dependent event.key. If it is a Latin letter, or any other non-letter symbol, we use it as is. This covers the case of a user with a Latin layout, and since we rely on layout-dependent codes, non-QWERTY layouts are covered as well.

let key = event.key.toLowerCase();

However, if it is a non-Latin character (\p{Ll} but not [a-z]), the event handler looks at the layout-independent event.code. There’s a good chance that in this case event.code is Key*, where * is a Latin letter that occupies the same key in the QWERTY layout (e.g. KeyQ). After all, non-Latin letters usually occupy the same keys as Latin letters do in QWERTY.

In this case, all we have to do is to trim the Key prefix to get the Latin letter. This is a very simple (but slightly hacky) way to map non-Latin letters to the letters of the QWERTY layout.

if (
  /^\p{Ll}$/u.test(key) &&
  !/^[a-z]$/.test(key) &&
  /^Key[A-Z]$/.test(event.code)
) {
  key = event.code.at(3).toLowerCase();
}

(I first came across this method in the KeyUX library. Its clever and compact implementation inspired this whole article.)

Of course, this implementation is not perfect. For example, you wouldn’t be able to invoke the Ctrl + ] shortcut in the ЙЦУКЕН layout. The event.key value is a non-Latin letter ъ, but the event.code is BracketRight and not Key*.

The key is non-Latin letter ъ, but the code doesn’t refer to a Latin letter.

This can be solved with a more robust mapping between codes and symbols of the QWERTY layout, but I would just avoid using punctuation symbols in shortcuts altogether.

There’s a good reason for this. Lesser-used punctuation symbols, like square and curly brackets, ampersands, backslashes, and so on, are omitted from many keyboard layouts to make room for larger alphabets. This means keyboard shortcuts like Ctrl + ] can confuse your users because they don’t know offhand where to find symbols like ] on their keyboards.

More common punctuation, like commas, can be found in most keyboard layouts, but they are not always in the same place as in QWERTY (for example, in ЙЦУКЕН, you should press Shift + . to enter a comma). So shortcuts like Ctrl + , are ambiguous, because it’s not immediately clear whether a user should be looking for a comma in QWERTY or in their local layout.

Unless you’re building professional software with lots of keyboard actions, it’s better to just stick to letters for your shortcuts.

Designing Suspenseful Hooks

2024-02-07T20:01:15.885Z

React Suspense is not just about data fetching and loaders. But, it’s also mostly about data fetching and loaders, and it’s a really good API for that. So it makes sense that data fetching libraries, like @tanstack/react-query or swr, provide “suspenseful” versions of their hooks.

Except that the way their suspenseful hooks are implemented (dare I say it) kinda goes against the idea of Suspense.

Consider the following component, which makes two requests with react-query v5:

// UserProfile.jsx
function UserProfile({ userId }) {
  const { data: user, isPending: isUserPending } = useQuery({
    queryKey: ["user", userId],
    queryFn: () => fetchUser(userId),
  });

  const { data: friends, isPending: isFriendsPending } = useQuery({
    queryKey: ["user", userId, "friends"],
    queryFn: () => fetchFriends(userId),
  });

  if (isUserPending || isFriendsPending) {
    return <p>Loading...</p>;
  }

  return (
    <>
      <h2>{user.name}</h2>
      <p>Friends: {friends.length}</p>
    </>
  );
}

// index.jsx
root.render(
  <>
    <h1>User Profile</h1>
    <UserProfile userId="some-id" />
  </>
);

In a perfect world, there’s a single endpoint that returns all the data we need for our UserProfile component, including both user data and the amount of friends the user has. But we can’t always dictate how an API works, so it’s fairly common for a single component to make multiple requests.

Currently our UserProfile component handles both fetching the data and the loading state. The cool thing about Suspense is that it allows us to write components as if the data always exists, and not have to deal with the loading state at the component level. Let’s try using a suspenseful version of the useQuery hook, useSuspenseQuery:

// UserProfile.jsx
function UserProfile({ userId }) {
  const user = useSuspenseQuery({
    queryKey: ["user", userId],
    queryFn: () => fetchUser(userId),
  });

  const friends = useSuspenseQuery({
    queryKey: ["user", userId, "friends"],
    queryFn: () => fetchFriends(userId),
  });

  return (
    <>
      <h1>{user.name}</h1>
      <p>Friends: {friends.length}</p>
    </>
  );
}

// index.jsx
root.render(
  <>
    <h1>User Profile</h1>
    <Suspense fallback={<p>Loading...</p>}>
      <UserProfile userId="some-id" />
    </Suspense>
  </>
);

This seems great at the first glance, but there’s a problem. Previously, the UserProfile component initiated two parallel requests:

Now those same two requests are serial. We’ve introduced a waterfall:

And this makes sense. The useSuspenseQuery hook will suspend rendering if the data is not ready yet. Suspending happens by throwing a promise, so once the first query suspends rendering, the second query doesn’t even have a chance to run until rendering is unsuspended.

How does the component get suspended?

Although it’s not currently documented, this is basically how Suspense works: throwing a Promise object from the component during render causes React to scrap the entire component subtree up to the nearest Suspense boundary (similar to how throwing an error from render is handled by the nearest error boundary).

React will then render a fallback and continue working on other subtrees. When the thrown promise resolves, React renders the suspended subtree again. In the case of react-query, the fact that the promise is resolved means that the data is cached, so this time the hook doesn’t throw and instead returns the data from the cache.

The solution suggested by react-query is to use the useSuspenseQueries hook. Instead of using useSuspenseQuery twice, you write:

// UserProfile.jsx
const [user, friends] = useSuspenseQueries({
  queries: [
    {
      queryKey: ["user", userId],
      queryFn: () => fetchUser(userId),
    },
    {
      queryKey: ["user", userId, "friends"],
      queryFn: () => fetchFriends(userId),
    },
  ],
});

This prevents the waterfall from happening, but in every other way it is a downgrade. It doesn’t look as nice, but more importantly, it’s less composable. We used to be able to extract our queries into reusable custom hooks:

// api.js
export function useUser(userId) {
  return useSuspenseQuery({
    queryKey: ["user", userId],
    queryFn: () => fetchUser(userId),
  });
}

export function useUserFriends(userId) {
  return useSuspenseQuery({
    queryKey: ["user", userId, "friends"],
    queryFn: () => fetchFriends(userId),
  });
}

The developer importing these hooks didn’t have to worry about react-query at all, and could compose them however they wanted. Now, our best option is to provide reusable query configs and to ask the developer to use react-query hooks directly, which is not nearly as nice.

∗ ∗ ∗

The root cause of our problems is that the useSuspenseQuery hook is suspending too early. We haven’t even had a chance to use the data in any meaningful way, but our component is already suspended!

Now imagine that instead of throwing and suspending, the hook we use to fetch the data returns a promise. We then use a special helper function (let’s call it use) that either returns the value of the promise synchronously, or throws the promise and suspends rendering if the promise has yet to be fulfilled. (You could say that the use function unpacks a value inside the promise, and throws the promise if it cannot be unpacked yet.)

Then our code might look something like this:

function use(promise) {
  /* We'll implement it later */
}

// UserProfile.jsx
function UserProfile({ userId }) {
  const user = useUser();
  const friends = useFriends();

  return (
    <>
      {/* unpack 👇 user before accessing */}
      <h1>{use(user).name}</h1>
      {/* unpack freinds 👇 before accessing */}
      <p>Friends: {use(friends).length}</p>
    </>
  );
}

// index.jsx
root.render(
  <>
    <h1>User Profile</h1>
    <Suspense fallback={<p>Loading...</p>}>
      <UserProfile userId="some-id" />
    </Suspense>
  </>
);

Let’s take a line-by-line look at how React renders this component.

First, two requests are made in parallel:

const user = useUser();
const friends = useFriends();

The hooks don’t suspend, and they don’t actually return the data: instead, they initiate requests, and return promises associated with those requests.

Then, we try to unpack the first promise:

<h1>{use(user).name}</h1>

If the user data isn’t already cached (which it probably isn’t), the call to use(user) will throw a promise and suspend the component.

Once this promise is fulfilled, React will try to render UserProfile again. This time, no new requests will be initiated: the user data is already cached by our library, so there’s no need for a new request; the friends data may also already be cached at this point, but if it is not, the request should still be deduplicated based on the query key.

During this second render, use(user) doesn’t throw and instead returns the cached data. If the friends data is also ready, then use(friends) won’t throw either, and we’re done. If not, use(friends) will throw a promise — and we’ll go through the whole cycle again.

The hypothetical use function is not that difficult to implement in practice:

function use(promise) {
  if (promise.status === "fulfilled") {
    return promise.value;
  }

  if (promise.status === "rejected") {
    throw promise.reason;
  }

  if (promise.status === "pending") {
    throw promise;
  }

  promise.status = "pending";
  promise.then(
    (value) => {
      promise.status = "fulfilled";
      promise.value = value;
    },
    (reason) => {
      promise.status = "rejected";
      promise.reason = reason;
    }
  );

  throw promise;
}

An important thing to note here is that we mutate the promise object to “smuggle” the value it was resolved with — or the error it was rejected with — onto the promise itself. That way, the next time use is called with the same promise, we can return the value synchronously. This is important because the implementation of use can’t be async, otherwise we won’t be able to use it during rendering.

Another, perhaps cleaner way to achieve the same thing is to have a global WeakMap that maps promises to their values:

const promiseResults = new WeakMap();

function use(promise) {
  const result = promiseResults.get(promise);

  if (result) {
    if (result.status === "fulfilled") {
      return result.value;
    }

    if (result.status === "rejected") {
      throw result.reason;
    }

    throw promise;
  }

  promiseResults.set(promise, { status: "pending" });
  promise.then(
    (value) => {
      promiseResults.set(promise, { status: "fulfilled", value });
    },
    (reason) => {
      promiseResults.set(promise, { status: "rejected", reason });
    }
  );

  throw promise;
}

(Without smuggling values onto the promise object, this implementation feels less hacky to me.)

Whichever implementation we choose, you may have noticed a potential pitfall. In order for the use function to work properly, we must pass the same instance of the promise for each fetched value. This means that the data fetching library must be very careful not to accidentally create new promises on subsequent renders.

Clearly, this implementation will not work:

// This will not work!
function useQuery({ queryKey, queryFn }) {
  return queryFn();
}

It creates a new promise on each render, so the use function will always throw. Instead, we need to cache our promises:

const cache = new Map();

function useQuery({ queryKey, queryFn }) {
  const key = queryKey.join(".");
  const entry = cache.get(key);

  if (!entry) {
    entry = queryFn();
    cache.set(key, entry);
  }

  return entry;
}

We must also be careful to avoid calling an async function on every render:

async function fetchOrGetCached({ queryKey, queryFn }) {
  /* ... */
}

function useQuery(options) {
  return fetchOrGetCached(options);
}

The caveat here is that fetchOrGetCached creates a new promise with each call, even if it is resolved immediately. So, again, the use function will always get a brand new promise and throw.

Why even make useQuery a hook at this point?

Good question! Our implementation of useQuery doesn’t call any React hooks, so it doesn’t need to be a hook itself. In real life, however, it will probably create a subscription (e.g. with useSyncExternalStore) to update the component when the stale data is refetched, or when the cache is invalidated.

Still, it’s a good idea to also provide a non-hook version of useQuery, so that requests can be made not only by React components, but also by regular JavaScript code.

With a little care around our promises, we get the desired experience: requests run in parallel, we only suspend when the data is actually read, and developers can compose as many data-fetching hooks in their components as they like.

It even unlocks new patterns, such as passing promises as props and suspending further down the tree:

// UserProfile.jsx
function UserProfile({ userId }) {
  const user = useQuery({
    queryKey: ["user", userId],
    queryFn: () => fetchUser(userId),
  });

  const friends = useQuery({
    queryKey: ["user", userId, "friends"],
    queryFn: () => fetchFriends(userId),
  });

  return (
    <>
      <h1>{use(user).name}</h1>
      <Suspense fallback={<p>Loading friends...</p>}>
        <FriendsList friends={friends} />
      </Suspense>
    </>
  );
}

// FriendsList.jsx
function FriendsList({ friends }) {
  return use(friends).map((friend) => {
    /* ... */
  });
}

// index.jsx
root.render(
  <>
    <h1>User Profile</h1>
    <Suspense fallback={<p>Loading profile...</p>}>
      <UserProfile userId="some-id" />
    </Suspense>
  </>
);

Because UserProfile doesn’t try to unpack the friends data, it will never suspend on it. Instead, it’s the FriendsList component that will suspend if the friends data is not ready. If the friends data takes longer to load than the user data, we’ll see the user profile partially loaded with the friends list suspended and the “Loading friends...” loader visible.

This pattern comes in handy when we want to start fetching data as soon as possible to avoid waterfalls, and to gradually reveal parts of the UI as the data trickles in.

∗ ∗ ∗

So! If there’s a single takeaway from this lengthy article, it’s this one:

Your library hooks should not suspend. Just return a promise, and let the developer decide when to suspend.

And the best news: React 19 will include an out-of-the-box implementation of the use hook! Until then, you can ship one of the implementations from this article along with your library, and later provide a migration guide for React 19 users. Or, why not publish a polyfill for the use hook right now? It’s a useful pattern that can benefit React 18 users as well.

As an aside, it’s no wonder that developers are confused about how best to use Suspense in their libraries, since there’s no real guidance from the React team. It’s been two years since Suspense was released in React 18, and there’s still no documentation for library authors.

Hopefully, with React 19, we’ll get proper documentation, leading to wider (and more idiomatic) adoption of Suspense in both libraries and applications.

The Right Idea

2023-10-28T15:02:26.662Z

Not a week goes by on Ex-Twitter without hype for a new frontend library. Yet every now and then a project comes along that feels like The Right Idea.

The Right Idea is more of a vibe than anything objective. The Right Idea project is not always the best tool for the job (although some of them are). But I believe in the approach these projects have taken, and I think others could benefit from taking inspiration in their direction.

React

React’s progress is slow, sometimes painfully so. And yet, each new feature introduced fits so neatly into place that it almost feels like an academic project, a “general UI runtime”.

JSX, Hooks, Suspense, Server Components are all good, clear, and inspired ideas. They also have a tendency to reveal a deeper, more general idea behind them over time.

Hooks are not just a way to achieve feature parity between functional and class components. They are a novel approach to sharing logic between components. They are also algebraic effects that abstract away non-pure parts of a render function, allowing for a much simpler mental model of rendering.

Suspense, it turns out, is not just about loaders. It’s a way to fork your component tree and render new state in the background. It’s also a way to postpone rendering part of your page on the server and stream it in later.

I can’t wait to see what kind of impact Server Components are going to have in the future!

React Spectrum

Spectrum is a component library built in layers: there’s presentation and there’s behavior.

React Aria implements behavior for different types of components and user interactions. It provides a set of hooks that make minimal assumptions about what the final component will look like. It just exports hooks and doesn’t provide any actual components.

React Aria is pretty low-level, so there are also React Aria Components, which provide an unstyled implementation of components based on React Aria hooks.

This feels like The Right Idea of extensibility and reusability in a component library.

shadcn/ui

Has the right idea about how component libraries should be distributed. Instead of importing a component and then overriding its style with themes or whatever, just copy and paste the whole component and edit the Tailwind classes directly.

Too bad it’s based on Radix UI and not React Aria Components :)

Tailwind

For a long time I thought CSS Modules were the way to go. To me, Tailwind looked like unreadable CSS with extra steps.

Now I think that the whole idea of separating styles from semantic markup, which started with CSS 1.0 in 1996, was wrong to begin with. There is no “semantic” markup. It’s all just content, and styles are content too.

Tailwind fixes this decades-old mistake by putting styles and markup back together.

Stop Using String Field Names in Your Forms (and Use Locators Instead)

2023-10-25T20:02:43.782Z

You can also read this article in Russian.

As Leo Tolstoy said, all React form libraries are alike; each one makes me unhappy in its own way. Or was it something to do with families?

Anyway, here’s a typical form made with Formik:

<Formik
  initialValues={{ email: "" }}
  onSubmit={(values) => {
    /* ... */
  }}
>
  <Form>
    <Field name="email" as={EmailInput} />
  </Form>
</Formik>

It’s trivially easy to misspell a field name. In this case, it would be reasonable to expect a type error during compilation, or at least a runtime error:

      // typo! 👇
<Field name="notmail" as={EmailInput} />

Unfortunately, Formik does nothing to help us find the typo. What we get instead are unexpected form values in the onSubmit callback.

Another source of unexpected behavior is incompatible components. Let us say we’re using a custom component for our email input that looks something like this:

function EmailInput(props: {
  value: string;
  onChange: (value: string) => void;
         // that's 👆 not compatible with Formik!
}) {
  /* ... */
}

It’s difficult to spot, but the signature for the onChange callback of this component is incompatible with Formik. Again, we won’t get compilation or runtime errors. Instead, the form just won’t work.

The reason that Formik cannot catch these types of errors is that the Field component doesn’t know anything about our form schema. Without the information about the form schema, the Field component cannot check if a field name is valid or if a component has compatible prop types for that field.

Let’s take a look at the more modern React Hook Form:

const { handleSubmit, control } = useForm({
  defaultValues: { email: "" },
});

return (
  <form
    onSubmit={handleSubmit((values) => {
      /* ... */
    })}
  >
    <Controller
      name="email"
      control={control}
      render={({ field }) => <EmailInput {...field} />}
    />
  </form>
);

Right out of the box, the situation is much better. A typo in a field name is immediately caught by the type system. That’s thanks to a neat FieldPath type defined within the library:

FieldPath<{ users: { email: string }[] }>
// "users" | `users.${number}` | `users.${number}.email`

React Hook Form also checks for some potential component compatibility issues:

function EmailInput(props: {
  value: number;
      // 👆 that's the wrong type for email!
  onChange: (value: string) => void;
}) {
  /* ... */
}

<Controller
  name="email"
  control={control}
  render={({ field }) => <EmailInput {...field} />}
/>;
// 🔴 Error:
// Types of property 'value' are incompatible.
// Type 'string' is not assignable to type 'number'.

However, it’s not without its own drawbacks. Yes, it requires a component’s value prop type to be compatible with the field. But at the same time React Hook Form doesn’t check for the onChange callback compatibility. Still, this can be fixed in a future release.

More importantly, all these type safety features are based on the form schema information inferred from the type of the control object. This means no type safety is guaranteed when the control object is passed implicitly via the FormProvider context:

const methods = useForm({
  defaultValues: { email: "" },
});

return (
  <FormProvider methods={methods}>
    <form>
      {/* that's a typo, but there won't be any errors! */}
      <Controller
        name="notmail"
        render={({ field }) => <EmailInput {...field} />}
      />
    </form>
  </FormProvider>
);

And finally, even if the control object is passed explicitly, sometimes these type safety features just aren’t very handy.

Let’s say we want to implement a reusable component for editing an address within a form. An address consists of several fields, and since we want our component to be reusable, we want to pass a prefix for those fields as a prop:

function AddressFieldset<T extends FieldValues>(props: {
  prefix: FieldPath<T>;
  control: Control<T>;
}) {
  return (
    <>
      <Controller
        control={props.control}
        name={`${props.prefix}.city`}
        render={() => {
          /* ... */
        }}
      />
      {/* ... */}
    </>
  );
}
// 🔴 Error:
// Type '`${Path<T>}.city`' is not assignable to type 'Path<T>'.

Unsurprisingly, the type system doesn’t allow us to append ".city" to a random field name since we cannot even be sure that the prefix points to an address. In this case, our only option is to opt out of strict typing and just use string instead of FieldPath:

function AddressFieldset(props: { prefix: string; control: Control }) {
  /* ... */
}

And that’s just unsportsmanlike!

Next, I’ll describe an interesting type of objects I’ll call “locators”. Using locators instead of strings for field names makes implementing type-safe forms just so much easier.

Introducing Locators

I think it’s best to start with an example. Take a look at the form schema:

type FormValues = {
  email: string;
  address: {
    city: string;
    street: string;
  };
};

This is a locator for this form:

const pathTag = Symbol("path");

const locator = {
  [pathTag]: "",
  email: {
    [pathTag]: "email",
  },
  address: {
    [pathTag]: "address",
    city: { [pathTag]: "address.city" },
    street: { [pathTag]: "address.street" },
  },
};

You’ll notice two things about this object:

it has the same shape as the form values object, and
instead of field values, it stores field paths.

You can say that a locator is an object that stores a path for each of its properties: locator.email[pathTag] equals "email", and locator.address.city[pathTag] equals "address.city".

To add a type annotation to this locator, we could simply write something like this:

const pathTag = Symbol("path");

interface Locator {
  [pathTag]: string;
  email: {
    [pathTag]: string;
  };
  address: {
    [pathTag]: string;
    city: {
      [pathTag]: string;
    };
    street: {
      [pathTag]: string;
    };
  };
}

But let’s go a step further. Along with a path for each form field stored in the locator’s value, we’ll actually have a type for each form field stored in the locator’s type:

const typeTag = Symbol("type");
const pathTag = Symbol("path");

interface Locator {
  [typeTag]?: FormValues;
  [pathTag]: string;
  email: {
    [typeTag]?: FormValues["email"]; // 👈
    [pathTag]: string;
  };
  address: {
    [typeTag]?: FormValues["address"]; // 👈
    [pathTag]: string;
    city: {
      [typeTag]?: FormValues["address"]["city"]; // 👈
      [pathTag]: string;
    };
    street: {
      [typeTag]?: FormValues["address"]["street"]; // 👈
      [pathTag]: string;
    };
  };
}

The neat thing is, we don’t have to do it manually. We can construct locator type for any form schema with a recursive generic type:

const typeTag = Symbol("type");
const pathTag = Symbol("path");

type Locator<T> = {
  [typeTag]?: T;
  [pathTag]: string;
} & (T extends Record<string, unknown>
  ? { [K in keyof T]: Locator<T[K]> }
  : T extends (infer R)[]
  ? Locator<R>[]
  : {});

But can we actually implement an object that matches this type? Sure we can! A locator is basically a string builder that appends a property name to a string each time that property is accessed. We can implement it using a proxy:

function getLocator<T>(prefix: string = ""): Locator<T> {
  return new Proxy(
    {},
    {
      get(target, key) {
        if (key === pathTag) {
          return prefix;
        }
        
        if (typeof key === "symbol") {
          throw new Error("Symbol path segments are not allowed in locator");
        }
        
        const nextPrefix = prefix ? `${prefix}.${key}` : key;
        return getLocator(nextPrefix);
      },
    }
  ) as Locator<T>;
}

This is a reference implementation. There’s some room for optimazation, e.g. we can reuse the same get handler for all proxies instead of creating a new closure each time.

So, how do locators help us implement type-safe forms? Here’s what an API for our hypothetical locator-based form library might look like:

function useForm<T>(options: { initialValues: T }): { n: Locator<T> } {
  return {
    n: getLocator<T>(), // 👈1️⃣
    /* ... */
  };
}

function Field<V>(props: {
  name: Locator<V>; // 👈2️⃣
  render: (field: {
    name: string;
    value: V; // 👈3️⃣
    onChange: (value: V) => void;
  }) => ReactElement;
}) {
  return props.render({
    name: props.name[pathTag],
    /* ... */
  });
}

There are three things to note here:

The useForm hook returns the “root” locator for the form schema, called n for brevity.
Locator is used instead of a string for the name prop of the Field component.
The Field component can infer the value type of the field from the locator and type arguments for its render prop accordingly.

The user of our library gets the root locator from the useForm hook and must use it to construct field names:

const { n } = useForm({
  initialValues: {
    users: [
      {
        email: "",
        address: {
          city: "",
          street: "",
        },
      },
    ],
  },
});

<Field
  name={n.users[0].email}
  render={(field) => <EmailInput {...field} />}
/>;

Since the locator’s type has the same shape as the form values, there’s no way to build a locator that points to a non-existent field. And the types for our field’s render prop ensure that whatever component is used for the field, it is compatible with the field’s value type.

It’s also very easy to create a reusable set of fields:

function AddressFieldset(props: {
  prefix: Locator<{ city: string; street: string }>;
}) {
  return (
    <>
      <Field
        name={props.prefix.city}
        render={() => {
          /* ... */
        }}
      />
      {/* ... */}
    </>
  );
}

<AddressFieldset prefix={n.users[0].address} />

This component only accepts a locator pointing to an address in its prefix prop. We can be sure that the value pointed to by this locator is indeed an address, and has all the properties an address should have.

Even better, locator types are covariant, so instead of passing an address, we can pass a locator that points to any value which is assignable to an address!

And as a cherry on top, you can totally rename a property on the FormValues type, and your IDE will rename that property in every locator where it’s used. That’s super useful for refactoring!

There’s just one more thing: it’s still possible to accidentally pass a locator from one form to a field on another form:

const { form, n } = useForm({
  initialValues: { email: '' }
});

const { form: anotherForm, n: anotherN } = useForm({
  initialValues: { notemail: '' }
});

<FormProvider form={anotherForm}>
  {/* that's bad 👇 there's no "email" in "anotherForm" */}
  <Field name={n.email} render={() => {
    /* ... */
  }} />
</FormProvider>

We can’t catch that at build time. But at least we can handle this error at runtime by “branding” our locators.

A brand is just a unique value that we’ll add to a form’s root locator. Each locator constructed from that root locator should have the same brand. And in the Field component, we’ll check that the brand of the locator matches the brand of the form:

function useForm<T>(options: { initialValues: T }) {
  const [brand] = useState(() => Symbol('formBrand'));

  return {
    // 1️⃣ the root locator "n" and all other locators constructed
    // from it will be branded by the same unique value
    n: getLocator<T>(brand),

    // 2️⃣ the same unique value is accessible via context as well
    form: { brand, /* ... */ },
  };
}

function Field<V>(props: {
  name: Locator<V>;
  /* ... */
}) {
  const { brand } = useContext(FormContext);

  // 3️⃣ matching the form brand with the locator brand
  if (brand !== name[brandTag]) {
    throw new Error('Foreign locator used to address form field');
  }

  /* ... */
}

It’s a shame we can’t express the same guarantee in the type system. But unfortunately, React contexts are hard to type properly.

I’ve worked on a project with dozens of huge web forms, some with more than a hundred fields. (As you’ve probably guessed it, this job was in the B2B division of a large bank.) Ensuring a smooth user experience was key, but we couldn’t have done it without great developer experience. Taking the approach described in this article was a huge help. It gave us all the tools we needed to catch bugs early and ship with confidence.

I hope it helps you too!

Не используйте строковые идентификаторы полей в формах (используйте локаторы)

2023-03-06T02:06:14.588Z

Все реактовые библиотеки для работы с формами похожи друг на друга (и каждая несчастлива по-своему).

Вот, например, Formik:

<Formik
  initialValues={{ email: "" }}
  onSubmit={(values) => {
    /* ... */
  }}
>
  <Form>
    <Field name="email" as={EmailInput} />
  </Form>
</Formik>

Если мы опечатаемся в названии поля, мы не получим ошибки ни на уровне типов, ни в рантайме:

// опечатка! 👇
<Field name="notmail" as={EmailInput} />

Вместо этого колбэк onSubmit получит неожиданные значения в качестве
аргумента.

Если кастомный комопнент EmailInput имеет апи, не совместимый с формиком, мы также не получим ошибки ни на уровне типов, ни в рантайме — форма просто не будет работать:

function EmailInput(props: {
  value: string;
  onChange: (value: string) => void /* несовместимо с Formik! */;
}) {
  /* ... */
}

Так просиходит, поскольку компонент Field ничего не знает о схеме формы и о
типе поля email в частности.

Посмотрим на более модный React Hook Form:

const { handleSubmit, control } = useForm({
  defaultValues: { email: "" },
});

return (
  <form
    onSubmit={handleSubmit((values) => {
      /* ... */
    })}
  >
    <Controller
      name="email"
      control={control}
      render={({ field }) => <EmailInput {...field} />}
    />
  </form>
);

Дела обстоят лучше. Опечатка в названии поля будет обнаружена на уровне типов. Это благодаря хитрому типу FieldPath, которым типизирован проп name:

type T = FieldPath<{ users: { email: string }[] }>;
// "users" | `users.${number}` | `users.${number}.email`

Совместимость кастомных контролов с библиотекой также частично гарантируется типами:

function EmailInput(props: {
  value: number /* неподходящий тип */;
  onChange: (value: string) => void;
}) {
  /* ... */
}

<Controller
  name="email"
  control={control}
  render={({ field }) => <EmailInput {...field} />}
/>;
// Ошибка:
// Types of property 'value' are incompatible.
// Type 'string' is not assignable to type 'number'.

Но есть и недостатки. Во-первых, проверка совместимости только частичная:
несовместимая сигантура колбэка onChange, например, не приведёт к ошибке. Это на совести авторов библиотеки и вполне может быть исправлено.

Во-вторых, вся магия держится на информации о схеме формы, содержащейся в типе control. Если control передаётся неявно через контекст, проверки не работают:

const methods = useForm({
  defaultValues: { email: "" },
});

return (
  <FormProvider methods={methods}>
    <form>
      {/* опечатка, но ошибки не будет */}
      <Controller
        name="notmail"
        render={({ field }) => <EmailInput {...field} />}
      />
    </form>
  </FormProvider>
);

В-третьих, типизация пропа name затрудняет разработку переиспользуемых наборов полей. Например, мы делаем переиспользуемый компонент для редактирования адресов. Мы не знаем заранее, где именно в данных формы хранится адрес, поэтому «префикс» (путь к полю с адресом) передаётся пропом.

function AddressFieldset<T extends FieldValues>(props: {
  prefix: FieldPath<T>;
  control: Control<T>;
}) {
  return (
    <>
      <Controller
        control={props.control}
        name={`${props.prefix}.city`}
        render={() => {
          /* ... */
        }}
      />
      {/* ... */}
    </>
  );
}
// Ошибка:
// Type '`${Path<T>}.city`' is not assignable to type 'Path<T>'.

Ожидаемо, типы не позволяют нам добавить ".city" к произвольному пути и
надеяться, что такое поле существует. Мы даже не можем быть уверены, что
prefix действительно указывает на адрес. Скорее всего, в таком случае нам
придётся отказаться от строгой типизации совсем:

function AddressFieldset(props: { prefix: string; control: Control }) {
  /* ... */
}

Грустно!

Далее я опишу новую сущность — «локатор». Использование локаторов вместо строк в качестве идентификатора поля в форме (то есть в качестве значения пропа name) позволит реализовать безопасные, строго типизированные формы.

Локаторы

Локатор строится на основе схемы формы. Например:

type FormValues = {
  email: string;
  address: {
    city: string;
    street: string;
  };
};

Локатор для этой схемы будет выглядеть так:

const typeTag = Symbol("type");
const pathTag = Symbol("path");

const locator: {
  [typeTag]?: FormValues;
  [pathTag]: string;
  email: {
    [typeTag]?: FormValues["email"];
    [pathTag]: string;
  };
  address: {
    [typeTag]?: FormValues["address"];
    [pathTag]: string;
    city: {
      [typeTag]?: string;
      [pathTag]: string;
    };
    street: {
      [typeTag]?: string;
      [pathTag]: string;
    };
  };
} = {
  [pathTag]: "",
  email: {
    [pathTag]: "email",
  },
  address: {
    [pathTag]: "address",
    city: { [pathTag]: "address.city" },
    street: { [pathTag]: "address.street" },
  },
};

Здесь тип и реализация локатора описаны вручную. Разумеется, далее мы реализуем дженерик локатор для произвольного объекта.

Локатор имеет три важных свойства:

Локатор имеет ту же структуру, что и исходный тип.
Для каждого поля исходного типа локатор хранит информацию о пути этого поля.
На уровне типов, для каждого поля исходного типа локатор хранит информацию о типе этого поля.

Опишем локатор как дженерик тип:

const typeTag = Symbol("type");
const pathTag = Symbol("path");

type Locator<T> = {
  [typeTag]?: T;
  [pathTag]: string;
} & (T extends Record<string, unknown>
  ? { [K in keyof T]: Locator<T[K]> }
  : T extends (infer R)[]
  ? Locator<R>[]
  : {});

С точки зрения реализации, локатор — это билдер строк, в котором каждое обращение к свойству билдера добавляет название этого свойства к строке. Для реализации используем прокси:

function getLocator<T>(prefix: string = ""): Locator<T> {
  return new Proxy(
    {},
    {
      get(target, key) {
        if (key === pathTag) {
          return prefix;
        }
        
        if (typeof key === "symbol") {
          throw new Error("Symbol path segments are not allowed in locator");
        }
        
        const nextPrefix = prefix ? `${prefix}.${key}` : key;
        return getLocator(nextPrefix);
      },
    }
  ) as Locator<T>;
}

Эту реализацию можно оптимизировать, переиспользуя один и тот же перехватчик get, вместо того чтобы создавать каждый раз новое замыкание:

const handlers: ProxyHandler<{ prefix: string }> = {
  get({ prefix }, key) {
    if (key === pathTag) {
      return prefix;
    }

    if (typeof key === "symbol") {
      throw new Error("Symbol path segments are not allowed in locator");
    }

    const nextPrefix = prefix ? `${prefix}.${key}` : key;
    return new Proxy({ prefix: nextPrefix }, handlers);
  },
};

const rootLocator = new Proxy({ prefix: "" }, handlers);

function getLocator<T>(): Locator<T> {
  return rootLocator as unknown as Locator<T>;
}

Использование локатора в форме

Апи нашей гипотетической библиотеки для работы с формами упрощённо может
выглядеть так:

function useForm<T>(options: { initialValues: T }): { n: Locator<T> } {
  return {
    n: getLocator<T>(),
    /* ... */
  };
}

function Field<V>(props: {
  name: Locator<V>;
  render: (field: {
    name: string;
    value: V;
    onChange: (value: V) => void;
  }) => ReactElement;
}) {
  return props.render({
    name: props.name[pathTag],
    /* ... */
  });
}

Пользователь библиотеки получает корневой локатор из хука useForm и использует его в качестве имени поля:

const { n } = useForm({
  initialValues: {
    users: [
      {
        email: "",
        address: {
          city: "",
          street: "",
        },
      },
    ],
  },
});

<Field
  name={n.users[0].email}
  render={(field) => <EmailInput {...field} />}
/>;

Локатор не позволит создать имя, которого не существует в форме. Типы для пропа render не позволят использовать компонент, пропы которого не совместимы с библиотекой.

Типизировать переиспользуемые наборы полей тоже стало проще:

function AddressFieldset(props: {
  prefix: Locator<{ city: string; street: string }>;
}) {
  return (
    <>
      <Field
        name={props.prefix.city}
        render={() => {
          /* ... */
        }}
      />
      {/* ... */}
    </>
  );
}

<AddressFieldset prefix={n.users[0].address} />

Этот компонент требует, чтобы ему передали локатор, указывающий именно на адрес, и поэтому может безопасно обращаться к полям адреса через переданный локатор. И, поскольку локатор повторяет структуру исходного объекта, вместо локатора адреса можно передать локатор любого объекта, совместимого с адресом по присваиванию.

И, кстати, рефакторинг на названиях полей теперь работает.

Защита от чужого локатора

Мы не должны разрешать использовать локатор одной формы для полей другой формы.

const { form, n } = useForm({
  initialValues: { email: '' }
});

const { form: anotherForm, n: anotherN } = useForm({
  initialValues: { notemail: '' }
});

<FormProvider form={anotherForm}>
  {/* плохо: в anotherForm нет email */}
  <Field name={n.email} render={() => {
    /* ... */
  }} />
</FormProvider>

Защититься от использования чужого локатора мы можем только в рантайме. Подход такой: пометим саму форму и её корневой локатор уникальным значением — «брендом»; производные локаторы наследуют бренд от своего родителя; компонент Field проверяет совпадение бренда формы и бренда локатора.

function useForm<T>(options: { initialValues: T }) {
  const [brand] = useState(() => Symbol('formBrand'));

  return {
    // локатор n и все производные от него будут помечены
    // брендом, уникальным для этой формы
    n: getLocator<T>(brand),

    // тот же самый бренд будет и в контексте формы
    form: { brand, /* ... */ },
  };
}

function Field<V>(props: {
  name: Locator<V>;
  /* ... */
}) {
  const { brand } = useContext(FormContext);

  // сверям бренд из контекста формы и бренд локатора
  if (brand !== name[brandTag]) {
    throw new Error('Foreign locator used to address form field');
  }

  /* ... */
}

Жаль, что нельзя защититься от чужих локаторов на уровне типов, но контексты вообще плохо поддаются строгой типизации.

Заключение

Однажды кто-то, кому менее лень, использует описанные принципы для создания по-настоящему типобезопасной библиотеки для работы с формами.

Контейнер обнимает текст

2022-09-04T01:16:23.241Z

Про странности работы с размером шрифта и высотой строки на вебе уже писали, и лучше моего. Но зря я что ли сам разбирался! Плюс, я принёс практические решения. Так что давайте ещё разок.

Метрики шрифта

Коротко, файл со шрифтом содержит несколько важных циферок. Это метрики шрифта:

Размер em-квадрата. Это произвольная область, задающая масштаб системы координат для знаков внутри шрифта.
Положение базовой линии. Базовая линия задаёт начало координат. По договорённости, буквы без нижних выносных элементов «стоят» прямо на базовой линии.
Высота заглавных букв (cap height). Если автор шрифта не накосячил, это действительно высота заглавных букв без выносных элементов.
Высота строчных букв (x height) — аналогично, буквально высота буквы „x“.
Ascender и descender. Показывают, сколько места давать буквам сверху и снизу от базовой линии. В сумме они задают «естественную» высоту строки для шрифта.

Например, у шрифта Source Sans 3 такие метрики:

Размер em-квадрата: 1000 единиц
Базовая линия: 200 единиц от нижней стороны квадрата (и, соответственно, 800 единиц от верхней)
Высота заглавных: 660 единиц
Высота строчных: 478 единиц
Ascender: 1024, descender: 400, в сумме 1424 единицы.

— Петька, cap height!
— 660!
— Что 660?
— А что cap height?

Шрифты векторные, так что никаких абсолютных единиц, вроде пикселей, внутри самого шрифта нет. Есть только сетка единиц, задаваемая em-квадратом и базовой линией.

Что мы имеем в виду, когда говорим font-size

Указывая в CSS размер шрифта в пикселях (например, font-size: 100px), мы на самом деле задаём абсолютный размер em-квадрата. Собственно, поэтому текущий размер шрифта в CSS — это 1em.

Немного арифметики. У Source Sans 3 em-квадрат на 1000 единиц, так что при font-size: 100px одна единица в координатах шрифта в реальности занимает на экране 0,1 пиксель. Заглавные буквы высотой 660 единиц имеют реальную высоту 66 пикселей. А span с таким размером шрифта имеет высоту 142,4 пикселя (с округлением до целого физического пикселя).

Em-квадрат — относительно произвольная область, не видимая невооружённым взглядом. В зависимости от того, как она задана, разные шрифты будут выглядеть крупнее или мельче при том же размере шрифта.

По возрастанию: Crimson Pro, Source Sans 3, Roboto с одним и тем же размером шрифта имеют разный визуальный размер.

При сочетании разных шрифтов на одной странице такая непредсказуемость становится проблемой.

Делаем размер шрифта предсказуемым

Что считать настоящим визуальным размером шрифта: высоту строчных (x height) или высоту заглавных (cap height)? В интерфейсе, если надо выровнять текст с иконкой, я обычно ориентируюсь на заглавные; а в журнальной вёрстке сочетают шрифты с одинаковой высотой строчных.

Для себя я выбрал высоту заглавных как визуальную метрику размера шрифта, а если вам это не подходит — просто замените везде дальше cap height на x height.

Зная размер em-квадрата и cap height, посчитаем, какой указывать font-size, чтобы получить желаемую высоту заглавных:

размер шрифта = желаемая высота заглавных ÷ высота заглавных в em
высота заглавных в em = высота заглавных ÷ размер em-квардрата

Например, хотим иметь одну высоту заглавных в 72 пикселя для трёх разных шрифтов:

Source Sans 3: 72px ÷ (660 / 1000) ≈ 109px
Crimson Pro: 72px ÷ (587 / 1024) ≈ 126px
Roboto: 72px ÷ (1456 / 2048) ≈ 101px.

Равенство, братство: Crimson Pro с размером 126 пикселей, Source Sans 3 с размером 109 пикселей, Roboto с размером 101 пиксель.

На практике, чтобы не считать руками каждый раз, заведём несколько вспомогательных стилей:

:root {
  font-family: 'Source Sans 3';
  --cap-height-em: 0.66; /* = 660 / 1000 */
}

/* Typography helper */
.tyh {
  font-size: calc(var(--cap-height) / var(--cap-height-em));
}

Используя наш класс-хелпер, мы теперь можем где угодно задавать размер шрифта, ориентируясь на высоту заглавных:

<p class="tyh" style="--cap-height: 72px">
  Hello, world!
</p>

Предсказуемость!

Теперь про высоту строки

В метриках неявно зашита «естественная» высота строки для этого шрифта, равная сумме ascender + descender. Указывая в CSS явный line-height, мы просим браузер докинуть отступов к этой высоте. Эти дополнительные отступы, которые называются leading — читается [лэдинг], — распределяются поровну сверху и снизу:

Вертикальное положение букв в этой области зависит от отношения ascender к descender. Ещё немного арифметики: возьмём Source Sans 3 в блоке с font-size: 100px и line-height: 150px. Естественная высота строки при таком размере шрифта равна 142,4 пикселя (округлим до 142). Значит, браузер добавит к блоку 4 дополнительных пикселя сверху и снизу.

При этом расстояние от нижнего края блока до базовой линии составит

descender + ½ leading =
40 + 4 = 44px,

а от верхнего края до верхнего края заглавных —

ascender + ½ leading − cap height =
102,4 + 4 − 66 ≈ 40px.

Получается, заглавные буквы оказываются не строго в центре области, выделенной под строку. Это тоже головная боль, например, в интерфейсах, когда иконка и текст в блоках равной высоты оказываются смещены относительно друг друга.

Контейнер обнимает текст

В идеальном мире, свойство line-height устанавливает только расстояние между базовыми линиями строк текста, не добавляя дополнительных отступов над первой и под последней строкой.

В ещё более идеальном мире вертикальное положение текста в блоке вообще не зависит от таких произвольных метрик, как ascender и descender. Для взаимного выравнивания блоков с текстом удобнее всего, если верхний край блока прижимается к верхнему краю заглавных, а нижний — к базовой линии.

Границы текстового блока в идеальном мире.

Научим наш класс .tyh производить все необходимые расчёты:

:root {
  font-family: 'Source Sans 3';
  --cap-height-em: 0.66; /* = 660 / 1000 */
  --ascender-em: 1.024; /* = 1024 / 1000 */
  --descender-em: 0.4; /* = 400 / 1000 */
}

/* Typography helper */
.tyh {
  /* Коэффициент для перевода em в абсолютные величины,
     а заодно и значение font-size: */
  --units-per-em: calc(var(--cap-height) / var(--cap-height-em));

  --half-leading: calc((
    var(--line-spacing) -
    (var(--ascender-em) + var(--descender-em)) * var(--units-per-em)
  ) / 2);

  --trim-top: calc(-1 * (
    var(--half-leading) +
    var(--ascender-em) * var(--units-per-em) -
    var(--cap-height)
  ));

  --trim-bottom: calc(-1 * (
    var(--half-leading) +
    var(--descender-em) * var(--units-per-em)
  ));
  
  font-size: var(--units-per-em);
  line-height: var(--line-spacing);
}

Осталось добавить блоку отрицательные поля, откусывающие --trim-top сверху и --trim-bottom снизу. Чтобы избежать проблем с margin collapsing, добавим их не самому блоку, а псевдоэлементам в начале и конце блока:

.th::before,
.th::after {
  content: "";
  display: table;
}

.th::before {
  margin-bottom: var(--trim-top);
}

.th::after {
  margin-top: var(--trim-bottom);
}

Готово:

<p class="tyh" style="--cap-height: 72px; --line-spacing: 100px;">
  The quick brown fox jumps
</p>

А вот и демка.

Зачем всё это было, и что делать дальше

Используя класс .tyh, гораздо проще подгонять текстовые блоки друг к другу, к иллюстрациям и к иконкам. Отдельно замечу, что заодно стало куда легче следить за приводностью вёрстки.

При этом я не считаю, что стоит тащить такой CSS везде. Во-первых, вам придётся объяснить своим коллегам всё то, что я попытался объяснить в этой статье, а это уже не тривиальная задача. Во-вторых, кому-то придётся следить за актуальностью захардкоженных метрик в коде, либо придумывать пайплайн, чтобы автоматизировать их генерацию. В-третьих, возможно, такой перфекционизм просто никому не нужен.

Но если вы всё же решите заморочиться, метрики шрифта можно подсмотреть в FontForge (полезнейшее приложение с ужасным, ужасным интерфейсом), либо достать программно библиотеками вроде fontkit.

Наконец, рекомендую прочитать прекрасные статьи из следующего раздела. Там особенно интересно, откуда взялись все эти странные термины, вроде em square и leading.

Литература

Три статьи, описывающие предметную область лучше, чем я:

Font size is useless; let’s fix it
Deep dive CSS: font metrics, line-height and vertical-align
Getting to the bottom of line height in Figma

Основное вдохновение для класса .tyh — библиотека Capsize.

Завтра в это же время: на удивление сложная реализация на JavaScript

2022-05-22T02:36:24.703Z

Задача: имея юникстайм и название часового пояса, получить юникстайм этого же времени дня на следующий день.

Например: 1648292400 Europe/Prague (26 марта 2022, 12:00 по местному времени). Хотим получить 1648375200 Europe/Prague (27 марта 2022, 12:00 по местному времени).

Решение на JavaScript: на удивление сложное.

Первая наивная попытка

Добавим 24 часа к исходному таймстэмпу:

const timestamp = 1648292400;
const timeZone = "Europe/Prague";
const thisTimeTomorrow = timestamp + 24 * 60 * 60;
console.log(thisTimeTomorrow, timeZone);
// 1648378800 Europe/Prague

На удивление, полученный тайстэмп соотвествует не 12:00, а 13:00 по местному времени. По совпадению, именно в ночь с 26 на 27 марта в Чехии переводят часы на летнее время — на час вперёд. Как результат, полдень 26 и 27 марта отделяет всего 23, а не 24 часа.

Вторая наивная попытка

Не будем работать с датой и временем самостоятельно, доверимся классу Date стандартной библиотеки:

const timestamp = 1648292400;
const date = new Date(timestamp * 1000);
date.setDate(date.getDate() + 1);
console.log(date);
console.log(Math.floor(date / 1000));

Этот код прекрасно работает, если системный часовой пояс — Europe/Prague:

Sun Mar 27 2022 12:00:00 GMT+0200 (Central European Summer Time)
1648375200

(В этом легко убедиться, исполнив код в консоли Chrome. Предварительно в панели Sensors надо переопределить текущее местоположение и указать соответствующий Timezone ID.)

Если же код работает на серверах, которые принято держать в UTC, получим другой результат:

Sun Mar 27 2022 11:00:00 GMT+0000 (Coordinated Universal Time)
1648378800

Этот ошибочный результат ожидаемо совпадает с первой наивной попыткой.

Проблема с Date

Класс Date умеет работать только с двумя часовыми поясами: системным и UTC. Методы getDate, getHours, toString и другие интерпретируют таймстэмп по местному времени, а их аналоги getUTCDate, getUTCHours, toUTCString — по UTC.

(Стилистические вопросы написания аббревиатур в идентификаторах ~~выходят~~ выходили бы за рамки этой статьи, если бы ответ не был прост: всегда getUtcDate. Впрочем, после XMLHttpRequest наши ожидания не высоки.)

В этом огромная слабость API для работы с датой и временем в JavaScript. Попытка закрыть этот недочёт предпринята в новом API Intl.DateTimeFormat, который позволяет интерпретировать таймстэмп в любом часовом поясе:

const formatter = new Intl.DateTimeFormat("en-US", {
  timeZone: "Europe/Prague",
  dateStyle: "long",
  timeStyle: "long",
});

console.log(formatter.format(new Date(1648292400 * 1000)));
// March 26, 2022 at 12:00:00 PM GMT+1

console.log(formatter.format(new Date(1648375200 * 1000)));
// March 27, 2022 at 12:00:00 PM GMT+2

Однако, говоря «интерпретировать таймстэмп», мы подразумеваем две задачи:

Отформатировать числовой таймстэмп как строку в заданном часовом поясе
Прочитать строку с датой и временем как таймстэмп в заданном часовом поясе

Intl.DateTimeFormat решает первую задачу. Для второй задачи в JavaScript по-прежнему не существует простого решения.

Третья попытка

Несмотря на свою неполноту, Intl.DateTimeFormat приближает нас к решению задачи, поскольку даёт доступ к ключевой информации: какой временной сдвиг действует в данный момент в данном часовом поясе.

Извлечём эту информацию:

const offsetPattern = /GMT([+-]\d+)/;

function getTimeZoneOffset(timestamp, timeZone) {
  const formatter = new Intl.DateTimeFormat("en-US", {
    timeStyle: "long",
    timeZone,
  });
  const localTimeStr = formatter.format(new Date(timestamp * 1000));
  const offsetMatch = localTimeStr.match(offsetPattern);
  const offsetSecs = Number.parseInt(offsetMatch[1]) * 60 * 60;
  return offsetSecs;
}

console.log(getTimeZoneOffset(1648292400, "Europe/Prague"));
// 3600

console.log(getTimeZoneOffset(1648375200, "Europe/Prague"));
// 7200

Используя эту вспомогательную функцию, обновим наше первое наивное решение:

const timestamp = 1648292400;
const timeZone = "Europe/Prague";
const tomorrow = timestamp + 24 * 60 * 60;
const thisTimeTomorrow =
  tomorrow +
  getTimeZoneOffset(timestamp, timeZone) -
  getTimeZoneOffset(tomorrow, timeZone);
console.log(thisTimeTomorrow, timeZone);
// 1648375200 Europe/Prague

И это уже похоже на правду.

Заключительные примечания

Во-первых, наше решение ломается на 1648258200 Europe/Prague (26 марта 2022, 2:30 по местному времени) — мы получим 1648341000 Europe/Prague (27 марта, 01:30 по местному времени). Впрочем, не понятно, что значит «завтра в это же время» в таком случае: стрелки переводятся вперёд в два часа ночи, так что 02:30 просто не существует 27 марта.

Во-вторых, естественно, эта задача уже решена в библиотеках. Например, с использованием date-fns-tz:

const thisTimeTomorrow = zonedTimeToUtc(
  addDays(utcToZonedTime(timestamp, timeZone), 1),
  timeZone
);

В-третьих, эта задача хорошо показывает, почему недостаточно хранить только временной сдвиг часового пояса вместе с тайстэмпом. Всегда храните название часового пояса по IANA.

В-четвёртых, страны иногда меняют правила перехода на летнее время и временные сдвиги часовых поясов. Не факт, что ваш рантайм своевременно отразит эти изменения. Например, Node.js бандлит библиотеку ICU, содержащую эту информацию. Не обновив Node.js, вы не получите актуальную информацию о часовых поясах.

Если эта информация критична для работы вашего приложения, пересоберите Node.js с флагом --with-intl=system-icu и своевременно обновляйте библиотеку ICU в вашей системе.

Вывод

Не завидую тем, кому приходится работать с часовыми поясами.