feat(:sidebar_item): add avatar_url + state props (Wave 3.7 Class C extension, DRAFT, Pascal-review REQUIRED)

[ty13r]

Summary

Extends the canonical :sidebar_item widget with two new optional props per unified_ui issue #184 (Wave AshUI-3.7 comp-fidelity audit findings SB-4 + SB-5).

• avatar_url (String.t() | nil, default nil): when set, renders a small <img aria-hidden="true"> before the item label. Used for DM rows in the sidebar showing the target's avatar beside the name.
• item_state (:default | :stalled | :blocked | :errored | nil, default nil): applies a BEM modifier class live-ui-sidebar-item--state-{value} and a data-live-ui-item-state hook attribute for CSS/JS targeting. Semantic workflow-state meaning for stalled/blocked/errored items.

Both are backward-compatible additive changes (nil default preserves all existing behavior).

Files modified

• packages/unified_iur/lib/unified_iur/widgets/components.ex — Stage 1: sidebar_item/3 constructor accepts avatar_url and item_state opts; validates item_state against [:default, :stalled, :blocked, :errored]; uses maybe_put so nil values are omitted
• packages/live_ui/lib/live_ui/renderer.ex — Stage 3: replaces the inline :sidebar_item HEEx template with a dispatch to LiveUi.Widgets.SidebarItem.component (same pattern as :thread_card)
• packages/live_ui/lib/live_ui/widgets/sidebar_item.ex — Stage 4: new LiveUi.Widgets.SidebarItem Phoenix.Component with full attr declarations + render/1
• packages/unified_iur/test/unified_iur/widgets/components_test.exs — 10 new describe "sidebar_item constructor" tests covering defaults, avatar_url present/absent, all valid item_state values, invalid state raises, backward-compat, and combined use
• packages/live_ui/test/live_ui/sidebar_item_widget_test.exs — 16 new Stage-4 tests: true-widget attr, label render, aria-current + BEM selected, avatar img present/absent, state hook + modifier for each state, nil/default state omission, renderer dispatch

Test results

• packages/unified_iur: 34 tests, 0 failures (components_test.exs only; 7 pre-existing failures in other test files are unrelated to this PR)
• packages/live_ui: 587 tests, 0 failures (includes 16 new sidebar_item tests)

Open questions for Pascal (verbatim from unified_ui #184)

1. Avatar composition: currently renders <img> inline directly (smallest delta). Should :sidebar_item instead compose with the canonical :avatar widget (ash_ui PR feat(live_ui): add Avatar widget Phoenix.Component (Wave 3.9.1a Stage-4) #116, DRAFT)? Composing is cleaner separation but a larger PR. Inline <img> used here pending Pascal decision.
2. State enum completeness: :stalled | :blocked | :errored are the audit-required values. Are :loading or :in_progress needed? Should it overlap with the :loading state convention from button widgets?
3. state vs tone naming: item_state was chosen to avoid collision with LiveUi.Component's common :state assign (style hook). Does this widget align with the :tone convention used elsewhere? Or is state more appropriate here for workflow-state semantics?
4. ARIA for :blocked: comp shows visual treatment (dimmed + lock icon) but items remain clickable. Should aria-disabled="true" be added for :blocked? Or just a state CSS class with no ARIA implication?
5. Avatar fallback: when avatar_url not provided but the item is a DM row, should there be an initials fallback? Left as consumer-side composition for now.

Cross-references

• Closes audit gap: ariston-ui docs/wave-ashui-3-7-comp-fidelity-audit.md extension table lines 237-238 (SB-4 + SB-5)
• Ref: unified_ui issue #184
• Avatar canonical: ash_ui PR feat(live_ui): add Avatar widget Phoenix.Component (Wave 3.9.1a Stage-4) #116 (DRAFT) — see open question Implement Ash UI Governance System #1
• Class C (extension issue + Pascal-review extension PR) per Wave 3.7 comp-audit dispatch pattern

Status

DRAFT — Pascal review required before merge. Standing auto-merge does NOT apply.

🤖 Generated with Claude Code