feat(plugin-field-kit): conditional sub-field visibility (visibleWhen) — follow-up to #702

[ilicfilip]

Background

Following up on the agreed visibleWhen work mentioned in discussion #571:

"visibleWhen looks good, but leave it to a follow-up." — @ascorbic, discussion #571

I read "follow-up" as "follow-up PR" but want to confirm before opening one — opening this discussion in the Ideas category to match the CONTRIBUTING.md process for features.

Proposal

Add conditional sub-field visibility (visibleWhen) to the object-form and list widgets in @emdash-cms/plugin-field-kit. Sub-fields can declare a rule that hides them when a sibling value doesn't match — e.g. show Cooking time only when Cooked? is checked.

{
  "key": "cooking_time",
  "label": "Cooking time",
  "type": "number",
  "visibleWhen": { "field": "cooked", "equals": true }
}

Operators

Four operators, all using strict equality (so equals: 1 does not match "1"):

Operator	Matches when…
equals	sibling is strictly equal
notEquals	sibling is not strictly equal
in	sibling is one of the listed values
notIn	sibling is not in the list

Behaviour

• Values persist across toggles. Hidden fields stay in the DOM (display: none + aria-hidden) so values round-trip through save and reappear when the condition flips back. A user can toggle a flag on, fill the dependent field, toggle off, and toggle on again — the value is still there.
• required is stripped while hidden so HTML5 validation can't block save on a field the user can't see. The required asterisk reappears with the field.
• list evaluates per-row — row A can show a sub-field that row B hides.
• Sibling lookup only. visibleWhen.field references another sub-field within the same object-form (or list row), not a top-level collection field.

Code is ready

Implementation is on a single-commit branch off latest main, ready to PR once approved here:

• Branch: ilicfilip:feat/field-kit-visible-when
• Compare view: main...ilicfilip:emdash:feat/field-kit-visible-when

What's in it (10 files, all in packages/plugins/field-kit/ or its docs):

• 5 source files implementing VisibleWhenCondition, the isSubFieldVisible evaluator, hidden-aware rendering in SubField, and per-row sibling context wiring in list / object-form
• 3 test files: 6 unit tests for isSubFieldVisible, 4 new object-form tests, 1 new list test
• 1 docs update: new Conditional visibility (visibleWhen) subsection on the existing field-kit.mdx reference page
• 1 changeset: @emdash-cms/plugin-field-kit: minor

pnpm typecheck and pnpm test are green (44 plugin tests pass).

Demo

Re-shared from the original prototype on ilicfilip/field-kit#2 — same feature, same behaviour, recorded against a recipe schema with calories, protein, source, organic, on sale, ingredients sub-fields:

Screen.Recording.2026-04-17.at.16.58.40.mov

Asking

@ascorbic — does this match what you had in mind for the follow-up? Happy to:

1. Open the PR directly against main if "follow-up" meant follow-up PR (my read of your earlier comment), or
2. Iterate on the proposal here first if you'd prefer to discuss before code review.

Either way the branch is rebased and ready.