feat(propose_new_doc_card): canonical widget Stage 1-4 (:layer_shell_and_callout family — new)

[ty13r]

Summary (DRAFT — Pascal-review required)

Phase 41 PR 41.6 — adds :propose_new_doc_card as a NEW canonical widget in family :layer_shell_and_callout (NEW family — this PR creates the aggregator). Stage 1-4 of the canonical-widget pipeline; Stage 5 (AshUI Screen DSL adoption) deferred.

Renders the :propose_new_doc SessionEvent emitted by propose_new_project_document MCP (shipped in PR 41.3a feat(phase-41.3a)).

Implementation

Stage 1 — UnifiedUi catalog + DSL entity + DSL pipeline + verifier:

• packages/unified_ui/lib/unified_ui/widget_components.ex — register :propose_new_doc_card with family: :layer_shell_and_callout
• packages/unified_ui/lib/unified_ui/dsl/entities/widget_components.ex — DSL leaf
• packages/unified_ui/lib/unified_ui/compiler/pipeline.ex + dsl/node.ex + dsl/verifiers/validate_widget_components.ex — lowering + verifier wiring

Stage 2 — UnifiedIUR constructor + validation:

• packages/unified_iur/lib/unified_iur/widgets/components.ex — propose_new_doc_card/1 constructor + @layer_callout_kinds
• packages/unified_iur/lib/unified_iur/validate.ex — :invalid_propose_new_doc_card validation
• packages/unified_iur/lib/unified_iur/fixtures.ex — fixture coverage

Stage 3 — LiveUi Phoenix.Component:

• packages/live_ui/lib/live_ui/widgets/propose_new_doc_card.ex — Phoenix.Component with live-ui-* BEM, full aria coverage (aria-controls + aria-expanded + descriptive labels), Accept/Reject/Preview actions
• packages/live_ui/lib/live_ui/renderer.ex — dedicated :propose_new_doc_card clause placed above generic fallback

Stage 4 — Adapter routings + NEW family aggregator:

• lib/ash_ui/rendering/iur_adapter.ex — canonical IUR path
• lib/ash_ui/rendering/live_ui_adapter.ex — string-HTML fallback
• packages/live_ui/lib/live_ui/widgets/layer_shell_and_callout.ex — NEW family aggregator (Codex created this file because :layer_shell_and_callout didn't exist as an aggregator yet; will be extended in PR 41.7 with escalation_card)

Spec ref (ariston-ui)

• .spec/specs/canonical_widget_propose_new_doc_card.spec.md
• ADR-0044 §"PR 6 — propose_new_doc_card"

Spec ↔ shipped payload reconciliation needed (Pascal): spec contract uses proposed_path/proposed_title/rationale/proposed_kind/decision. Implementation uses target_path/title/body_md_preview/conversation_seed_md/status to match the Phase 41.3a SessionEvent payload (lib/ariston_ui/mcp/tools/propose_new_project_document.ex:80-88,107-111) that's already shipped. Recommend amending the spec to match the working payload — the SessionEvent ships those exact field names and any rename would ripple back through PRs 41.3a/3b.

Test plan

• IUR constructor: happy path + invalid-payload rejections (blanks, unknown status, invalid actions)
• LiveUi.Widgets.ProposeNewDocCard render: status variants / Accept-Reject button rendering for :pending / preview link / aria-expanded + aria-controls linkage
• Both adapter dispatch tests
• Catalog test asserts family: :layer_shell_and_callout
• DSL verifier rejects malformed widget payloads
• aria-controls target remains in DOM with hidden attribute when collapsed (post-Opus-review fix)

97/97 tests pass on changed files; 117 total pass across the widget surface.

Reviews

• Codex implementer: 1 round, no WIP. 25 files, 1399 insertions.
• Opus Max independent review: APPROVE for DRAFT. No P1. 1 P2 (aria-controls dangling reference) fixed inline post-review; 1 P2 (stateless widget contract documentation) deferred as design clarification.

Deferred P3 follow-ons

• Spec vs shipped payload field naming reconciliation (see above; Pascal decision).
• status: :archived added to widget enum — not in spec; aligns with Phase 41.3a lifecycle. Pascal to confirm.
• CSS asset assets/css/widgets/propose_new_doc_card.css not present (DRAFT acceptable).
• 6 pre-existing test failures unrelated to this PR (collection_picker / thread_card / composer_query_preview missing-from-fixture, pre-existed on main).

Notes for Pascal

• NEW :layer_shell_and_callout family aggregator at packages/live_ui/lib/live_ui/widgets/layer_shell_and_callout.ex. PR 41.7 (escalation_card) will extend this aggregator with its widget.
• Spec ↔ payload reconciliation — see above. Implementation is internally consistent; aligned to actual SessionEvent emission shape.
• Stateless widget contract: :expanded? and :seed_expanded? state lives in the consuming LiveView, not the widget. Widget emits body_toggled and conversation_seed_toggled events; consumer flips state.

Generated with Claude Code