PlHotKeys

키보드 키 하나, 조합, 또는 키보드에 놓인 그대로의 이동 키 네 개입니다. Mod는 Mac에서는 ⌘로, 그 밖에서는 Ctrl로 해석됩니다.

React

import { PlHotKeys } from 'plass-ui';

<PlHotKeys keys="Mod+K" />;
<PlHotKeys cluster={{ up: 'W', left: 'A', down: 'S', right: 'D' }} />;

import 'package:plass_ui/plass_ui.dart';

const PlHotKeys(keys: 'Mod+K');
const PlHotKeys(cluster: PlHotKeysCluster(up: 'W', left: 'A', down: 'S', right: 'D'));

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'glass' | 'ghost'	'glass'	키캡의 재질. glass는 인쇄된 매뉴얼의 그 헤어라인 상자이고, 기본값입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	캡의 크기. 컨트롤 사다리에서 한 단계 내려옵니다 — 캡은 문장 속 토큰이지 줄이 기준선을 맞추는 컨트롤이 아닙니다
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	'default' | 'compact'	'compact'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 기본값 0 — 캡에는 이미 아래쪽 립이 있고, 페이지에서 띄우기까지 하면 깊이 신호가 하나 많습니다
keys	string | string[]	—	키 목록. 문자열은 `+`로 쪼갭니다 ('Mod+Shift+P'). 키 자체가 `+`인 단축키는 배열 형태로 주세요
cluster	{ up, left, down, right }	—	네 개의 이동 키를 인라인 조합 대신 뒤집힌 T로 그립니다 — WASD나 방향키. keys보다 우선합니다
os	'auto' | 'mac' | 'windows' | 'linux'	'auto'	어느 키보드 기준으로 modifier 이름을 붙일지. auto는 브라우저에 묻습니다
separator	ReactNode	—	키 사이에 놓이는 것. 생략하면 플랫폼 관례를 따릅니다 — Windows/Linux는 +, macOS는 아무것도 없음

Prop	타입	기본값	설명
keys	Object?	—	키들. + 로 나뉘는 String이거나, 키 자체가 +인 단축키를 위한 List<String>입니다. Dart에 union이 없어 Object입니다
cluster	PlHotKeysCluster?	—	네 개의 이동 키를 인라인 조합 대신 뒤집힌 T로 그립니다 — WASD나 방향키. keys보다 우선합니다
os	PlHotKeysOS	PlHotKeysOS.auto	어느 키보드 기준으로 modifier 이름을 붙일지. auto는 브라우저에 묻습니다
separator	Widget?	—	키 사이에 놓이는 것. 생략하면 플랫폼 관례를 따릅니다 — Windows/Linux는 +, macOS는 아무것도 없음
variant공통	PlassVariant	PlassVariant.glass	캡의 재질
size공통	PlassSize	PlassSize.md	캡의 크기. PlHotKeys와 같은 한 단계 아래 사다리를 씁니다
color공통	PlassColor	PlassColor.secondary	의미론적 색 역할
density공통	PlassDensity	PlassDensity.compact	캡의 좌우 여백
elevation공통	int	0	그림자 깊이. 0이 기본입니다 — 키캡에는 이미 립이 있고, 페이지에서 띄우기까지 하면 깊이 단서가 하나 많습니다

네이티브 <span> 속성은 그대로 전달됩니다. color는 위 표의 color와 충돌해서, children은 키가 keys이기 때문에 제외됩니다.

keys의 타입은 Object?인데, Dart에 없는 union을 쓰는 방법입니다. +로 나뉘는 String이거나, 키 자체가 +인 단축키를 위한 List<String>입니다.

PlKbd

Prop	타입	기본값	설명
variant공통	'solid' | 'glass' | 'ghost'	'glass'	캡의 재질
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	캡의 크기. PlHotKeys와 같은 한 단계 아래 사다리를 씁니다
density공통	'default' | 'compact'	'compact'	캡의 좌우 여백
children	ReactNode	—	캡에 인쇄되는 것

Prop	타입	기본값	설명
child *	Widget	—	캡에 인쇄된 것
variant공통	PlassVariant	PlassVariant.glass	캡의 재질
size공통	PlassSize	PlassSize.md	캡의 크기. PlHotKeys와 같은 한 단계 아래 사다리를 씁니다
color공통	PlassColor	PlassColor.secondary	의미론적 색 역할
density공통	PlassDensity	PlassDensity.compact	캡의 좌우 여백
elevation공통	int	0	그림자 깊이. 0이 기본입니다 — 키캡에는 이미 립이 있고, 페이지에서 띄우기까지 하면 깊이 단서가 하나 많습니다
semanticLabel	String?	—	인쇄된 글자 대신 스크린 리더가 읽을 이름. ⌘는 "place of interest sign"으로 읽히는데, 그것은 아무도 가지고 있지 않은 키입니다

PlKbd는 캡 하나입니다. 이 컴포넌트가 그리지 않는 배치(숫자 키패드, 기능키 줄)를 단축키 줄과 같은 물건으로 직접 조립할 수 있도록 export합니다.

라이브러리 전체에서 공유 축(variant size color density elevation)이 뜻하는 바는 prop 규칙에 있습니다.

Examples

Mod, 그리고 os

Mod는 나머지가 존재하는 이유입니다. 철자만이 아니라 뜻이 플랫폼에 따라 달라지는 유일한 토큰으로, 단축키가 기반으로 삼는 modifier입니다. Mac에서는 Command, 그 밖에서는 Control. Ctrl+K라고 쓴 페이지는 모든 Mac 독자에게 틀렸고, ⌘K라고 쓴 페이지는 나머지 모두에게 틀렸습니다.

os의 기본값은 auto이고, 플랫폼에 묻습니다. 플랫폼을 명시하는 것은 페이지가 그래야 할 때뿐입니다: Windows 빌드를 설명하는 지원 문서, 둘을 비교하는 표.

auto는 defaultTargetPlatform을 읽으므로, 테스트나 미리보기의 debugDefaultTargetPlatformOverride가 그것을 옮깁니다. Android와 Fuchsia는 Linux 표기로 해석되는데, 둘 중 어느 쪽에 붙는 물리 키보드든 그렇게 인쇄되어 있기 때문입니다.

별칭은 전부 받습니다. Cmd, Command, Meta, Super는 한 키가 이미 있는 이름들이고, 그중 하나만 받는 컴포넌트는 모든 호출자가 매번 찾아봐야 하는 컴포넌트입니다.

React

import { PlHotKeys } from 'plass-ui';

export default function HotKeysOs() {
  return (
    <div className="flex flex-col gap-3 text-(--plass-fg)">
      <p className="flex items-center gap-2">
        <span className="w-20 text-xs text-(--plass-muted-fg)">auto</span>
        <PlHotKeys keys="Mod+Shift+P" />
      </p>
      <p className="flex items-center gap-2">
        <span className="w-20 text-xs text-(--plass-muted-fg)">mac</span>
        <PlHotKeys keys="Mod+Shift+P" os="mac" />
      </p>
      <p className="flex items-center gap-2">
        <span className="w-20 text-xs text-(--plass-muted-fg)">windows</span>
        <PlHotKeys keys="Mod+Shift+P" os="windows" />
      </p>
      <p className="flex items-center gap-2">
        <span className="w-20 text-xs text-(--plass-muted-fg)">linux</span>
        <PlHotKeys keys="Mod+Shift+P" os="linux" />
      </p>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class HotKeysOs extends StatelessWidget {
  const HotKeysOs({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      spacing: 12,
      children: <Widget>[
        for (final os in PlHotKeysOS.values)
          Row(
            mainAxisSize: MainAxisSize.min,
            spacing: 8,
            children: <Widget>[
              SizedBox(width: 80, child: PlTypography(os.name, level: PlTypographyLevel.caption)),
              PlHotKeys(keys: 'Mod+Shift+P', os: os),
            ],
          ),
      ],
    );
  }
}

variant

기본값은 glass입니다. 헤어라인 상자이고, 인쇄된 매뉴얼에서 키캡이 언제나 그렇게 생겼습니다. 셋 다 아래에 2px 립을 답니다. 라이브러리에서 표면 바로 아래에 각진 그림자가 붙는 유일한 자리인데, 그것이 "누르는 키"를 뜻하는 표시이기 때문입니다. 키의 그림은 키처럼 생겨도 되지만, 컨트롤은 키 그림처럼 생기면 안 됩니다.

React

import { PlHotKeys } from 'plass-ui';

export default function HotKeysVariants() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      {(['solid', 'glass', 'ghost'] as const).map((variant) => (
        <PlHotKeys key={variant} variant={variant} keys="Mod+K" />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class HotKeysVariants extends StatelessWidget {
  const HotKeysVariants({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 16,
      runSpacing: 16,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        for (final variant in PlassVariant.values) PlHotKeys(variant: variant, keys: 'Mod+K'),
      ],
    );
  }
}

cluster

이동 키 네 개를 뒤집힌 T로 그립니다. keys의 레이아웃 옵션이 아니라 자기 prop인 이유는 둘이 서로 다른 물건이기 때문입니다. 조합은 함께 누르는 키들이고, cluster는 하나씩 누르는 키 넷인데 키보드 위의 배치 자체가 핵심입니다.

React

import { PlHotKeys } from 'plass-ui';

export default function HotKeysCluster() {
  return (
    <div className="flex flex-wrap items-end gap-8">
      <PlHotKeys cluster={{ up: 'W', left: 'A', down: 'S', right: 'D' }} />
      <PlHotKeys cluster={{ up: '↑', left: '←', down: '↓', right: '→' }} />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class HotKeysCluster extends StatelessWidget {
  const HotKeysCluster({super.key});

  @override
  Widget build(BuildContext context) {
    return const Wrap(
      spacing: 32,
      runSpacing: 32,
      crossAxisAlignment: WrapCrossAlignment.end,
      children: <Widget>[
        PlHotKeys(
          cluster: PlHotKeysCluster(up: 'W', left: 'A', down: 'S', right: 'D'),
        ),
        PlHotKeys(
          cluster: PlHotKeysCluster(up: '↑', left: '←', down: '↓', right: '→'),
        ),
      ],
    );
  }
}

size

캡은 컨트롤 사다리에서 한 단계 내려옵니다. md 캡은 40px이 아니라 32px입니다. 캡은 문장 속 토큰이지, 줄이 기준선을 맞추는 컨트롤이 아닙니다.

React

import { PlHotKeys } from 'plass-ui';

export default function HotKeysSizes() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <PlHotKeys key={size} size={size} keys="Mod+K" />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class HotKeysSizes extends StatelessWidget {
  const HotKeysSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 16,
      runSpacing: 16,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[for (final size in PlassSize.values) PlHotKeys(size: size, keys: 'Mod+K')],
    );
  }
}

목록 안에서

React

import { PlHotKeys, PlTable, type PlTableColumn } from 'plass-ui';

interface Row {
  action: string;
  keys: string;
}

const columns: PlTableColumn<Row>[] = [
  { key: 'action', header: 'Action' },
  {
    key: 'keys',
    header: 'Shortcut',
    align: 'end',
    render: (row) => <PlHotKeys size="sm" keys={row.keys} />
  }
];

const rows: Row[] = [
  { action: 'Command palette', keys: 'Mod+K' },
  { action: 'Save', keys: 'Mod+S' },
  { action: 'Find in page', keys: 'Mod+F' },
  { action: 'Close the tab', keys: 'Mod+W' }
];

export default function HotKeysList() {
  return <PlTable size="sm" columns={columns} rows={rows} caption="Keyboard shortcuts" />;
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class Shortcut {
  const Shortcut(this.action, this.keys);

  final String action;
  final String keys;
}

const List<Shortcut> _rows = <Shortcut>[
  Shortcut('Command palette', 'Mod+K'),
  Shortcut('Save', 'Mod+S'),
  Shortcut('Find in page', 'Mod+F'),
  Shortcut('Close the tab', 'Mod+W'),
];

class HotKeysList extends StatelessWidget {
  const HotKeysList({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 420,
      child: PlTable<Shortcut>(
        size: PlassSize.sm,
        caption: const Text('Keyboard shortcuts'),
        rows: _rows,
        columns: <PlTableColumn<Shortcut>>[
          PlTableColumn<Shortcut>(
            header: const Text('Action'),
            cell: (Shortcut row, int index) => Text(row.action),
          ),
          PlTableColumn<Shortcut>(
            header: const Text('Shortcut'),
            align: PlassAlign.end,
            cell: (Shortcut row, int index) => PlHotKeys(keys: row.keys, size: PlassSize.sm),
          ),
        ],
      ),
    );
  }
}

Accessibility

• 각 키는 진짜 <kbd>입니다. 감싸는 것은 <span>입니다. <kbd> 안에 <kbd>를 넣는 것도 적법하고 변호할 만하지만, kbd 상자를 하나 더 두는 것은 호스트 스타일시트가 손댈 자리를 하나 더 만드는 일이고 얻는 것이 없습니다.
• ⌘는 단어가 아닙니다. 스크린리더는 이 문자를 "place of interest sign"으로 읽습니다. 글리프로 그려지는 모든 키는 화면에 보이지 않는 상자에 진짜 이름을 함께 실어서, Mac의 Mod+K가 "Command K"로 읽힙니다.
• 구분자는 aria-hidden이라, 단축키가 "Ctrl plus K"가 아니라 키들로 읽힙니다.
• 플랫폼은 useSyncExternalStore로 결정합니다. 서버의 답과 브라우저의 답이 다른 것이 의도된 일이라고 React에 알려 줄 수 있는 유일한 API입니다. 서버 렌더링된 페이지는 Ctrl로 hydrate하고 Mac에서는 ⌘로 다시 렌더링되며, hydration mismatch 경고가 남지 않습니다.
• 이 컴포넌트는 단축키를 보여 줄 뿐 바인딩하지 않습니다. 키를 눌렀을 때 무슨 일이 일어나는지는 호출하는 쪽의 몫입니다.

• ⌘는 단어가 아닙니다. 스크린리더는 이 문자를 "place of interest sign"으로 읽습니다. 글리프로 그려지는 키는 대신 진짜 이름으로 알려지므로, Mac의 Mod+K가 "Command K"로 읽힙니다.
• 구분자는 semantics에서 제외되므로, 단축키가 "Ctrl plus K"가 아니라 키들로 읽힙니다.
• 어긋날 hydration이 없습니다. 플랫폼은 빌드 시점에 알 수 있고, 그려지는 캡은 처음부터 맞는 것 하나뿐입니다.
• 이 컴포넌트는 단축키를 보여 줄 뿐 바인딩하지 않습니다. 바인딩은 직접 두는 Shortcuts 위젯의 일이고, 키를 눌렀을 때 무슨 일이 일어나는지는 호출하는 쪽의 몫입니다.

React 빌드와 다른 점

React	Flutter	이유
진짜 <kbd>	그려진 캡	Flutter에는 kbd가 없습니다. 그 요소가 사 주던 것("이 글자들은 키다")은 글리프 키가 알리는 이름이 대신 나릅니다.
useSyncExternalStore	defaultTargetPlatform	맞춰야 할 서버 렌더링이 없습니다. 플랫폼은 첫 프레임 전에 이미 알려져 있습니다.
나머지 전부에 os="linux"	Android와 Fuchsia도	둘 중 어느 쪽에 붙는 물리 키보드든 Linux처럼 인쇄되어 있습니다.
string | string[]인 keys	Object?	Dart에는 union 타입이 없습니다. +로 나누는 형태와 목록 형태는 둘 다 그대로입니다.
className, style	—	전달할 클래스 목록도 style 속성도 없습니다.