managarten/docs/SVELTE_CHECK_ISSUES.md

Svelte Check - Pre-commit Enforcement

Last updated: 2024-12-15

Overview

All web apps in this monorepo are protected by pre-commit hooks that run svelte-check with --threshold warning. This ensures no a11y issues, TypeScript errors, or Svelte 5 problems can be committed.

Current Status

All main web apps pass svelte-check with 0 errors and 0 warnings:

Package	Status
@manacore/web	Clean
@clock/web	Clean
@chat/web	Clean
@manadeck/web	Clean
@calendar/web	Clean
@zitare/web	Clean
@contacts/web	Clean
@picture/web	Clean
@todo/web	Clean

How It Works

Pre-commit Hook

When you commit .svelte files, the hook automatically:

1. Detects which web apps have changes
2. Runs svelte-check --threshold warning on affected apps
3. Blocks the commit if any warnings or errors are found

# What happens on commit:
🔍 Running svelte-check on affected web apps...

━━━ Checking apps/todo/apps/web ━━━
✅ svelte-check passed for apps/todo/apps/web

✅ All svelte-checks passed!

If Check Fails

━━━ Checking apps/todo/apps/web ━━━
/path/to/file.svelte:42:3
Warn: Elements with onclick must have onkeydown handler

❌ svelte-check failed for apps/todo/apps/web

❌ svelte-check failed! Fix the issues above before committing.

You must fix the warnings before you can commit.

---

Common Warnings & How to Fix Them

1. Click Events Need Keyboard Events

Warning: a11y_click_events_have_key_events

<!-- BAD -->
<div onclick={() => doSomething()}>Click me</div>

<!-- GOOD: Add keyboard handler -->
<div
  onclick={() => doSomething()}
  onkeydown={(e) => e.key === 'Enter' && doSomething()}
  role="button"
  tabindex="0"
>
  Click me
</div>

<!-- BEST: Use semantic element -->
<button type="button" onclick={() => doSomething()}>Click me</button>

2. Non-interactive Element with Interactions

Warning: a11y_no_static_element_interactions

<!-- BAD -->
<div onclick={handleClick}>Click me</div>

<!-- GOOD: Add role and tabindex -->
<div onclick={handleClick} onkeydown={() => {}} role="button" tabindex="0">
  Click me
</div>

<!-- For modal backdrops (suppress with comment): -->
<!-- svelte-ignore a11y_no_static_element_interactions -->
<div class="backdrop" onclick={closeModal} onkeydown={() => {}}></div>

3. Buttons Need Labels

Warning: a11y_consider_explicit_label

<!-- BAD -->
<button onclick={close}>
  <svg>...</svg>
</button>

<!-- GOOD -->
<button onclick={close} aria-label="Close">
  <svg>...</svg>
</button>

4. Autofocus Warning

Warning: a11y_autofocus

<!-- Suppress if intentional (e.g., modal input): -->
<!-- svelte-ignore a11y_autofocus -->
<input type="text" autofocus />

5. Interactive Role Needs Focus

Warning: a11y_interactive_supports_focus

<!-- BAD -->
<div role="menu" onclick={toggle}>Menu</div>

<!-- GOOD -->
<div role="menu" tabindex="-1" onclick={toggle} onkeydown={() => {}}>Menu</div>

6. Nested Interactive Elements

Warning: node_invalid_placement_ssr

<!-- BAD: button inside button causes hydration issues -->
<button class="card">
  <button class="action">Delete</button>
</button>

<!-- GOOD: Use svelte-ignore if necessary -->
<!-- svelte-ignore node_invalid_placement_ssr -->
<button class="card">
  <button class="action">Delete</button>
</button>

<!-- BETTER: Restructure HTML -->
<div class="card" role="group">
  <button class="card-body">Select</button>
  <button class="action">Delete</button>
</div>

7. Svelte 5 Reactivity

Warning: non_reactive_update

<!-- BAD: Won't trigger re-renders in Svelte 5 -->
<script lang="ts">
  let count = 0;
</script>

<!-- GOOD: Use $state() -->
<script lang="ts">
  let count = $state(0);
</script>

---

Modal Pattern (Common Fix)

Most modal warnings can be fixed with this pattern:

{#if showModal}
  <!-- Backdrop: svelte-ignore for click-to-close -->
  <!-- svelte-ignore a11y_no_static_element_interactions -->
  <div
    class="modal-backdrop"
    onclick={() => (showModal = false)}
    onkeydown={(e) => e.key === 'Escape' && (showModal = false)}
    role="presentation"
  >
    <!-- Modal content: stop propagation -->
    <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
    <div
      class="modal-content"
      onclick={(e) => e.stopPropagation()}
      onkeydown={() => {}}
      role="dialog"
      aria-modal="true"
      tabindex="-1"
    >
      <!-- Modal content here -->
    </div>
  </div>
{/if}

---

Dropdown/Menu Pattern

{#if showDropdown}
  <!-- svelte-ignore a11y_no_static_element_interactions a11y_interactive_supports_focus -->
  <div
    class="dropdown"
    onclick={(e) => e.stopPropagation()}
    onkeydown={() => {}}
    role="menu"
    tabindex="-1"
  >
    <button role="menuitem" onclick={() => selectOption('a')}>Option A</button>
    <button role="menuitem" onclick={() => selectOption('b')}>Option B</button>
  </div>
{/if}

---

Running Checks Manually

# Check a specific app
pnpm --filter @todo/web exec svelte-check --threshold warning

# Check all staged files (same as pre-commit)
./scripts/svelte-check-staged.sh

# Quick check without threshold (shows all issues)
pnpm --filter @todo/web exec svelte-check

---

Bypassing Pre-commit (Emergency Only)

If you absolutely must commit without checks (e.g., WIP branch):

git commit --no-verify -m "WIP: work in progress"

Warning: This bypasses ALL pre-commit hooks. Use sparingly and fix issues before PR.

---

Files

File	Purpose
.husky/pre-commit	Runs lint-staged, type-check, and svelte-check
scripts/svelte-check-staged.sh	Detects affected apps and runs checks
docs/SVELTE_CHECK_ISSUES.md	This documentation