Skip to content

fix(dashboard): disambiguate same-basename composer tiles by widening labels (#13829) - #17403

Merged
iamwhatever merged 2 commits into
kirodotdev:mainfrom
chenmingwei23:fix/13829-composer-tile-path
Oct 7, 2026
Merged

iamwhatever merged 2 commits into
kirodotdev:mainfrom
chenmingwei23:fix/13829-composer-tile-path

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make two composer preview tiles that share a basename distinguishable by their visible label, so a sighted user — keyboard-only or not — can tell which staged file is which.

The composer preview tiles (staged attachments, pasted files, folder references)
rendered their visible label as just the basename, carrying the full path only
in title (pointer hover) and the role="group" aria-label (screen reader).
A sighted, keyboard-only user who runs no screen reader is served by neither: a
native title does not open on keyboard focus, and the aria-label is silent
without assistive tech. So two staged files named report.txt from different
directories were indistinguishable on screen.

(This is the one live finding of #13829 — Gap 1. Gaps 2 and 3 in the issue were
confirmed stale against the reworked composer paste path in the triage comment.)

Why it matters

A user who stages multiple files sharing a basename cannot tell which tile they
are about to remove, preview, or send — they must guess or hover each one. For a
keyboard-only user hover is unavailable, so it is an a11y gap; but the fix helps
every user.

Not a goal

  • Full screen-reader audit of the composer: the tiles' aria-label already
    carries the full path for assistive tech; this PR addresses the visible
    label.
  • Gaps 2 and 3 from the original issue: confirmed stale by the triage comment
    (the paste path was reworked).

What changed (motivation → approach → change)

The fix is the one this component already uses for folder chips:
buildFileLabels. It renders each tile's visible label basename-first and
widens it by parent segments only until it is unique among the staged tiles
(report.txt → src/report.txt vs docs/report.txt).

  • One buildFileLabels map is computed over all staged files — images and
    non-images together — so a pasted report.txt image and an attached
    report.txt file widen against each other too.
  • Non-image file chips now render the widened label instead of the bare
    basename.
  • Image chips (which previously showed no visible text, only a thumbnail)
    gain a visible label caption under the thumbnail only when their name
    collides with another staged file
    (the label was widened past its
    basename), so a lone pasted screenshot with a long generated name stays
    caption-free and the strip is not a row of near-identical truncated captions.
    The caption is clamped to the tile width and truncated; the full path stays in
    title/aria-label.
  • The caption lives on its own 64px-wide span; the chip wrapper keeps the base
    sizing (as wide as the wider of tile and resize pill), so a wide de/bn resize
    pill does not overflow onto the next chip.
  • Folder chips already used buildFileLabels — unchanged.
  • Windows-aware: the label normalizes \ → / only when \ is actually a
    separator (drive-rooted / UNC), reusing backslashIsSeparator from
    pathBasename, so a POSIX file name containing a literal \ (/tmp/we\ird.md
    is one name) is not wrongly split. This keeps the invariants of the
    neighbouring fix(dashboard): show a Windows gateway path's file name at every basename site #17512 Windows-basename change (its 38 tests still pass).
  • No focus state, no overlay, no new eslint-disables, no new localized string.

This supersedes an earlier revision of this PR that added a focus-gated overlay
readout. Three fork AI-review lanes (First Principles, UX, Design) converged on
the same point: the defect is a basename-only label, and the same file already
had buildFileLabels one line away for the folder chips. The relabel is the
smaller, honest fix — it disambiguates for every user at rest (not only
keyboard-only, not only on focus) and removes two real overlay bugs the reviews
found (a stale readout after removing a focused tile, and the overlay covering
the textarea for pointer users).

A second review round (Design + UX, on the relabel revision) is also addressed:
the image caption is now shown only on a name collision (no clutter on a lone
paste), the w-16 clamp was removed from the image chip wrapper (it is on the
caption span only, so a wide resize pill no longer overflows the next chip), the
one-off capture harness is kept out of the product tree, and the evidence lives
under temp-screenshots/ (the path the review evidence gate reads).

Pattern harvest

  • Reuse the disambiguation that already lives in the file. When a component
    renders several labels that can collide (file names, folder names, tab
    titles), buildFileLabels (website/src/utils/fileTokens.ts) is the shared
    rule: basename-first, widened by parent segments only until unique. This
    component already applied it to folder chips; the file and image chips were
    the one tile kind that skipped it. Prefer extending an in-file pattern over a
    second, bespoke mechanism (here, a focus overlay).
  • A fix is better at rest than on an interaction. The first revision solved
    the same-basename problem only while a tile had focus; the relabel solves it
    for pointer, keyboard, and screen-reader users without any gesture, and has no
    mount/unmount state to leak.
  • \ is Windows-only as a separator. Any code that splits a UI path on
    separators must gate backslash handling on the path being Windows-shaped
    (backslashIsSeparator), because \ is a legal POSIX file-name character.

Rule candidate: when a component shows a list of labels that can collide
(file/folder names, tab titles), reuse the repo's buildFileLabels
basename-first widening rather than inventing a per-view disambiguation
(an overlay, a tooltip, a focus readout) — and prefer a fix that is visible at
rest over one gated on an interaction.

Backwards compatibility

Compatible: no API, prop, or key is changed. The only visible change is that a
tile's label text may now carry one or more parent segments when it would
otherwise collide with a sibling; a unique basename is still shown bare.

Removes nothing: no path, key, function, or capability is taken away.

Tests

New website/src/test/FilePreviewStrip.pathLabels.test.tsx (5 tests):

  • two same-basename files render distinct visible labels (the reported
    defect),
  • a unique basename stays a bare basename (no needless widening),
  • widening spans image and non-image tiles together,
  • a colliding image tile gets a widened caption while a unique one gets none,
  • the full path is still exposed via title/aria-label.

Ran locally (worktree): the new test, the existing preview-strip scroll-edge
test, and the neighbouring #17512 windowsBasenameSites 38-test suite
(unchanged — the Windows semantics are preserved), plus
tsc -p tsconfig.app.json and eslint src/ --max-warnings 0 — all green.
Per the fleet's local-gate rule the directly-relevant frontend tests are run
locally; CI runs the full cross-surface set.

Screenshot evidence

Two same-basename images (shot.png) and two same-basename files (report.txt)
from different directories, plus a folder chip — each tile already shows a
distinct, widened label at rest (no focus needed), in both themes.

Dark:

composer tiles with distinct widened labels, dark theme

Light:

composer tiles with distinct widened labels, light theme

Fixes #13829

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 6, 2026 13:21
@chenmingwei23
chenmingwei23 requested a review from buluoray October 6, 2026 13:21
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 6, 2026
@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 80e3fc515452bf01e8bf242df240d316f972085a via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 80e3fc5

Description read

[DESCRIPTION-READ] 2f47064aa6f1177f969c1afbb7bd1c41e330520e87adf0cb8ac39da8e6280256

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — 🟡 CONCERNS

UX-level review of 80e3fc515452bf01e8bf242df240d316f972085a via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

The 64px image caption truncates at its end, so long folder names can cut off the part that tells two tiles apart and the two captions look identical again.

Watch

  • Caption truncation can undo the fix. The caption is <span className="w-16 text-[10px] … truncate">{labelOf(path)}</span>, and the widened label puts the parent folder first. At about 12 characters, labels like screenshots-2025/a.png and screenshots-2026/a.png both show as screenshots-…. The user is back to two tiles they cannot tell apart, with hover-only title as the only way to check, and that path is the keyboard-only gap this PR set out to close. This happens only when two files share a name and sit in long folders, but each time it does, the tiles are still ambiguous. The screenshots already show it starting: docs/shot.p… loses its extension. Smallest fix: keep the end of the label visible (middle-ellipsis, or truncate from the start), or let the caption wrap to two lines.
  • The screenshots show broken thumbnails. The image tiles render alt-text spill (/Demo Workspac Guide/src) instead of images, so nobody can see how the caption sits under a real thumbnail. Re-capture both themes with images that actually load.
  • No first-time reader has seen these labels. This fork lane runs no blind read, so it is unconfirmed that src/report.txt / docs/report.txt chips and the image captions read as "same file name, different folder".

[UX-REVIEWED] 80e3fc5

Description read

[DESCRIPTION-READ] b737fd6028b22a17cea14947f31c44d02fbe1e4fcf21ee1727ef5beadbeea140

That sha256 names everything this verdict read: the PR description, plus the 5 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 80e3fc515452bf01e8bf242df240d316f972085a via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check one claim before merge: images and non-images can never widen against each other. IMG_EXT matches on the extension, and a shared basename means a shared extension.

What this change ships

Inventory (5 items) — 5 justified

Intent: let a user tell apart two staged composer files that share a basename, using the visible label alone. This is a FIX.

  1. Two non-image chips with the same name now show parent folders in their labels (2024/report.txt vs 2023/report.txt). A unique name still shows bare — justified
  2. Two image thumbnails with the same name now get a small caption showing the widened name. An image whose name is unique still has no caption — justified
  3. When a Windows path is used for the label, \ counts as a separator only if the path is drive-rooted or UNC. On POSIX a \ stays part of the file name — justified
  4. A new test file pins the distinct labels, the bare unique label, the image caption, and the full path in title/aria-label — justified
  5. Two committed screenshots under temp-screenshots/, the evidence path that .github/workflows/ux-review.yml:282 reads — justified

[FIRST-PRINCIPLES-REVIEWED] 80e3fc5

Description read

[DESCRIPTION-READ] df105dd80acf7d54afd7075e1ee669c3e70fb0cf75ace3f132244ef967290a9a

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 80e3fc515452bf01e8bf242df240d316f972085a via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 80e3fc5

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 80e3fc515452bf01e8bf242df240d316f972085a via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 80e3fc5

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 6, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/13829-composer-tile-path branch from ea0c438 to f955a20 Compare October 6, 2026 17:18
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 6, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/13829-composer-tile-path branch from f955a20 to 0e70d38 Compare October 6, 2026 20:27
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 7, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/13829-composer-tile-path branch from 0e70d38 to dd8b96b Compare October 7, 2026 11:05
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 7, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Addressed in dd8b96bdf4 — overlay dropped, widened labels instead

Thanks for the reviews. The three blocking lanes (First Principles, UX, Design) converged on the same point, so I reworked the change rather than patch the overlay. Per-finding:

First Principles — BLOCK (symptom patched while the cause sits one line away, use buildFileLabels). Done exactly as named. Deleted the focusedPath state, every onFocus/onBlur handler, the three no-noninteractive-element-interactions eslint-disables, and the preview-strip-full-path span. The non-image file chips now render buildFileLabels labels (the rule the folder chips in this same file already used). The image chips — which showed no visible text at all — gained a visible truncated caption using the same label. One label map is computed over all staged files so images and non-images widen against each other too. The full path stays in title/aria-label.

UX — BLOCK + two Watch items. Both watch bugs are gone because the overlay is gone:

  • "The readout can outlive its tile" (stale focusedPath after a focused remove) — no focus state remains, so nothing can outlive a tile.
  • "Pointer users see it too, and it covers their typing" — there is no absolute top-full z-20 overlay anymore; the labels are inline tile text, so nothing lands over the textarea.
    The disambiguation now works for every user at rest (pointer, keyboard, screen-reader), not only a keyboard user on focus.

Design — BLOCK (no rendered evidence for a new visible surface). There is no longer a new floating surface to screenshot. The change is richer tile labels; I committed dark + light screenshots under evidence/ showing two same-basename images and two same-basename files each rendering distinct widened labels (src/report.txt vs docs/report.txt), referenced in the PR body.

Opus 5.5 review — FINDING (stale full-path readout after removing a focused tile). Same root cause as the UX watch item; resolved by removing the overlay entirely.

GPT 6.1 review — no findings. No change needed.

Windows semantics (neighbouring #17512). The label normalizes \ → / only when \ is actually a separator (drive-rooted / UNC), reusing backslashIsSeparator, so a POSIX name containing a literal \ is not split. #17512's 38 windowsBasenameSites tests still pass locally.

New test: website/src/test/FilePreviewStrip.pathLabels.test.tsx pins that two same-basename tiles render distinct labels, a unique basename stays bare, the widening spans image + non-image tiles, image tiles gain a visible label, and the full path is still in title/aria-label.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 7, 2026
kirocrew-agent added 2 commits October 7, 2026 11:19
… labels (kirodotdev#13829)

Composer preview tiles rendered only the basename, so two staged files named
`report.txt` from different directories were indistinguishable on screen. The
full path lived only in `title` (pointer hover) and the group `aria-label`
(screen reader), serving neither a sighted keyboard-only user nor a pointer
user glancing at the row.

Render each tile's visible label with `buildFileLabels` -- the shared rule the
folder chips in this same component already use -- which is basename-first and
widens by parent segments only until unique among the staged tiles. Non-image
file chips show the widened label. Image chips, which showed no text at all,
gain a visible truncated caption under the thumbnail ONLY when their name
collides with another staged file, so a lone pasted screenshot stays
caption-free. One label map spans all files so images and non-images widen
against each other. The full path stays in `title`/`aria-label`.

Windows-aware: `\` is normalized to `/` for the label only when it is actually
a separator (drive-rooted / UNC), reusing `backslashIsSeparator`, so a POSIX
file name containing a literal `\` is not split -- preserving the kirodotdev#17512
Windows-basename invariants.
Dark + light renders of two same-basename images and two same-basename files
showing distinct widened labels at rest. Committed under temp-screenshots/
(the path the AI-review evidence gate reads at the head SHA); the one-off
capture harness is kept out of the product tree.
@chenmingwei23
chenmingwei23 force-pushed the fix/13829-composer-tile-path branch from dd8b96b to 80e3fc5 Compare October 7, 2026 11:27
@chenmingwei23 chenmingwei23 changed the title fix(dashboard): show full path in composer tiles on keyboard focus (#13829) fix(dashboard): disambiguate same-basename composer tiles by widening labels (#13829) Oct 7, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 2 — addressed in 80e3fc5154

Thanks for the second-round reviews on the relabel revision. Per finding:

Design — BLOCK (w-16 on the image chip re-introduces resize-pill overflow). Fixed. Removed w-16 from the image chip wrapper; it is now only on the caption <span>. The chip wrapper is back to the base sizing (as wide as the wider of tile and resize pill), so a wide de/bn pill no longer spills ~40px onto the next chip.

Design — BLOCK (no admitted evidence; evidence/ is not an admitted path) + Watch (one-off capture tooling in the product tree). Fixed both:

  • Evidence moved to temp-screenshots/composer-tile-path/{dark,light}-distinct-labels.png — the path the review evidence gate reads at the head SHA — and the root evidence/ directory is gone.
  • The one-off capture harness (website/capture/composer-tile-path.*, website/scripts/capture-composer-tile-path.mjs) is dropped from the PR; it was scaffolding for the evidence only.

Design/UX — Watch (PR title still described the superseded overlay). The title is now fix(dashboard): disambiguate same-basename composer tiles by widening labels (#13829), matching the static relabel.

UX — BLOCK (missing screenshot of the caption + widened labels). The admitted temp-screenshots/ renders show two same-basename images (shot.png) and two same-basename files (report.txt) each carrying distinct widened labels, in both themes. Referenced in the description.

UX — Watch (caption on every image tile is clutter). Fixed with the smallest change: the image caption now renders only when the name collides with another staged file (i.e. buildFileLabels widened it past the bare basename). A lone pasted screenshot — the common case — keeps a clean, caption-free tile; non-image chips still always show their label since it is the chip's only text.

PR Hygiene — FAILURE (Pattern harvest needs a Rule candidate: / Not generalizable: line). Added a Rule candidate: line to the Pattern harvest section.

Still 2 commits (fix+test, evidence). Local gate green on 80e3fc5154: the label test (now pinning the collision-gated caption), the #17512 windowsBasenameSites 38-test suite, the preview-strip scroll test, tsc, and eslint src/.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 7, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

**Approve.** Composer tiles now show a *visible* label widened past the basename only when needed, using the same `buildFileLabels` rule the folder chips already use. So two staged `report.txt` files read `2024/report.txt` / `2023/report.txt` for every user, not only pointer-hover or screen-reader users. The full path stays in `title`/`aria-label`.

### Verified (head 80e3fc5154, from source)
- `FilePreviewStrip.tsx:93-96`: one label map over all staged files. `normFile` converts `\` to `/` only when `backslashIsSeparator` (drive/UNC), so a POSIX `we\ird.md` is not split. That's the same predicate `pathBasename` uses (`pathBasename.ts:21-32`).
- `fileTokens.ts:31-47`: `buildFileLabels` widens one parent at a time until unique, and `|| p` guarantees a non-empty label. Absolute and relative paths with the same tail resolve to distinct labels at max depth.
- `:104` `isWidened` stays false for a sole Windows path (the normalized label equals `pathBasename`), so lone images remain caption-free.
- `:167-169`: `w-16` is on the caption only, not the chip wrapper, so the round-2 fix for resize-pill overflow holds.
- First Principles' cross-category claim holds: `IMG_EXT` keys on the extension, so an image and a non-image can never share a basename.

### Tests
**Not run locally.** The review worktree had no `website/node_modules`. I relied on CI (green, with no failures at this head) and on reading source. Predicted mutations: reverting the chip to `pathBasename` fails `renders distinct visible labels…`, and dropping the `isWidened` gate fails `captions a colliding image tile but not a unique one`. No test covers the `normFile` Windows branch.

### Upgrade impact
Display only. Nothing is persisted, and there are no API or config changes. Rendering changes only when two staged files share a basename. Unique names look exactly as before.

### Non-blocking follow-ups
1. **Caption truncation can hide the part that tells them apart** (UX lane). `truncate` cuts the end of the 64px caption, and the widened label puts the parent first, so `screenshots-2025/a.png` and `screenshots-2026/a.png` both show `screenshots-…`. Consider a middle/start ellipsis or a two-line clamp. This fails closed: the worst case is the old ambiguity, and the full path is still in `title`/`aria-label`.
2. **Evidence screenshots show broken thumbnails.** `temp-screenshots/composer-tile-path/light-distinct-labels.png` renders alt-text spill instead of images, and `docs/shot.p…` already truncates. Please re-capture with images that load.
3. The image preview button's `aria-label` (`open_preview_of`, `:129`) still uses `pathBasename`, so two colliding images announce the same button name. Consider `labelOf(path)`.
4. Add a unit test for a Windows-shaped pair (`C:\a\x.md` / `C:\b\x.md`) to pin the `normFile` branch. This is from source only; I did not run it on Windows.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving (crew-pr-reviewer). A widened visible label shows on an image tile only when its basename collides with another staged file. The full path stays in the title and aria-label. This is a frontend-only change. CI is green and the base is main.

@iamwhatever
iamwhatever enabled auto-merge (squash) October 7, 2026 16:08
@iamwhatever
iamwhatever merged commit 5b9cfb7 into kirodotdev:main Oct 7, 2026
108 of 116 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

a11y: composer file/paste tiles show only the basename on keyboard focus (no visible full path)

3 participants