Clickable

child 를 감싸 인터랙티브하게 만드는 인프라 프리미티브입니다 — 포인터 커서, 포커스 링, press 피드백 스케일, 키보드 활성화(Enter/Space)를 직접 소유합니다. Button 같은 상위 컴포넌트가 이 위에 쌓입니다. 직접 쓸 일은 드물지만, 커스텀 클릭 영역을 만들 때 raw GestureDetector 대신 사용하면 양 플랫폼 동작이 통일됩니다.

Live Preview#

class ClickableDefaultExample extends StatelessComponent {
  const ClickableDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return Clickable(
      onPressed: () {},
      child: Card(child: Text('클릭 가능한 영역').bodyMedium),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Clickable(
      onPressed: () {},
      child: Card(child: Text('클릭 가능한 영역').bodyMedium),
    );
  }
}

사용법#

Clickable(
  onPressed: () {},
  child: Card(child: Text('클릭 가능한 영역').bodyMedium),
)

빠른 오버라이드 (Chain)#

이미 만든 Clickable 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다. .radius9999처럼 Core 토큰 상수 이름과 똑같은 이름의 getter도 있습니다 — withStyle을 한 번 더 줄인 sugar로, 이름이 곧 값이라(radius9999 == CoreRadius.radius9999) 어느 컴포넌트에서 써도 뜻이 갈리지 않습니다.

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

  @override
  Widget build(BuildContext context) {
    return Clickable(
          onPressed: () {},
          child: Card(child: Text('클릭 가능한 영역').bodyMedium),
        )
        .withStyle(
          const CoreClickableStyle(
            disabledOpacity: CoreOpacity.opacity30,
            duration: Duration(milliseconds: CoreDuration.fast),
            pressDuration: Duration(milliseconds: CoreDuration.instant),
          ),
        )
        .radius16;
  }
}

class ClickableChainExample extends StatelessComponent {
  const ClickableChainExample({super.key});

  @override
  Component build(BuildContext context) {
    return Clickable(
          onPressed: () {},
          child: Card(child: Text('클릭 가능한 영역').bodyMedium),
        )
        .withStyle(
          const CoreClickableStyle(
            disabledOpacity: CoreOpacity.opacity30,
            duration: Duration(milliseconds: CoreDuration.fast),
            pressDuration: Duration(milliseconds: CoreDuration.instant),
          ),
        )
        .radius16;
  }
}

Props / Parameters#

W 는 Flutter의 Widget, Web의 Jaspr Component 입니다.

콘텐츠 · 상태#

탭 · 포인터 콜백#

롱프레스 콜백#

상태 변화 콜백#

접근성#

Flutter 전용#

Web 은 브라우저 native focus / cursor / CSS pseudo-class 로 같은 capability 를 제공합니다.

CoreClickableStyle 필드#

동작 스펙 (Behavior)#

• 콘텐츠에 기본 탭 · 키보드 활성화 · hover · 포커스 피드백을 붙이는 합성 프리미티브입니다. enabled: false 는 주 활성화와 포커스 진입을 막습니다. 자체 선택 상태를 바꾸지는 않습니다.
• 포커스된 표면의 Enter / Space는 onPressed 를 실행합니다. Web은 자식 컨트롤에서 버블된 키 이벤트를 걸러 부모를 다시 활성화하지 않습니다.
• 더블탭은 첫 클릭의 onPressed 후 두 번째 클릭을 onDoubleTap 으로 처리합니다. enableFeedback: false 는 누름 피드백을 끄며 시간은 clickableStyle.pressDuration(Duration, ms), 스케일은 단위 없는 배율입니다.
• 버튼 chrome까지 필요하면 Button, 목적지 링크이면 Link 입니다. 이미 구성한 임의 콘텐츠에 인터랙션만 붙일 때 Clickable 을 씁니다.

사용 가이드라인 (Usage Guidelines)#

✅ Do#

Clickable(
  onPressed: toggle,
  semanticsButton: false, // checkbox/switch/tab이 자기 role을 직접 붙임
  child: myCheckboxVisual,
)

❌ Don't#

// ❌ 이름 없는 버튼으로 읽힘 — child 가 텍스트를 렌더하지 않음
Clickable(onPressed: handleClose, child: Icon(LucideIcons.x))

// ✅ Web: attributes 로 aria-label / Flutter: 바깥에 Semantics 로 이름 부여
Clickable(
  onPressed: handleClose,
  attributes: {'aria-label': 'Close'}, // Web
  child: Icon(LucideIcons.x),
)

접근성 (Accessibility)#

Clickable 은 자기 자신을 버튼으로 알립니다 — 위에 쌓이는 컴포넌트가 각자 기억하지 않아도 되도록, 역할과 활성/비활성 상태를 이 레이어에서 한 번 내보냅니다.

역할#

• Flutter: Semantics(enabled: enabled, button: semanticsButton, selected: semanticsSelected). semanticsButton 은 기본 true 이고, 더 구체적인 역할을 가진 컴포넌트(checkbox / switch / tab 등)가 false 를 넘긴 뒤 자기 역할을 직접 붙입니다. 탭 활성화 시 TapSemanticEvent 도 함께 발생합니다.
• Web: 루트 <div> 에 role="button", 활성일 때 tabindex="0", 비활성일 때 aria-disabled="true", semanticsSelected 가 있으면 aria-selected. semanticsButton: false 는 role 만 내려놓고 tabindex 는 남깁니다 — 더 구체적인 컨트롤도 여전히 포커스 대상입니다. 호출자 attributes 가 마지막에 병합되므로, 감싸는 컴포넌트가 넘긴 role / tabindex 이 기본값을 덮습니다.

키보드#

그 외 키는 처리하지 않습니다 — Escape·방향키·Home/End 모두 바인딩이 없습니다.

Web 은 keydown 이 자기 노드에서 발생했을 때만 활성화합니다. 안쪽에 포커스 가능한 컨트롤이 들어 있을 때 그 컨트롤의 키 입력이 버블링돼 이중 활성화되는 것을 막기 위한 것으로, native <button> 과 같은 동작입니다.

포커스 관리#

양 플랫폼 모두 포커스 가능하며, 비활성일 때 탭 순서에서 빠집니다.

• Flutter: FocusNode 를 직접 소유하고(호출자가 focusNode 를 넘기면 그것을 사용), FocusableActionDetector(enabled:) 가 비활성 시 traversal 에서 제거합니다. 포커스 링은 FocusOutline 로 그리며 focusOutline: true 가 기본값 — false 로 끌 수 있습니다.
• Web: tabindex="0" 로 브라우저 native 포커스를 쓰고, 링은 CSS focus-visible 로 그립니다. focusin / focusout 리스너는 호출자가 onFocus 를 넘겼을 때만 붙습니다.

포커스 트랩이나 포커스 복원은 어느 쪽에도 없습니다.

스크린 리더#

버튼으로, 그리고 활성/비활성 상태와 함께 읽힙니다. 이름은 child 가 렌더한 텍스트에서 옵니다. semanticsButton: false 로 버튼 역할을 내려놓고 자기 역할을 붙이는 것이 상위 컴포넌트가 역할을 갈아끼우는 공식 경로이며, 양 플랫폼 같은 파라미터입니다 (Web 은 호출자 role 속성으로 덮어쓰는 길도 남아 있습니다).

알려진 제약#

• 자체 이름이 없습니다. child 가 렌더한 텍스트가 곧 이름이므로, 아이콘만 담은 Clickable 은 이름 없는 버튼으로 읽힙니다. 이름은 호출자가 붙여야 합니다 — Web 은 attributes 로 aria-label 을, Flutter 는 바깥에 자신의 Semantics 를 두는 방식.
• Web 은 Space 를 keydown 에서 활성화하고 key repeat 을 구분하지 않습니다. native <button>(keyup 활성화)과 달라, Space 를 누르고 있으면 반복 발생합니다.
• 비활성일 때도 시맨틱 트리에는 남아 "비활성 버튼"으로 읽힙니다 — 트리에서 제거되는 것이 아니라 상태로 표시됩니다.

전역으로 적용되는 축(동작 줄이기·고대비·색 강제 모드·최소 터치 타겟)은 전역 접근성 축에 있습니다.

크로스 플랫폼 차이점 (Platform Differences)#

Web의 일부 세부 포인터·롱프레스 필드는 선언되어도 Flutter의 Gesture 콜백처럼 모두 전달되지는 않습니다. 공통 주 클릭·키보드 활성화와 세부 제스처의 배선 결손을 구분해야 합니다.