Делиться своими идеями с сообществом - хорошо и полезно. Это позволяет развиваться, перенимать лучшие практики, исследовать новые инструменты, учиться оформлять свои решения. Но какой код стоит выносить в общий доступ? И как делать это на постоянной основе? Чтобы разобраться в этих вопросах, я решил сделать свой JavaScript OpenSource Boilerplate - маленькую, но максимально расширяемую библиотеку компонентов. Я назвал её handy-ones.
Задача
На самом деле задача формулируется даже шире, основной мотив в любом случае - исследовательский. Каждый день в JavaScript-мире появляются новые инструменты и технологии, противостояние ui-фреймворков сменилось борьбой js-рантаймов, бандлеров, стейт-менеджеров, утилит для работы с монорепозиториями. Мне понадобился проект, внутри которого я смогу экспериментировать с новыми технологиями, а удачные эксперименты легко оформлять и публиковать. Я сформулировал к нему такие требования:
Удобство и комфорт разработки. Проект должен запускаться и собираться быстро, должны быть доступны все возможные инструменты: HMR, source-maps и тд.
Удобство для потребителя. Компиляция в ES6, d.ts и source-maps внутри пакетов. Поставка через npm.
Минимальный time-to-market. От написания кода до дистрибуции должны проходить минуты.
Независимые сборка, поставка, тестирование отдельных компонентов системы. Кто знает, что нового придумают завтра, и в чем захочется поковыряться?
Минимальная конфигурация и максимальная унификация инструментов.
Документация и demo-стенды "из коробки".
Инструменты
Технологический стек, позволивший решить большинство этих задач, выглядит следующим образом:
npm для установки внешних и перелинковки локальных зависимостей;
turborepo для запуска скриптов;
tsc и postcss-cli для сборки пакетов;
vite для сборки сервисных бандлов;
ladle как движок для демо-стенда.
Часть этих инструментов супер-стандартные, другие, наоборот, очень свежие. Любой из них может вызвать споры. Я подробно расскажу про выбор каждого из них в отдельной статье, пока же просто скажу, что я ими доволен. И поделюсь первыми опубликованными компонентами моей библиотеки.
First ones
Первые компоненты - самые простые, базовые, атомарные. Но они же и самые универсальные и гибкие. Объединяет их еще и стремление решить задачу максимально нативным способом: взять все лучшее, что предлагает браузерное API, и написать поверх него минимальное количество JavaScript-кода.
Каждый из этих компонентов доступен через npm, но часто значимый код можно забрать прямо из гитхаба.
Всего таких компонентов четыре:
handy-clamp - React-компонент, умеющий прятать лишние строчки текста под "кат";
handy-range-slider - полностью кастомизируемый, но в тоже время нативный компонент выбора диапазона;
handy-scroll-strip - надстройка над браузерным скролл-баром, позволяющая изящно размещать на странице длинные горизонтальные блоки контента;
handy-svg - самый удобный способ встраивания
SVGв вебе. Я уже рассказывал о нем на Хабре.
В этих компонентах использованы подходы, к которым я прибегаю годами. Теперь же, благодаря бойлерплейту в handy-ones, я смог сделать их доступными всем. А добавить новый компонент или утилиту можно буквально за несколько минут, прямо за завтраком.
Расскажу о первой пачке компонентов подробнее.
Handy clamp
Типовая задача - спрятать лишний текст под "кат". Особенность handy-clamp в том, что он умеет обрезать текст по строчкам, а еще он отзывчивый и максимально нативный. В основе его работы две технологии:
Так и не ставшее стандартом, но поддержанное всеми современными браузерами css-свойство
line-clamp;ResizeObserver- браузерное API для отслеживания изменений размера элемента.
Дальше все просто - следим за размерами элемента с текстом, проверяем, помещается ли он в своего родителя:
const isOverflowing = el.scrollHeight > el.clientHeightЕсли не помещается - рисуем кнопку "Показать еще", если помещается - скрываем эту же кнопку. Заворачиваем идею в React-компонент, придумываем незамысловатое API.
import {HandyClamp} from '@handy-ones/handy-clamp';
<HandyClamp lines={2}>
Длинный-длинный текст в десятки строчек, который надо спрятать...
</HandyClamp>Публикуем, любуемся, ставим чайник, двигаемся дальше.
Handy range slider
Еще со времен jQuery я работал со множеством разных компонентов выбора диапазона, среди них слайдер из jQuery UI, замечательное standalone-решение noUiSlider, React-обертки в Material UI и Ant Design. И я знаю про опыт ребят из Тинькофф с кастомизацией нативного контрола range-инпута, это и правда впечатляющая работа. Но тащить в проект тяжелое решение снаружи не хотелось, а подход с css-кастомизацией нативного контрола не дает полной гибкости. Например, не получится покрасить трек слайдера градиентом. Плюс, css-магия вокруг нативного компонента меня немного пугает, я не очень понимаю, как поддерживать "три слоя градиента" и пачку вендорных префиксов.
Для горизонтального слайдера с одним ползунком я решил использовать нативный браузерный компонент, а для гибкой стилизации использовать элементы, отрендеренные через JavaScript. Для меня лучше всего сработал следующий подход:
Рендерим нативный слайдер нужного размера. И делаем все его элементы полностью прозрачными.
Рендерим под ним псевдо-контрол, любую удобную нам HTML-разметку, которая будет отвечать исключительно за отображение. Стилизуем ее как нам нравится.
Связываем нативный и псевдо контролы через локальный стейт. Тут нужно будет чуть-чуть арифметики и внимательно потестировать в разных браузерах.
В итоге пользователь управляет нативным контролом, а отображается расположенный слоем ниже псевдо-контрол, кастомизация которого никак не ограничена. И это работает, и это просто, и это мало кода, и это mobile-friendly.
Дальше - дело техники, тестируем в разных браузерах, придумываем API, способ отрисовки лейблов, оформляем код:
import {HandyRangeSlider} from '@handy-ones/handy-range-slider';
<HandyRangeSlider
min={50}
max={100}
step={2}
value={10}
labels={[
{value: 50, text: '😔'},
{value: 75, text: '😃'},
{value: 100, text: '❤️'}
]}
onChange={(event, parsedValue) => {}}
/>Проектировать АПИ у инпутов на самом деле очень просто, любые инпуты должны управляться всего двумя пропсами:
valueиonChange. А первым аргументом вonChangeвсегда должен приходить оригинальныйevent. Этот подход использует React, а также самые популярные библиотеки для работы с формами: Formik, React Hook Form, React Final Form.
Текущее решение работает во всех современных десктопных и мобильных браузерах, а также в IE 10+, если это по какой-то причине еще важно. Нет никаких проблем адаптировать handy-range-slider для вертикального отображения, но Firefox все еще не полностью его поддерживает.
Так что публикуем то, что есть, закидываем пару примеров на демо-стенд, чайник как раз вскипел.
Handy Scroll Strip
Простейший, но в то же время универсальнейший компонент: полоса прокрутки без браузерных контролов, но с фейдом по краям и императивным API. Я создавал на его основе галереи, мобильную навигацию, прятал в него огромные multistep-формы и широченные таблицы. Он очень производительный, ведь скролл в нем нативный. Хорошей идеей будет также его использование с css-scroll-step.
В реализации он очень прост:
Скрываем полосы прокрутки.
Добавляем блоки с градиентом по краям, слушаем скролл, отображаем их и прячем.
Реализуем императивное API, с ужасом продираясь через
useImperativeHandleи вспоминая, как удобно это было реализовано в классовых, а не функциональных компонентах.
Скрыть полосы прокрутки можно через css, это кроссбраузерно, хотя и многословно:
.content {
overflow-x: scroll;
overflow-y: hidden;
-webkit-overflow-scrolling: touch;
-ms-overflow-style: none; /* Internet Explorer 10+ */
scrollbar-width: none; /* Firefox */
}
.content::-webkit-scrollbar {
display: none; /* Safari and Chrome */
}В императивном API можно использовать нативный браузерный Element.scrollTo(), он уже давно умеет скроллить плавно:
element.scrollTo({
left: 2000,
behavior: 'smooth'
});Вот и всё, основные сложности тут будут с типизацией императивного API и forwardRef, но есть хороший пример в React Typescript Cheatsheet, интерфейс получается такой:
interface ImperativeHandlers {
getContainer: () => HTMLDivElement | null;
getScrollLeft: () => number;
scrollTo: (value: number) => void;
}Решить остальные проблемы поможет наш бойлерплейт. Закидываем в отдельную папку, публикуем и проверяем, что там осталось в холодильнике.
Handy SVG
Не буду подробно останавливаться на этой утилите, про нее у меня была отдельная статья на Хабре. Напомню только, что с ее помощью можно динамически встраивать SVG-изображения в web-проекты с любым технологическим стеком. Под капотом она делает fetch-запросы для получения кода SVG-изображений, формирует на странице спрайт символов и предоставляет React и standalone API для отрисовки:
import {HandySvg} from '@handy-ones/handy-svg';
import iconSrc from './icon.svg';
export const Icon = () => (
<HandySvg
src={iconSrc}
className="icon"
width="32"
height="32"
/>
);Утилита handy-svg какое-то время существовала как независимо решение, но сделать ее частью библиотеки handy-ones не составит труда. Благодаря изолированности отдельных проектов внутри монорепозитория не придется даже синхронизировать зависимости старых и новых библиотек, npm хорошо справляется с этим сам. Порядок действий такой же, как с новыми компонентами: новая папка, новый package.json, публикуем и выдыхаем. На сегодня кажется хватит.
Boilerplate
Конечно, часть этих инструментов очень простая и не требует такой развернутой инфраструктуры, а, может, и их публикация избыточна. Но, во-первых, основная задача первых четырех компонентов - как раз попилотировать бойлерплейт, а во-вторых, вы никогда не знаете, что из ваших идей будет полезно сообществу, а что нет.
Мой совет - не надо долго пыхтеть и вымучивать что-то заумное, большинство хороших решений простые. Гораздо важнее принцип fail-fast - оформите свое решение, поделитесь им, выслушайте критику, двигайтесь дальше. Даже стендап-комики с многолетним опытом не понимают, смешная ли шутка, пока не расскажут ее перед аудиторией*. Важно делать легко и просто, как щелкать пальцами, тогда шансы сделать что-то по-настоящему полезное сильно возрастают.
Вопросы, комментарии а также пул-реквесты всячески приветствуются.
Я буду развивать handy-ones по мере возможностей, за завтраком и в дороге, и в любое удобное время, главное, что теперь у меня есть отличный инструмент для этого. Как раз про него, а также про то, почему я не стал использовать lerna, tsup, esbuild, storybook, yarn и всерьез подумывал про gulp, я расскажу в следующей статье.
* Видео, на котором Луи Си Кей рассказывает про это, удалили с Ютуба, про него немного помнит reddit и, я надеюсь, кто-то из читателей.
