a11y-lint 0.13.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c17375bf978e252c281fec08a28a33d0fc22642e49d8aeb5af721454dc967f1
-  data.tar.gz: 9c89ac25d4163cb4807b31c396114bac42a153ecd7309effb4c77fd19c292c91
+  metadata.gz: 17ce590d5fc702bdcf3feb01606767c2aaa0938ca6a40b3f456737d7e9f519f2
+  data.tar.gz: b1ec19b360ccbc592fd42a9848cfdb351b924f3752b3041afa063f64bfd3e380
 SHA512:
-  metadata.gz: 637000bab2f93eacb3a7a799a22e8844c450f7a0da6226cada99866c57accc4bb60a4dfc36bbf7355fa35aaaf155a88bf593caef26c159d8451b0053b83f5105
-  data.tar.gz: ae04ef4e64f360df93fae63aaa502f08462958f29c3fa5e1f9afe89b263dd0d1a8ec2f0212e35507bb30ddfab7804ae50f88e9278b3e565ca591c889beb739dd
+  metadata.gz: fa1db2cd985c446515c75808512e3663859af93d254949e51fb3638e0ee1fe7cf2172a55686f66b937476e8739a9f24910b8662ef03e285445dfab9079983be3
+  data.tar.gz: 045c3ec7a7e4442a47517020aa2cf3da15496a3e304a1768e8e067d7767f2cd0693db025711f25c05e02736c6d3f0095378e9dfb68ed1a3b19ebcb3e8232a49e

data/.claude/commands/task.md

@@ -0,0 +1,37 @@
+---
+description: Capture a free-form idea as a GitHub issue in the current repo
+argument-hint: <idea>
+allowed-tools: Bash(gh issue create:*), Bash(gh repo view:*), Bash(grep:*), Bash(rg:*), Bash(ls:*), Bash(find:*), Read, Glob, Grep
+---
+
+Take the free-form idea below and turn it into a well-formed GitHub issue in the current repo.
+
+Idea: $ARGUMENTS
+
+## What to do
+
+1. **Refine** the idea into:
+   - A clear **title** (≤ ~70 chars, sentence case, no trailing period)
+   - A **body** with these sections (omit any that don't apply):
+     - **Problem / idea** — restate the idea clearly in 1–3 sentences
+     - **Proposed approach** — only include if the approach is obvious from the idea
+     - **Files likely involved** — only include if you can quickly identify them from the repo (e.g. a new rule idea should point at the right WCAG principle directory under `lib/a11y/lint/rules/`)
+
+2. **Clarify only if necessary** — one round, max. Voice input drops context, but too many questions defeat frictionless capture. Skip clarification when the idea is unambiguous. Typical clarifications: bug vs. feature, which rule/file, which template pipeline (Slim/ERB/Phlex).
+
+3. **Create the issue** with `gh issue create --title "..." --body "$(cat <<'EOF' ... EOF)"` against the current repo. Do **not** pass `--repo`. Do **not** add labels.
+
+4. **Return the issue URL** that `gh issue create` prints. Keep your final reply to one line — just the URL (and a one-line summary if helpful).
+
+## Out of scope
+
+- Auto-suggesting labels
+- Cross-repo support
+- Duplicate detection / linking related issues
+- Editing or closing existing issues
+
+## Style notes
+
+- Bias toward **fast capture** over thoroughness — the issue can always be edited on GitHub.
+- Don't pad the body with boilerplate. If "Proposed approach" or "Files likely involved" isn't obvious, leave it out.
+- Match the tone of recent issues in this repo if you can quickly check one.

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-05-03
+
+### Fixed
+
+- `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` no longer report Phlex `a`/`button` tags whose accessible text comes from a phlex-rails value helper (`t`, `translate`, `l`, `localize`, `pluralize`, `truncate`, the `number_to_*` / `number_with_*` helpers, `highlight`, `excerpt`) or Phlex's built-in `text`. Previously only `plain` was recognized
+
+## [0.14.0] - 2026-04-28
+
+### Changed
+
+- **Breaking:** `SimpleFormSelectMissingAccessibleName` is now `SimpleFormInputMissingAccessibleName` and flags any Simple Form `form.input` with `label: false`/`label: ""` that has no `aria-label` or `aria-labelledby` in `input_html`, regardless of input type (WCAG 4.1.2). `as: :hidden` is skipped. Projects that pinned the rule by name in `.a11y-lint.yml` need to update the key
+
 ## [0.13.0] - 2026-04-28
 
 ### Added

data/docs/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to the a11y-lint docs site
+
+## Authoring rule reference pages
+
+Rule pages live in `src/rules/`, one Markdown file per WCAG concept. Each rule class is an anchor section within that page.
+
+### Showing example code in multiple template languages
+
+a11y-lint supports ERB, Slim, and Phlex. When a rule page shows example code, render it through the `Shared::CodeTabs` component so all three pipelines collapse into one tabbed block instead of three stacked code blocks.
+
+ERB is required and is the default tab. Slim and Phlex are optional — omit either kwarg and the tab won't render.
+
+```erb
+<%= render Shared::CodeTabs.new(
+  erb: <<~ERB,
+    <img src="hero.jpg" alt="Team celebrating after a product launch">
+  ERB
+  slim: <<~SLIM,
+    img src="hero.jpg" alt="Team celebrating after a product launch"
+  SLIM
+  phlex: <<~PHLEX,
+    img(src: "hero.jpg", alt: "Team celebrating after a product launch")
+  PHLEX
+) %>
+```
+
+The component takes care of:
+
+- Rouge syntax highlighting per tab (using the `erb`, `slim`, and `ruby` lexers).
+- WAI-ARIA tab pattern: `role="tablist"` / `role="tab"` / `role="tabpanel"` with full `aria-*` wiring.
+- Keyboard navigation: Left/Right arrows move between tabs, Home/End jump to the first/last tab, Enter/Space activate, Tab moves into the panel.
+- A no-JavaScript fallback that shows the ERB panel only.
+- `prefers-reduced-motion`.
+
+Multiple instances on the same page get unique IDs automatically.

data/docs/src/_components/shared/code_tabs.css

@@ -0,0 +1,57 @@
+.code-tabs {
+  margin: 1.5rem 0;
+}
+
+.code-tabs__tablist {
+  display: none;
+  gap: 0.25rem;
+  border-bottom: 1px solid #ddd;
+}
+
+.code-tabs.is-enhanced .code-tabs__tablist {
+  display: flex;
+}
+
+.code-tabs__tab {
+  background: transparent;
+  border: 1px solid transparent;
+  border-bottom: none;
+  border-radius: 4px 4px 0 0;
+  padding: 0.5rem 1rem;
+  font: inherit;
+  font-weight: 600;
+  color: var(--body-color);
+  cursor: pointer;
+  margin-bottom: -1px;
+}
+
+.code-tabs__tab[aria-selected="true"] {
+  background: white;
+  border-color: #ddd;
+  color: var(--heading-color);
+}
+
+.code-tabs__tab:focus-visible,
+.code-tabs__panel:focus-visible {
+  outline: 2px solid var(--action-color);
+  outline-offset: 2px;
+}
+
+.code-tabs__panel {
+  border: 1px solid #ddd;
+  border-radius: 0 4px 4px 4px;
+}
+
+.code-tabs.is-enhanced .code-tabs__panel {
+  border-top-left-radius: 0;
+}
+
+.code-tabs__panel pre {
+  margin: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .code-tabs__tab {
+    transition: none;
+  }
+}

data/docs/src/_components/shared/code_tabs.erb

@@ -0,0 +1,30 @@
+<div class="code-tabs">
+  <div class="code-tabs__tablist" role="tablist" aria-label="Template language">
+    <% tabs.each_with_index do |tab, i| %>
+      <button
+        type="button"
+        role="tab"
+        id="<%= tab_id(tab[:key]) %>"
+        aria-controls="<%= panel_id(tab[:key]) %>"
+        aria-selected="<%= i.zero? %>"
+        tabindex="<%= i.zero? ? 0 : -1 %>"
+        class="code-tabs__tab"
+      >
+        <%= tab[:label] %>
+      </button>
+    <% end %>
+  </div>
+
+  <% tabs.each_with_index do |tab, i| %>
+    <div
+      role="tabpanel"
+      id="<%= panel_id(tab[:key]) %>"
+      aria-labelledby="<%= tab_id(tab[:key]) %>"
+      class="code-tabs__panel"
+      tabindex="0"
+      <%= "hidden" unless i.zero? %>
+    >
+      <%= raw highlighted(tab[:key], tab[:lexer]) %>
+    </div>
+  <% end %>
+</div>

data/docs/src/_components/shared/code_tabs.js

@@ -0,0 +1,54 @@
+function initCodeTabs(root) {
+  if (root.classList.contains("is-enhanced")) return
+
+  const tabs = Array.from(root.querySelectorAll('[role="tab"]'))
+  const panels = Array.from(root.querySelectorAll('[role="tabpanel"]'))
+  if (tabs.length === 0) return
+
+  root.classList.add("is-enhanced")
+
+  function activate(index, { focus = true } = {}) {
+    tabs.forEach((tab, i) => {
+      const selected = i === index
+      tab.setAttribute("aria-selected", String(selected))
+      tab.setAttribute("tabindex", selected ? "0" : "-1")
+      panels[i].hidden = !selected
+    })
+    if (focus) tabs[index].focus()
+  }
+
+  tabs.forEach((tab, i) => {
+    tab.addEventListener("click", () => activate(i))
+    tab.addEventListener("keydown", (event) => {
+      let next = null
+      switch (event.key) {
+        case "ArrowRight":
+          next = (i + 1) % tabs.length
+          break
+        case "ArrowLeft":
+          next = (i - 1 + tabs.length) % tabs.length
+          break
+        case "Home":
+          next = 0
+          break
+        case "End":
+          next = tabs.length - 1
+          break
+        default:
+          return
+      }
+      event.preventDefault()
+      activate(next)
+    })
+  })
+}
+
+function initAllCodeTabs() {
+  document.querySelectorAll(".code-tabs").forEach(initCodeTabs)
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", initAllCodeTabs)
+} else {
+  initAllCodeTabs()
+}

data/docs/src/_components/shared/code_tabs.rb

@@ -0,0 +1,36 @@
+require "rouge"
+require "securerandom"
+
+class Shared::CodeTabs < Bridgetown::Component
+  TABS = [
+    { key: :erb,   label: "ERB",   lexer: "erb" },
+    { key: :slim,  label: "Slim",  lexer: "slim" },
+    { key: :phlex, label: "Phlex", lexer: "ruby" }
+  ].freeze
+
+  attr_reader :id
+
+  def initialize(erb:, slim: nil, phlex: nil)
+    @samples = { erb: erb, slim: slim, phlex: phlex }
+    @id = "code-tabs-#{SecureRandom.hex(4)}"
+  end
+
+  def tabs
+    TABS.select { |tab| @samples[tab[:key]] }
+  end
+
+  def tab_id(key)
+    "#{id}-tab-#{key}"
+  end
+
+  def panel_id(key)
+    "#{id}-panel-#{key}"
+  end
+
+  def highlighted(key, lexer_name)
+    formatter = Rouge::Formatters::HTML.new
+    lexer = Rouge::Lexer.find(lexer_name) || Rouge::Lexers::PlainText.new
+    inner = formatter.format(lexer.lex(@samples[key].to_s))
+    %(<pre class="highlight"><code>#{inner}</code></pre>)
+  end
+end

data/docs/src/rules/form-controls-need-accessible-names.md

@@ -29,15 +29,19 @@ In Simple Form, both go inside `input_html`:
 
 A placeholder is **not** a label. It disappears as soon as the user types, browsers don't reliably expose it as the accessible name, and it fails users who rely on the prompt staying visible while they fill the field.
 
-## SimpleFormSelectMissingAccessibleName
-{:#simple-form-select-missing-accessible-name}
+## SimpleFormInputMissingAccessibleName
+{:#simple-form-input-missing-accessible-name}
 
-Applies to: Simple Form `form.input` calls that render a `<select>` — either `collection:` is passed, or `as: :select` is set — when `label: false` or `label: ""` hides the visible label.
+Applies to: Simple Form `form.input` calls with `label: false` or `label: ""` — regardless of input type. `as: :hidden` is skipped, since hidden inputs don't render a visible control.
 
 The rule passes when `input_html` provides `aria-label` or `aria-labelledby`. Both hash and string keys are accepted (`aria: { label: "..." }` and `"aria-label" => "..."`).
 
 ### Bad
 
+```erb
+<%%= form.input :name, label: false %>
+```
+
 ```erb
 <%%= form.input :sort_by, collection: opts, label: false %>
 ```
@@ -48,17 +52,18 @@ The rule passes when `input_html` provides `aria-label` or `aria-labelledby`. Bo
 
 ### Good
 
-Render a visible label by removing `label: false`:
+Render a visible label by removing `label: false` and letting Simple Form generate one from the attribute name, or by passing an explicit string:
 
 ```erb
+<%%= form.input :name %>
 <%%= form.input :sort_by, collection: opts, label: "Sort by" %>
 ```
 
 Or, when there's no visible label, supply `aria-label`:
 
 ```erb
-<%%= form.input :sort_by, collection: opts, label: false,
-      input_html: { aria: { label: "Sort by" } } %>
+<%%= form.input :name, label: false,
+      input_html: { aria: { label: "Name" } } %>
 ```
 
 Or `aria-labelledby` pointing to existing visible text:
@@ -69,19 +74,25 @@ Or `aria-labelledby` pointing to existing visible text:
       input_html: { aria: { labelledby: "sort-label" } } %>
 ```
 
+`as: :hidden` doesn't render a visible control, so it's exempt:
+
+```erb
+<%%= form.input :secret, as: :hidden, label: false %>
+```
+
 ### Slim equivalent
 
 ```slim
-= form.input :sort_by, collection: opts, label: false, input_html: { aria: { label: "Sort by" } }
+= form.input :name, label: false, input_html: { aria: { label: "Name" } }
 ```
 
 ## What this rule doesn't catch
 
 This rule has a deliberately narrow scope. Things it doesn't flag:
 
-- **Plain `<select>` elements.** The rule targets Simple Form's `form.input` helper. A bare `<select>` with no associated `<label>` is not reported.
+- **Plain HTML form controls.** The rule targets Simple Form's `form.input` helper. A bare `<input>`, `<select>`, or `<textarea>` with no associated `<label>` is not reported.
 - **Other Simple Form helpers.** `form.select`, `form.association`, and similar helpers aren't checked — only `form.input`.
-- **Other input types.** `form.input` rendering as text, email, checkbox, radio, etc. is not checked. Selects are flagged because the `label: false` + missing aria pattern is unusually common for sort and filter dropdowns.
+- **Inputs without `label: false`.** Simple Form auto-generates a label from the attribute name, so `form.input :name` is treated as having a visible label. The rule only kicks in once the label is explicitly suppressed.
 - **Phlex views.** The rule is a no-op in Phlex by design. The Phlex pipeline only walks receiverless calls, so `form.input(...)` isn't surfaced as a candidate node. Simple Form code embedded inside a Phlex component won't be checked.
 - **Bad accessible name content.** `aria: { label: "" }` will pass the rule check above (an empty aria-label is its own problem, but not this rule's). `aria: { label: "select" }` will pass. The linter checks that an aria attribute is present, not that the value is useful.
 - **Dynamic accessible names.** `aria: { label: variable }` satisfies the rule even if `variable` is `nil` at runtime.

data/docs/src/rules/images-need-alt-text.md

@@ -67,15 +67,31 @@ Applies to: HTML `<img>` elements.
 
 ### Bad
 
-```erb
-<img src="hero.jpg">
-```
+<%= render Shared::CodeTabs.new(
+  erb: <<~ERB,
+    <img src="hero.jpg">
+  ERB
+  slim: <<~SLIM,
+    img src="hero.jpg"
+  SLIM
+  phlex: <<~PHLEX,
+    img(src: "hero.jpg")
+  PHLEX
+) %>
 
 ### Good
 
-```erb
-<img src="hero.jpg" alt="Team celebrating after a product launch">
-```
+<%= render Shared::CodeTabs.new(
+  erb: <<~ERB,
+    <img src="hero.jpg" alt="Team celebrating after a product launch">
+  ERB
+  slim: <<~SLIM,
+    img src="hero.jpg" alt="Team celebrating after a product launch"
+  SLIM
+  phlex: <<~PHLEX,
+    img(src: "hero.jpg", alt: "Team celebrating after a product launch")
+  PHLEX
+) %>
 
 For a decorative image, use an empty `alt` so assistive tech skips it:
 

data/lib/a11y/lint/phlex_runner.rb

@@ -9,6 +9,19 @@ module A11y
     class PhlexRunner
       PHLEX_PATTERN = /\bdef\s+view_template\b/
 
+      # Phlex auto-emits the return value of these calls into the document:
+      # `plain` / `text` are built-in; the rest are registered as value
+      # helpers by phlex-rails via `register_value_helper`.
+      TEXT_CALLS = %w[
+        plain text
+        t translate l localize
+        pluralize truncate
+        number_to_currency number_to_human number_to_human_size
+        number_to_percentage number_to_phone
+        number_with_delimiter number_with_precision
+        highlight excerpt
+      ].to_set.freeze
+
       def initialize(rules = nil, configuration: Configuration.new)
         @rules = rules || configuration.enabled_rules
         @configuration = configuration
@@ -161,7 +174,7 @@ module A11y
       end
 
       def text_call?(node)
-        receiverless_call?(node) && node.name.to_s == "plain"
+        receiverless_call?(node) && TEXT_CALLS.include?(node.name.to_s)
       end
 
       def receiverless_call?(node)

data/lib/a11y/lint/rules/robust/{simple_form_select_missing_accessible_name.rb → simple_form_input_missing_accessible_name.rb}

@@ -3,11 +3,11 @@
 module A11y
   module Lint
     module Rules
-      # Checks that Simple Form `form.input` calls rendering a select
-      # (via `collection:` or `as: :select`) with `label: false` /
+      # Checks that Simple Form `form.input` calls with `label: false` /
       # `label: ""` provide an accessible name through `input_html:`
-      # `aria-label` or `aria-labelledby` (WCAG 4.1.2).
-      class SimpleFormSelectMissingAccessibleName < NodeRule
+      # `aria-label` or `aria-labelledby` (WCAG 4.1.2). Skips
+      # `as: :hidden`, which doesn't render a visible control.
+      class SimpleFormInputMissingAccessibleName < NodeRule
         def check
           return if no_offense?
 
@@ -18,14 +18,13 @@ module A11y
 
         def no_offense?
           !helper_call ||
-            !select_like? ||
             !helper_call.label_hidden? ||
+            hidden_input? ||
             aria_label_in_input_html?
         end
 
-        def select_like?
-          helper_call.keyword?(:collection) ||
-            helper_call.keyword_symbol?(:as, :select)
+        def hidden_input?
+          helper_call.keyword_symbol?(:as, :hidden)
         end
 
         def aria_label_in_input_html?
@@ -53,7 +52,7 @@ module A11y
 
         def offense_message
           <<~MSG.strip
-            form.input select missing an accessible name \
+            form.input missing an accessible name \
             requires aria-label or aria-labelledby in input_html (WCAG 4.1.2)
           MSG
         end

data/lib/a11y/lint/version.rb

@@ -2,6 +2,6 @@
 
 module A11y
   module Lint
-    VERSION = "0.13.0"
+    VERSION = "0.14.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: a11y-lint
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.1
 platform: ruby
 authors:
 - Abdullah Hashim
@@ -45,6 +45,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/commands/task.md"
 - ".claude/rules/testing.md"
 - ".rubocop.yml"
 - CHANGELOG.md
@@ -55,6 +56,7 @@ files:
 - Rakefile
 - docs/.gitignore
 - docs/.ruby-version
+- docs/CONTRIBUTING.md
 - docs/Gemfile
 - docs/Gemfile.lock
 - docs/README.md
@@ -80,6 +82,10 @@ files:
 - docs/src/404.html
 - docs/src/500.html
 - docs/src/CNAME
+- docs/src/_components/shared/code_tabs.css
+- docs/src/_components/shared/code_tabs.erb
+- docs/src/_components/shared/code_tabs.js
+- docs/src/_components/shared/code_tabs.rb
 - docs/src/_components/shared/navbar.erb
 - docs/src/_components/shared/navbar.rb
 - docs/src/_data/site_metadata.yml
@@ -124,7 +130,7 @@ files:
 - lib/a11y/lint/rules/robust/button_missing_accessible_name.rb
 - lib/a11y/lint/rules/robust/button_tag_missing_accessible_name.rb
 - lib/a11y/lint/rules/robust/link_to_missing_accessible_name.rb
-- lib/a11y/lint/rules/robust/simple_form_select_missing_accessible_name.rb
+- lib/a11y/lint/rules/robust/simple_form_input_missing_accessible_name.rb
 - lib/a11y/lint/slim_node.rb
 - lib/a11y/lint/slim_runner.rb
 - lib/a11y/lint/version.rb