Перейти к содержимому

Подробно

Как сделать палитру команд Ctrl+K, которая работает офлайн

Опубликовано · 8 мин чтения·

Возможность Seed: Горячие клавиши →

Другие языки: العربية, Deutsch, English, Español, Français, 日本語, Português (Brasil) и 简体中文

Пустая фиолетовая клавиша светится на столе рядом с выдернутым кабелем, а над ней поднимаются четыре бумажные карточки: луна, солнце, страница и дом.

Коротко

  • Палитра команд должна управлять приложением, а не только искать. Страницы, действия «создать» и настройки — всё это команды, и настройка меняется в тот же миг, как вы нажали Enter.
  • Сравнивайте с началами слов, прощайте одну опечатку на слово и читайте запрос в другой раскладке. Тогда «notse» находит Notes, а «ntvf» — Theme.
  • Никогда не заканчивайте на «No results». Предложите создать то, что напечатано, ищите в копии на устройстве, когда сервер недоступен, и приглушайте то, чему нужна сеть.
  • Держите всё в одном чистом списке: на входе состояние приложения, на выходе команды. Клавиши берутся из единого списка горячих клавиш, так что палитра и диалог клавиш не расходятся.

Чтобы палитра команд Ctrl+K работала офлайн и люди к ней возвращались, она должна делать три вещи. Управляет приложением: каждая страница, каждое «New…» и каждая настройка — команда. Прощает то, как люди на самом деле печатают: опечатку, полслова, не ту раскладку. И никогда не заводит в тупик: если ничего не нашлось, предлагает создать то, что вы напечатали, а без сети ищет в копии на вашем устройстве. В Seed всё это получается из одного списка команд в одном файле.

Статья для разработчиков, которые добавляют Ctrl+K в своё веб-приложение. Сначала покажу, что палитра умеет, потом — файл, из которого она собрана, с настоящим кодом.

Палитра команд Seed, в поле поиска набрано «ntvf». Первая строка, подсвеченная под заголовком Commands, — Theme: на второй строке её раздел, Settings, а рядом текущее значение «System».

Что должна делать Ctrl+K, кроме поиска?

Откройте палитру и ничего не печатайте. Она уже полезна: пять последних выборов под Recent, команды текущей страницы, ваши свежие заметки и Create. Сам я чаще всего открываю палитру ради «верни меня к той штуке» или «сделай здесь очевидное», и ни то ни другое не должно требовать набора.

Наберите один >, и она перечислит всё, что умеет приложение, под пятью заголовками: This page, Go to, Create, Settings и Account (примеры здесь и ниже — в английской версии приложения, поэтому названия на экране английские). Наберите что-нибудь другое, и подходящие команды соберутся под одним заголовком Commands, в каждой строке будет указан её раздел, а ниже — Create. Несколько решений, которые окупились:

  • Настройки срабатывают сразу. Наберите light, нажмите Enter: страница становится светлой, а палитра остаётся открытой. Наберите dark, Enter — и всё как было. Не нужно идти на страницу настроек, чтобы понять, нравится ли.
  • Клавиши стоят рядом с командами. New note показывает свою клавишу, N, прямо в строке. Сочетание из двух клавиш, например G, затем N для страницы Notes, есть в диалоге Keyboard shortcuts, который читает тот же список команд. Шпаргалка уже встроена.
  • > значит «только команды». Начните запрос с > и печатайте дальше: заметки с группами не будут мешаться.
  • Enter ждёт ответа. На каждый запрос палитра даёт один ответ, включая заметки. Нажмёте Enter раньше, чем ответил сервер, — она подождёт, так что вы никогда не откроете строку, которая случайно была первой полсекунды назад.

Поле поиска, которое находит только заметки, — это полпалитры. Вторая половина — причина, по которой люди не снимают рук с клавиатуры.

Как она находит нужное сквозь опечатки и не ту раскладку?

Наберите notse, и первой строкой будет страница Notes. Наберите ntvf — получите Theme, как на картинке выше. Второе выглядит так, будто по клавиатуре прошла кошка. На самом деле это «тема», набранная с включённой английской раскладкой. На моей клавиатуре две раскладки, и я так часто оказываюсь не в той, что ntvf теперь тестовый случай.

Сравнение идёт по нескольким простым правилам:

  1. Регистр и диакритика не учитываются.
  2. Слова можно писать в любом порядке, и каждому набранному слову достаточно быть началом слова из названия команды или одного из её других названий. no all хватает для «all notes».
  3. В слове из четырёх букв и длиннее может быть одна опечатка: лишняя, пропущенная или не та буква либо две переставленные.
  4. Запрос читается ещё и так, будто включена другая раскладка, и через алфавиты, так что латиница может найти русское слово, и наоборот. Сейчас это английская и русская раскладки. Любой другой паре нужна своя таблица клавиш.

Когда совпадает несколько строк, побеждает более чистое совпадение: сначала точное название, потом название, начинающееся с запроса, потом совпавшие слова, потом псевдоним, потом другая раскладка и последней — опечатка. Поэтому прощённая опечатка никогда не оттесняет правильный ответ вниз.

Каждая команда несёт ещё и слова, которые люди пробуют, на английском и русском. Notes откликается на «all notes» и «заметки», Activity — на «history», «log» и «audit». Никто не помнит, как назвали страницу вы. Люди помнят, как назвали бы её сами.

Обычная альтернатива — нечёткий (fuzzy) поиск, который принимает любые буквы, лишь бы они шли по порядку. Для выбора файла он лучше: там gtn должен находить go-to-notes.ts. Для списка команд он слишком щедр: несколько букв могут совпасть со строками, не имеющими отношения к тому, что вы имели в виду, и он всё равно не знает, что ntvf — это слово. Начала слов плюс одна опечатка — строже, и это подходит коротким человеческим названиям.

Одна опечатка на слово — предел. Две опечатки в одном слове не найдут ничего: это поиск, а не телепат. Сравнение живёт в общей библиотеке под MIT, @spy4x/platform, которую можно подключить без остального Seed. Оно готовит названия каждой команды один раз, так что нажатие клавиши оплачивает только ранжирование.

Что она показывает, когда ничего не нашлось?

«No results» — это палитра говорит вам «уходите». В Seed она так не говорит никогда, потому что что бы вы ни напечатали, это вполне годное название для следующей вещи.

Наберите Palette demo. Так ничего не называется, поэтому раздел Create предлагает New note: “Palette demo”. Enter открывает форму новой заметки с уже заполненным заголовком. Ctrl+Enter пропускает форму: заметка создаётся и открывается.

Эти строки строятся из запроса, а не сравниваются с ним, поэтому их получает любой текст:

export function quickCreateRows(context: PaletteContext, query: string): PaletteOption[] {
  const { t, currentGroup } = context
  const title = query.trim()
  if (title === "") return []
  const writable = currentGroup?.canWrite && context.notes !== false ? currentGroup : null
  const row = (entity: QuickCreateEntity, key: string): PaletteOption => ({
    id: `quick-create-${entity}`,
    label: t.t(`Search.withText`, { label: t.t(key), text: isolate(quoted(title)) }),
    group: t.t(`Search.create`),
    choice: { kind: "quick-create", entity, title },
  })
  // …заметка и тег, когда человеку можно здесь писать, и группа
}

Читатель без права записи не получает строку «New note». Палитра предлагает только то, что предложили бы кнопки на странице.

Как она продолжает работать офлайн?

Без сети могут сломаться две вещи: поиску некого спросить, а некоторым командам некому их выполнить. Палитра справляется с каждой отдельно.

Поиск откатывается на устройство. Приложение Seed и так держит копию ваших заметок в локальной базе браузера (это офлайн-слой, на английском). Палитра сначала спрашивает сервер, а когда до него не достучаться, ищет в этой копии:

return async (query, signal) => {
  if (query === "") return { notes: await recentNotes(sources), onDevice: !sources.canCall() }
  if (sources.canCall()) {
    try {
      const answer = await sources.server(query, signal)
      return { notes: answer.notes.map(fromWire), onDevice: false }
    } catch (error) {
      if (signal.aborted || !(isUnreachable(error) || isProxyAnswer(error))) throw error
    }
  }
  return { notes: await notesOnDevice(sources, indexOf, query), onDevice: true }
}

Это apps/spa/src/state/search.ts. В нём важны три детали:

  • Заголовок меняется на «Notes on this device» («заметки на этом устройстве»), чтобы вы знали: ответ может быть старее серверного.
  • Откат включает только недоступный сервер. Отказ, например по лимиту запросов, показывается как ошибка. Спрятать его за локальными результатами значило бы вежливо соврать.
  • На устройстве могут остаться заметки группы, из которой вы вышли. Поиск смотрит только в группы, где вы состоите сейчас.

Локальный поиск — это небольшой индекс на устройстве, не тот механизм, что сравнивает команды, и он прощает те же промахи. Отключите сеть в демо, наберите pallette с двумя l — и найдётся заметка «Palette demo», которую вы создали выше через Ctrl+Enter. Как и по зфдуееу, тому же слову, набранному в русской раскладке.

Команды, которым нужен сервер, остаются в списке. Офлайн «New group» или «Delete my account» могли бы тихо исчезнуть из списка. Тогда вы гадали бы, есть ли такая функция вообще. Вместо этого они стоят на своих местах, приглушённые, с пометкой «Needs a connection» («нужно подключение»):

const SERVER_ONLY = new Set(
  [
    `import-notes`,
    `new-group`,
    `keep`,
    `download-data`,
    `change-picture`,
    `delete-account`,
    `turn-off-two-factor`,
    `end-other-sessions`,
  ].map((id) => `action-${id}`),
)

function needsServer(context: PaletteContext, option: PaletteOption): PaletteOption {
  return {
    ...option,
    disabledReason: context.online ? undefined : context.t.t(`Search.needsConnection`),
  }
}

New note и New tag в этом списке нет. Они работают офлайн: запись ждёт в очереди и уходит, когда связь вернётся.

Как она устроена? Один список команд

Весь реестр — это libs/ui/palette-commands.ts. Это чистая функция: на входе состояние приложения (кто вы, какая группа, есть ли сеть), на выходе список вариантов. Ни стора, ни fetch, ни роутера. Команда — одна запись:

{
  id: "notes",
  key: `Frame.notes`,
  href: (context) => context.notes === false ? null : NOTE_PATHS.list,
  aliases: [`notes list`, `all notes`, `заметки`, `список заметок`],
},

Ключ перевода для подписи, куда она ведёт, слова, которые её находят. href возвращает null, когда человеку туда нельзя, и команда не попадает в список.

Посмотрите, чего в записи нет: клавиш. G, затем N не написано в этом файле нигде. В приложении один список горячих клавиш, и палитра ищет клавиши там по тому же ключу перевода:

function kbdOf(shortcuts: readonly ShortcutRow[], key: string): string | undefined {
  return shortcuts.find((row) => row.description === key)?.keys
}

Поэтому палитра и диалог Keyboard shortcuts не могут разойтись. Другой вариант, с клавишами, вписанными в двух местах, работает до того дня, когда одно из мест поменяется. Диалог к тому же читает тот же реестр и показывает каждую команду со словами, которые её находят.

Каждый вариант несёт выбор — маленький объект вроде { kind: "quick-create", entity, title }. Приложение выполняет его той же функцией, которую вызывают его кнопки. У палитры никогда не вырастает вторая реализация «создать заметку», которая уплывает от настоящей.

Раз функция чистая, её дёшево тестировать: никакого браузера, только состояние на входе и строки на выходе. Тесты читаются как список возможностей, например «put Go to Notes first for notse and заметки» и «keep each command the server must run listed offline, dimmed with why, and dim none online». Они лежат в palette-commands.test.ts.

В админке та же палитра. Её команды — второй список на 268 строк, а всё остальное общее.

Как продукту добавить свои записи?

Seed — стартовый шаблон, поэтому палитра должна находить то, о чём я никогда не слышал: ваши счета, контакты, проекты. Продукт передаёт их как записи:

export interface PaletteRecord {
  /** Unique within its source. */
  id: string
  /** What the palette lists and matches, in the person's language. */
  label: string
  /** The row's second line, such as an amount or a date. It is shown, not matched. */
  detail?: string
  /** Other words that find it, such as a number or an old name. */
  aliases?: readonly string[]
  /** The page a pick opens, as a page command does. */
  href: string
}

Источник — это заголовок плюс функция, которая возвращает записи, лежащие на устройстве сейчас (search-palette.tsx). Они сравниваются на устройстве тем же механизмом, что и команды, так что счёт бесплатно получает прощение опечаток и раскладки, с сетью или без. Одна оговорка: функция вызывается на каждое нажатие, поэтому должна отвечать из памяти и возвращать те же объекты, пока ничего не изменилось. Сравнение готовит каждый объект один раз и переиспользует эту работу.

Попробуйте её сломать

Откройте живое демо и нажмите «Try it now». Вы получите гостевой аккаунт с примерами заметок. Дальше:

  1. Нажмите Ctrl+K (⌘K на Mac) и наберите notse, потом ntvf.
  2. Наберите light, нажмите Enter, потом dark, Enter.
  3. Наберите заголовок, которого ещё ни у кого нет, и нажмите Ctrl+Enter.
  4. Отключите сеть в инструментах разработчика браузера и поищите эту заметку с опечаткой.

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

Следующий пост — на почту

Короткое письмо, когда выходит новый пост или что-то запускается. Подписка подтверждается один раз по почте, отписаться можно в один клик.

Все посты