Replace ignored input read with selected_data connector, and add Excel columns write mode

[ebhills]

The input connector was ignored in the read: based on out-of-date assumptions related to its usage. The fix here ensures that recipes that explicitly consume the calling grid's selected data have a named read contract, and fail when an expected composed input is missing or empty. This adds shared/Excel read connectors (input → selected_data) and an explicit Excel columns writer (fka dataframe) while preserving the full calculation dataframe and generic Python return behavior.

Linked issue

Part of #943. Keep the issue open until the companion XL/JS integration and live verification are complete.

What changes

• Add grid.selected_data (JS) and forwarding wrapper excel.selected_data (XL), with the same filters and current-invocation dataframe scope.
• Add excel.columns as spreadsheet write mode columns (in lieu of dataframe); retain excel.sheet as mode sheet. Each emits all requested columns for destination-specific handling in XL.
• Reject missing/empty operands using any of input, grid.selected_data, or excel.selected_data in join/union/concatenate, including filters that remove all rows. The tests cover all three spellings for this validation.
• Preserve the standalone generic Python input exception: it may return an empty dataframe. The new grid.selected_data and excel.selected_data connectors require nonempty data even when used outside a composed read. Legitimate empty external query results remain valid.
• Preserve generic dataframe, inline/saved nested-recipe behavior, and matrix child-write orchestration.
• Register schema help, validate the generated schema without a network fetch, and document the spreadsheet contracts.

How it was verified

Focused credential-free checks using pytest-local.ini passed across:

• tests/connectors/test_input.py
• tests/connectors/test_excel.py
• tests/connectors/test_matrix.py
• tests/recipes/test_read.py
• tests/recipes/test_write.py

The broad focused run passed 115 tests; the final input/nested/schema suite passed 38 tests, including the additional saved-recipe cases. Credential variables were removed for these checks. git diff --check passed. No deployed Lambda or live Excel verification is claimed.

Compatibility and risk

Existing input syntax and filters remain supported. The intentional behavior change is an actionable failure for an empty expected selected-data operand in composed reads. New selected-data connectors require nonempty data and read the current transformed parent dataframe when nested.

This PR does not change Lambda defaults or perform Excel writes itself. The Python package must be promoted to execute-recipes-dev, and the development schema published, before XL development uses the new connectors. Coordinate rollback with XL/recipes already using those new names.

Companion shared helpers: WranglesJS #121. XL consumer: WranglesXL #1279. excel.table remains separate in #1220; the empty Functions override edge remains out of scope.

Ready-for-review checklist

• One human delivery owner is assigned: @ebhills
• The linked issue is correct; no release milestone has been selected
• The branch is current with main and has no merge conflicts
• Focused tests pass
• New or changed behavior has direct test coverage
• Documentation/schema/configuration is updated where applicable
• The PR contains no unrelated changes
• The PR description reflects the branch's current scope and latest validation
• One primary reviewer is requested only when this PR is ready

Draft while CI and the review handoff are pending.

[Copilot]

🔵 Needs a closer look

Its contract depends on inaccessible companion JS/XL changes and lacks live Excel integration verification.

0 open findings

What changed in this PR

Adds explicit selected-grid inputs and Excel write modes while preserving generic dataframe behavior.

Changes:

• Adds grid.selected_data and excel.selected_data.
• Adds excel.columns and clarifies excel.sheet.
• Validates empty composed inputs and updates tests, schema, and documentation.

Recommended disposition: Comment only

Next steps

1. Reviewer: Verify CI and companion JS/XL contracts before approval.

File	Description
wrangles/​recipe.py	Validates selected-data operands.
wrangles/​connectors/​grid.py	Adds shared selected-data input.
wrangles/​connectors/​excel.py	Adds Excel wrapper and columns writer.
wrangles/​connectors/​__init__.py	Registers the grid connector.
tests/​connectors/​test_input.py	Covers selected-data behavior and schema.
tests/​connectors/​test_excel.py	Covers Excel write modes.
schema/​generate_recipe_schema.py	Updates help and offline validation.
docs/​spreadsheet_recipes.md	Documents spreadsheet contracts.
.gitignore	Tracks the new documentation.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.