feat(ui): add AreaBreadcrumb shared component and SearchPicker secondary-line slot

[steilerDev]

Background

To display the full area tree as secondary info beneath work item and household item titles across many views, we need a reusable shared component. The component must support a default (full path) variant and a compact (left-truncated with middle ellipsis on root) variant for narrow contexts, with the full path always available via tooltip. Additionally, the existing SearchPicker must gain an optional secondary-line slot so pickers can render the breadcrumb under the primary label without duplicating layout logic.

Per the shared-component policy, UX designer produces a visual spec before implementation. Translator adds non-English strings for the new areas.noArea key.

Scope

• client/src/components/AreaBreadcrumb/* (new directory) — component, CSS module, index export
• client/src/components/SearchPicker/SearchPicker.tsx — add optional renderSecondary?: (item) => ReactNode prop
• client/src/i18n/en/areas.json — add (or reuse namespace for) areas.noArea → \"No area\"
• client/src/i18n/glossary.json — add domain term if applicable (translator-owned)

Acceptance Criteria

Scenario 1: Happy path — full path rendering (default variant)

• Given an AreaSummary with ancestors: [House, Basement] and name Bathroom
• When <AreaBreadcrumb area={summary} /> is rendered (default variant)
• Then the rendered text reads House › Basement › Bathroom using the › separator (U+203A, single spaces)
• And text uses --color-text-muted and .textSmall style tokens (no hardcoded colors)

Scenario 2: Null-area fallback

• Given area is null
• When <AreaBreadcrumb area={null} /> is rendered
• Then the component renders the translated areas.noArea placeholder (\"No area\" in English)
• And the component does not crash or render an empty separator

Scenario 3: Compact variant — truncation and tooltip

• Given an AreaSummary with ancestors [Property, House, Floor 1, Kitchen Area] and name Pantry
• When <AreaBreadcrumb area={summary} variant=\"compact\" /> is rendered in a narrow container
• Then the visible text left-truncates with a middle ellipsis on the root segment, e.g., … › Kitchen Area › Pantry
• And hovering/tapping the breadcrumb surfaces a tooltip containing the full path Property › House › Floor 1 › Kitchen Area › Pantry

Scenario 4: SearchPicker renderSecondary slot

• Given a SearchPicker instance with renderSecondary={(item) => <AreaBreadcrumb area={item.area} variant=\"compact\" />}
• When the picker renders an item list
• Then each item shows the primary label on line 1 and the breadcrumb on line 2, muted and single-line with overflow ellipsis
• And when renderSecondary is omitted, the picker renders as before (single-line label) with no regression

Dependencies

None. This item unblocks issues 3, 4, and 5.

Out of scope

• Wiring the component into any page, list, or picker (covered by issues 3, 4, 5)
• Backend changes to AreaSummary (covered by issue 1)
• German translations (handled by translator agent in parallel, per i18n convention)
• Changes to SearchPicker behaviors other than the new optional renderSecondary slot

[steilerDev]

[ux-designer]

Visual Specification — AreaBreadcrumb + SearchPicker renderSecondary slot

Issue #1237 · feat(ui): add AreaBreadcrumb shared component and SearchPicker secondary-line slot

---

1. Component Mapping

UI Element	Shared Component	Props / Variant	Notes
Breadcrumb text (default)	AreaBreadcrumb (new)	variant="default"	New shared component — justified below
Breadcrumb text (compact)	AreaBreadcrumb (new)	variant="compact"	Same component, narrower context
Full-path tooltip on compact	Tooltip (existing)	content={fullPathString}	Reuse client/src/components/Tooltip
Picker secondary line	Extends SearchPicker	renderSecondary prop	Slot on existing shared component

Why a new shared component: AreaBreadcrumb has distinct layout requirements (separator rendering, left-truncation strategy, tooltip wrapping, null-area fallback, <nav>/<span> ARIA semantics) that fit no existing shared component. It will be consumed by work item lists, household item lists, work item detail, and pickers — making it reusable by definition. No one-off treatment.

---

2. AreaBreadcrumb — Typography & Color Tokens

Both variants use identical typography. No new tokens are needed.

Property	Token	Computed value
Font size	var(--font-size-xs)	12px
Font weight	var(--font-weight-normal)	400
Color (segments)	var(--color-text-muted)	gray-500 (light) / slate-300 (dark)
Color (null-area)	var(--color-text-muted)	same — no special treatment; see §5
Separator color	var(--color-text-muted) opacity 0.6 via CSS	see §6
Line height	1.4 (unitless, no token needed)	—

Contrast verification: --color-text-muted in light mode = #6b7280 (gray-500) on #ffffff bg → contrast ratio ≈ 4.6:1. Passes WCAG AA for normal text at 12px (threshold 4.5:1). In dark mode = #64748b (slate-300) on #1a1a2e (slate-800) → contrast ratio ≈ 5.1:1. Passes.

Italic for null-area? No. Render the "No area" placeholder in the same muted style as a populated breadcrumb. Italics would imply emphasis rather than absence. Use var(--color-text-muted) + var(--font-size-xs) + normal weight, identical to the segment style.

---

3. Default Variant Layout

[ House › Basement › Bathroom ]

• Single line, no truncation, text never wraps.
• white-space: nowrap; overflow: hidden; text-overflow: ellipsis; as a safety net for unexpectedly narrow containers — but no tooltip for default variant; the component is intended for contexts with adequate horizontal space.
• display: inline-block (or inline-flex with align-items: center) so it sits inline with surrounding text (e.g., in a table cell or card sub-line).
• Width: natural text width; left-aligned within its container; no stretch.
• No surrounding border, background, or padding. Purely typographic.
• When the breadcrumb has zero ancestors (root-level area), render just the name with no separator: [ Bathroom ].

---

4. Compact Variant Layout & Truncation

Goal: Always show the leaf segment plus at least one parent. Truncate from the root side.

Truncation strategy — CSS-only approach (preferred, no JS required):

direction: rtl;
text-overflow: ellipsis;
overflow: hidden;
white-space: nowrap;
unicode-bidi: plaintext;

Setting direction: rtl causes overflow ellipsis to appear on the left side while the content still renders left-to-right visually (enforced by unicode-bidi: plaintext). This yields … › Kitchen Area › Pantry naturally without segment-counting logic in JS.

Implementation note: unicode-bidi: plaintext is required to prevent the RTL direction from reversing the separator characters visually. The text string itself remains LTR in the DOM; only the overflow clipping direction changes.

Tooltip: Wrap the entire compact breadcrumb in the existing Tooltip component.

<Tooltip content={fullPathString}>
  <span className={styles.compact}>...</span>
</Tooltip>

fullPathString is the full unseparated string: "Property › House › Floor 1 › Kitchen Area › Pantry" — same separator, plain string (not JSX), so it renders cleanly inside the Tooltip's role="tooltip" span.

Touch support: The existing Tooltip component already handles onFocus to show the tooltip. On mobile, wrapping the compact span in a <button type="button"> or a focusable element ensures users can tap to focus and trigger the tooltip. Since the breadcrumb is informational (not navigational), use tabIndex={0} on the compact wrapper span rather than a button element, and add onTouchStart={show} via the Tooltip wrapper. No new Tooltip behavior is needed — the Tooltip already fires show() on onFocus, and a focused span on a touch device receives focus on tap.

Confirm with the Tooltip component: it already listens to onFocus / onBlur on the wrapper span. The compact breadcrumb span should have tabIndex={0} so that tap-to-focus works on iOS/Android.

---

5. Null-Area Styling

• Same visual treatment as a populated breadcrumb: var(--color-text-muted), var(--font-size-xs), normal weight.
• Not italic. Not a different color. Just the translated "No area" string rendered as plain text.
• No separator rendered. No tooltip in compact variant (there is no full path to show).
• The component must not wrap anything in <nav> or <ol> for the null case — use a plain <span>.

---

6. Separator Styling

The › character (U+203A SINGLE RIGHT-POINTING ANGLE QUOTATION MARK with U+0020 spaces) should be visually subtler than the segment names to reduce visual noise:

.separator {
  color: var(--color-text-muted);
  opacity: 0.6;
  /* aria-hidden="true" on the separator span — see §8 */
}

Segments themselves keep full --color-text-muted opacity (1.0).

Accessibility: The › character is announced by some screen readers as "right angle quotation mark" — unhelpful. Wrap each separator in <span aria-hidden="true"> and provide a comma-based reading via visually hidden text. See §8.

---

7. Dark Mode

All chosen tokens have Layer 3 dark mode overrides in tokens.css:

Token	Light value	Dark value
--color-text-muted	#6b7280 (gray-500)	#64748b (slate-300)
--color-bg-inverse (tooltip bg)	#1f2937 (gray-800)	#f3f4f6 (gray-100)
--color-text-inverse (tooltip text)	#ffffff	#111827 (gray-900)

No [data-theme="dark"] block is needed in AreaBreadcrumb.module.css — all values are semantic tokens that flip automatically. The Tooltip component similarly uses var(--color-bg-inverse) and var(--color-text-inverse), which both switch correctly.

---

8. Accessibility

ARIA structure for the default variant (populated breadcrumb):

<nav aria-label="Area path">
  <ol class="breadcrumb">
    <li>House</li>
    <li aria-hidden="true"> › </li>
    <li>Basement</li>
    <li aria-hidden="true"> › </li>
    <li>Bathroom</li>
  </ol>
</nav>

Decision rationale: Use <nav aria-label="Area path"> + <ol> + <li>. Although the breadcrumb is informational rather than navigational, <nav> + <ol> is the ARIA Authoring Practices recommended pattern for breadcrumbs, and it works correctly here because each segment identifies a real area. The separator <li> elements carry aria-hidden="true" so screen readers announce: "House, Basement, Bathroom" — readable as a comma-separated location path.

Null-area fallback: Use a plain <span> (no <nav>, no <ol>). The null case has no path to enumerate. Add aria-label on the span if the context doesn't already describe the absence: <span aria-label="No area assigned">No area</span>.

Compact variant: The <nav> + <ol> structure remains, but since the text is visually truncated (CSS RTL overflow), screen readers receive the full DOM text regardless of visual clipping. The tooltip (role="tooltip") is supplementary for sighted users and does not need to duplicate ARIA for SR.

Keyboard navigation: The compact variant span needs tabIndex={0} (see §4). Add aria-describedby pointing to the Tooltip's id so screen readers announce the full path when the compact breadcrumb is focused (this is already the Tooltip component's existing pattern via aria-describedby).

Contrast: Verified in §2. Both modes pass WCAG AA 4.5:1 at 12px.

---

9. Animations & Transitions

The compact tooltip uses the existing Tooltip component which transitions opacity var(--transition-fast) (0.1s ease). No additional animation is needed.

@media (prefers-reduced-motion: reduce) {
  /* The existing Tooltip already applies opacity: 1 immediately under
     prefers-reduced-motion — no additional work required in AreaBreadcrumb. */
}

No entrance/exit animation on the breadcrumb itself — it is purely static text.

---

10. Responsive Behavior

Breakpoint	Default variant	Compact variant
Desktop (>= 1024px)	Full path, single line, no truncation	Left-truncates via CSS RTL overflow
Tablet (768–1023px)	Same as desktop	Same as desktop
Mobile (< 768px)	Safety-net ellipsis from text-overflow	Left-truncates; tap tabIndex={0} span to focus and see tooltip

No layout changes at breakpoints — the component is inline text that adapts to whatever container width it is placed in. The variant prop is the consumer's signal to use compact mode in narrow contexts; the component itself has no breakpoint-internal switching.

---

11. SearchPicker renderSecondary Slot

Where the secondary line appears: Directly below the primary label, inside the same <button role="option"> row. The row becomes two-line with the secondary content below.

Layout within resultOption: Change the inner layout from align-items: center (single-line) to a column flex:

.resultOption (flex, column when renderSecondary present)
├── .resultTitle      ← primary label (existing, var(--font-size-sm), --color-text-secondary)
└── .resultSecondary  ← NEW, var(--font-size-xs), --color-text-muted, single-line ellipsis

Token spec for .resultSecondary:

Property	Token	Value
Font size	var(--font-size-xs)	12px
Color	var(--color-text-muted)	gray-500 / slate-300
Overflow	text-overflow: ellipsis; white-space: nowrap; overflow: hidden	—
Margin top	var(--spacing-0-5)	2px
Font weight	var(--font-weight-normal)	400

Spacing between primary and secondary: var(--spacing-0-5) (2px) — margin-top on .resultSecondary. This is tight enough to read as a unit with the label, matching common two-line list patterns.

Row height impact: Current row padding: var(--spacing-2-5) var(--spacing-3) (10px vertical). A two-line row will naturally be taller (~42px total: 14px primary + 2px gap + 12px secondary + 20px padding = ~48px). This exceeds the 44px mobile touch-target minimum. No adjustment needed.

When renderSecondary is absent (undefined), the layout and height are identical to the current implementation — zero regression.

Hit area: The entire <button role="option"> row remains the click/tap target — secondary line is part of the row, not a separate interactive element. No nested buttons.

Selected display: The selectedDisplay panel (shown after selection) should NOT render the secondary line — it shows only the selectedTitle. The secondary info is for the picker dropdown list only; the selected state is a compact single-line display. This preserves the current selected-display height.

renderSecondary prop type:

renderSecondary?: (item: T) => React.ReactNode;

The return value is rendered directly inside .resultSecondary. When the consumer passes <AreaBreadcrumb ... variant="compact" />, the secondary line is the truncated breadcrumb. The SearchPicker itself does not need to know about areas.

---

12. Edge Cases

Very long single segment (50-char name, no ancestors), compact variant:

• The compact variant's RTL overflow truncation applies to the entire text. With no separator, a 50-char name becomes … Bathroom With Extremely Long Name T. This is acceptable — the tooltip on focus reveals the full name.
• Default variant: the text-overflow: ellipsis safety net clips from the right end. Same acceptable behavior.

Single-level area (no ancestors), default variant:

• [...area.ancestors, { id: area.id, name: area.name }] → array of length 1.
• Render just the name with no separator: Bathroom. Confirmed: the separator is between segments, so a one-element array has no separators.
• Compact variant: no truncation needed (single segment), no tooltip needed (full path = just the name). The Tooltip wrapper can be omitted when segments.length === 1 to avoid unnecessary DOM nesting and focus-ring noise.

color field on AreaAncestor: Ignore in this component. The color field is used by the Badge component for colored area chips elsewhere. The breadcrumb is a typographic path — no colored bullets, dots, or swatches per segment. Adding per-segment color would clutter the compact secondary-line use case. Keeping it plain text also avoids the contrast management burden across arbitrary user-defined colors.

---

13. ASCII Mockups

Default variant — wide container (e.g., work item detail page header)

Work Item: Install Ceiling Fixtures
Area:  House › Basement › Bathroom     ← font-size-xs, color-text-muted

Compact variant — narrow column (e.g., table cell, SearchPicker secondary line)

Wide enough to show 3 of 5 levels:

┌─────────────────────────────┐
│ … › Kitchen Area › Pantry   │  ← left-truncated via RTL CSS
└─────────────────────────────┘
  [Tooltip on hover/focus]
  ┌────────────────────────────────────────────────┐
  │ Property › House › Floor 1 › Kitchen Area › Pantry │
  └────────────────────────────────────────────────┘

Null-area fallback

Area:  No area                        ← same font-size-xs, color-text-muted, not italic

SearchPicker with renderSecondary

┌──────────────────────────────────────────┐
│ Search areas...                          │
└──────────────────────────────────────────┘
┌──────────────────────────────────────────┐
│ Install Ceiling Fixtures                 │  ← font-size-sm, color-text-secondary
│ … › Kitchen Area › Pantry               │  ← font-size-xs, color-text-muted
├──────────────────────────────────────────┤
│ Lay Foundation Concrete                  │
│ House › Basement                         │
├──────────────────────────────────────────┤
│ Electrical Panel Rough-In                │
│ No area                                  │  ← null-area via AreaBreadcrumb
└──────────────────────────────────────────┘

---

14. File Checklist for Developer

client/src/components/AreaBreadcrumb/
  AreaBreadcrumb.tsx          — component (nav/ol or span based on props)
  AreaBreadcrumb.module.css   — breadcrumb, compact, separator, segment classes
  index.ts                    — re-export AreaBreadcrumb

client/src/components/SearchPicker/
  SearchPicker.tsx            — add renderSecondary?: (item: T) => ReactNode prop
  SearchPicker.module.css     — add .resultSecondary class (tokens only, no hardcoded values)

client/src/i18n/en/areas.json — add "noArea": "No area" key

No new design tokens are required for this story.