Skip to content

feat(SidebarNavigationItem): add asChild so selected and disabled reach the link - #1317

Open
emunhoz wants to merge 5 commits into
ClickHouse:mainfrom
emunhoz:feat/sidebar-navigation-item-as-child
Open

emunhoz wants to merge 5 commits into
ClickHouse:mainfrom
emunhoz:feat/sidebar-navigation-item-as-child

Conversation

@emunhoz

@emunhoz emunhoz commented Nov 17, 2026 •

Copy link
Copy Markdown

Description

SidebarNavigationItem puts data-selected and aria-disabled on its wrapper div, so the consumer's link (passed through label) never gets either state. This adds an opt-in asChild prop, the direction suggested in the issue, so the item renders the consumer's link itself:

<SidebarNavigationItem asChild selected icon="table">
  <Link to="/tables">Tables</Link>
</SidebarNavigationItem>
  • Selected: the link gets aria-current="page". A consumer-provided aria-current wins (Radix Slot lets child props take precedence).
  • Disabled: the link gets aria-disabled="true" and tabIndex={-1}, and click (which Enter fires on a link) is prevented. This follows the existing CardHorizontal pattern (fix(a11y): add keyboard activation and button role to CardHorizontal #1269).
  • Icon: marked aria-hidden inside the link so the accessible name is "Tables", not "table Tables" (new optional iconHidden on the internal Collapsible/IconWrapper; other users of it are unchanged).
  • Focus: .wrapper:focus-visible uses the global outline token with a -2px offset because .wrapper has overflow: hidden. Same values as fix(Collapsible): show focus ring on keyboard focus of the trigger #1312.
  • Without asChild the output is unchanged. The existing label={<a/>} usage keeps working.

asChild uses @radix-ui/react-slot, which is already a dependency. No new dependency.

Links and tickets

Closes #1304

Good to know

  • Disabled link and href: the ideal markup for a disabled link is to drop href and use role="link" + aria-disabled (Scott O'Hara, "Disabling a link"). With asChild the child's props win, so the component can't remove the consumer's href/to. That's why it keeps the link out of the Tab order and prevents activation instead. Happy to change direction if you prefer an href prop that the component owns.
  • label is now optional in the type, since with asChild the link's own content is the label (JSDoc says so). I kept interface rather than a discriminated union so consumers extending SidebarNavigationItemProps don't break.
  • ref type stays HTMLDivElement even though in asChild mode the element is an <a>. Widening it to HTMLElement could break typed callback refs, so I left it as is.
  • An onClick placed directly on the child <a> still runs when disabled; navigation is still blocked.
  • Out of scope, noticed while testing: in the existing styles pointer-events: none on disabled items also hides the cursor: not-allowed. I didn't change it here.

Checklist

  • Breaking changes? (add migration notes in changesets)
  • Visual changes? (specify in changesets) Only the new focus ring on asChild links. Existing stories are unchanged.
  • Design review needed?

Contribution

  • Sufficient research before PR
  • Self-reviewed the PR
  • Manually tested the changes (when applies - visual confirmation in Storybook)
  • build and build-storybook work locally
  • Tests and Stories are aligned with the changes

Accessibility

  • Keyboard — Tab reaches enabled links with a visible ring. A disabled link is skipped by Tab, and Enter/click don't navigate.
  • Names — the link's name is its visible text ("Tables"); the decorative icon is aria-hidden.
  • Vision — colors and the focus ring come from tokens; the ring shows in light and dark.

Checked: 4.1.2 Name, Role, Value; 1.3.1 Info and Relationships; 2.1.1 Keyboard; 2.4.7 Focus Visible; 1.4.11 Non-text Contrast (light ring on the selected background ≈ 3.07:1, global token).

How:

  • Unit tests: aria-current, a consumer aria-current, Tab moving focus to the link, the ref reaching the <a>, and disabled (aria-disabled, skipped by Tab, click prevented, onClick not called).
  • Visual spec: new as-child-selected and as-child-disabled snapshots, an as-child focus case (body click, Tab, toBeFocused, screenshot) in light and dark like checkbox.spec.ts, and a check that a disabled link is skipped by Tab. Six new snapshots; the existing 12 are untouched.
  • Stories: AsChild, AsChildSelected and AsChildDisabled. I left out pseudo-state and play stories, following the review on fix(SplitButton): make the menu half a keyboard-accessible menu button #1278.
  • Ran Playwright with axe-core against Storybook in light and dark: 0 violations, no console errors.
  • yarn test:visual for Collapsible, SidebarNavigationTitle and SidebarCollapsibleItem (they share IconWrapper): passing, no snapshot updates.

Not tested: a real screen reader (VoiceOver/NVDA) and a real router Link (no router in the repo).

Screenshots

From the visual regression snapshots. Existing label={<a/>} usage (unchanged) next to asChild:

State Theme Existing (label) asChild
Selected Light Existing selected, light asChild selected, light
Selected Dark Existing selected, dark asChild selected, dark
Disabled Light Existing disabled, light asChild disabled, light
Disabled Dark Existing disabled, dark asChild disabled, dark
Keyboard focus Light (no focus ring) asChild focus ring, light
Keyboard focus Dark (no focus ring) asChild focus ring, dark

Note

Low Risk
Opt-in API with unchanged default rendering; changes are localized to sidebar navigation and shared icon accessibility, with broad test coverage.

Overview
Adds an opt-in asChild prop so consumers can pass a router Link or <a> as the item root (via Radix Slot). selected and disabled then land on the link: aria-current="page" (unless the child already sets aria-current), aria-disabled, tabIndex={-1} when disabled, and click prevention that also blocks Enter activation.

IconWrapper gains optional iconHidden so sidebar icons are decorative inside link items. Styles add text-decoration: none on the wrapper and a :focus-visible ring for keyboard focus on link-as-item markup. label becomes optional when asChild is used; default label={…} behavior is unchanged.

Stories, unit tests, and Playwright snapshots cover asChild selected, disabled, and focus states. Changeset marks a minor @clickhouse/click-ui release.

Reviewed by Cursor Bugbot for commit 0bb6575. Bugbot is set up for automated code reviews on this repo. Configure here.

…ch the link

The link now gets aria-current="page" when selected, and aria-disabled, tabIndex -1 and a click guard when disabled. Without asChild nothing changes.

Closes ClickHouse#1304
@changeset-bot

changeset-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 0bb6575

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@clickhouse/click-ui Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@emunhoz
emunhoz marked this pull request as ready for review November 18, 2026 09:29

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

Reviewed by Cursor Bugbot for commit d7284e9. Configure here.

@XOP
XOP requested a review from ariser November 19, 2026 15:30
@XOP XOP added bug Something isn't working good first issue Good for newcomers a11y Accessibility improvements labels Nov 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

a11y Accessibility improvements bug Something isn't working good first issue Good for newcomers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: SidebarNavigationItem selected and disabled state never reach the link

2 participants