feat: configurable description position for custom fields [3.x]

[ManukMinasyan]

Summary

• Adds per-field configuration for where the description text appears: below the input (default, current behavior) or above the input (between label and input)
• New DescriptionPosition enum with BELOW/ABOVE cases mapping to Filament's belowContent() and aboveContent() schema slots
• New FIELD_DESCRIPTION_POSITION feature flag (disabled by default) — both FIELD_DESCRIPTION and FIELD_DESCRIPTION_POSITION must be enabled for the position selector to appear
• Position Select in the field management form, visible only when both flags are enabled and the description field has a value
• No database migration required — stored as a nullable property in the existing JSON settings column via CustomFieldSettingsData

Changes

File	Change
src/Enums/DescriptionPosition.php	New enum with BELOW/ABOVE cases and translatable labels
src/Enums/CustomFieldsFeature.php	Added FIELD_DESCRIPTION_POSITION case
src/Data/CustomFieldSettingsData.php	Added nullable descriptionPosition property
src/Filament/Integration/Base/AbstractFormComponent.php	Position-aware rendering via when() block
src/Filament/Management/Schemas/FieldForm.php	Position Select + live() on description Textarea
resources/lang/en/custom-fields.php	Translation keys for position labels

Test plan

• 10 new tests in tests/Feature/DescriptionPositionTest.php covering:
  • Enum backing values and translatable labels
  • Feature flag disabled by default and can be enabled
  • DTO null default, enum storage, serialization round-trip
  • Rendering below by default, above when enabled, fallback when flag disabled

[Copilot]

Pull request overview

Adds a per-custom-field setting to control whether a field’s description renders above or below the input, gated behind a new feature flag and persisted in the existing settings JSON via CustomFieldSettingsData.

Changes:

• Introduces DescriptionPosition enum (below / above) with translatable labels.
• Adds FIELD_DESCRIPTION_POSITION feature flag and a management UI select for settings.description_position.
• Updates Filament form component rendering to use aboveContent() when configured (otherwise default helper text below).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/Enums/DescriptionPosition.php	New enum for ABOVE/BELOW description placement with labels.
src/Enums/CustomFieldsFeature.php	Adds new FIELD_DESCRIPTION_POSITION feature gate.
src/Data/CustomFieldSettingsData.php	Persists nullable descriptionPosition in settings DTO.
src/Filament/Integration/Base/AbstractFormComponent.php	Renders description via aboveContent() when enabled/configured.
src/Filament/Management/Schemas/FieldForm.php	Adds description position select + makes description textarea live().
resources/lang/en/custom-fields.php	Adds translations for new label/options.
tests/Feature/DescriptionPositionTest.php	New Pest coverage for enum/flag/DTO/rendering scenarios.
docs/superpowers/specs/2026-04-13-custom-field-description-position-design.md	Design spec for the feature.
docs/superpowers/plans/2026-04-13-custom-field-description-position.md	Implementation plan and checklist.

[ManukMinasyan]

All 4 review comments addressed in dbc3aab:

• Import consolidation (comments 1, 2, 4): All use statements moved to the top of the test file before any it() calls.
• HTML content assertions (comment 3): Added assertSeeHtml to all 3 rendering tests to verify description text is present in rendered output.