Drupal-side integration of |resizer_aspect (sub-issue of #16)

[parisek]

Sub-issue of #16 — Drupal-side integration

Tracking issue for landing |resizer_aspect in Drupal projects (parallel to the WordPress / timber-kit implementation specified in #16, and the styleguide-side implementation in parisek/styleguide#16).

Context

Issue #16 specifies a new |resizer_aspect Twig filter that classifies a source image's aspect orientation (landscape / portrait / square, tolerance 0.1, missing-metadata → landscape fallback) and routes to the appropriate tuple set for image resizing. WordPress production gets Helpers::classifyAspect() + Helpers::resizeImageAspect() in parisek/timber-kit. Styleguide demo surface gets a parallel registration in parisek/styleguide's bundled filters.

Drupal projects in the parisek org also use the same |resizer / |merge_resizer Twig pipeline (per .claude/rules/drupal/ docs in consuming projects), but there's no shared kit equivalent of Parisek\TimberKit\Helpers for Drupal at the moment — the resizer registration lives per-project, typically inside a project-local custom module that wires Drupal's image-style API into a Twig filter.

This sub-issue tracks the open questions for landing |resizer_aspect consistently on the Drupal side.

Open design questions

1. Where does the shared classification logic live?

   • Option A: New package parisek/drupal-kit (mirror of timber-kit) — biggest infra change, but matches the org's WP-side convention.
   • Option B: Add CMS-agnostic classifyAspect() to parisek/styleguide (the only existing CMS-agnostic package in the org) and have Drupal projects depend on it.
   • Option C: Per-project Drupal custom module registers the filter — no shared package, vocabulary + tolerance documented but each project ships its own ~30 lines of PHP.
   • Lean: Option B — styleguide already ships Helpers-like primitives (classifyAspect would fit), is already used by Drupal styleguide consumers, and avoids spinning up a new package for one feature.

2. What's the equivalent of WordPress's apply_filters('resizer_aspect_tolerance', 0.1)?

   • Drupal doesn't have a direct equivalent to WP's filter hook system; closest analogs are event dispatchers, hook implementations, or service container parameters.
   • Simplest: a global config setting resizer.aspect_tolerance that the filter reads at runtime, falling back to 0.1.
   • Alternative: drop the tolerance override entirely on the Drupal side and hardcode 0.1 (matches the styleguide sub-issue's "no filter mechanism" decision).
   • Lean: hardcode 0.1 unless a real project asks — YAGNI.

3. Which Drupal projects in the org currently use cropped tuples that would benefit?

   • Need to survey the active Drupal projects under ~/Sites/ to see which |resizer call sites have fixed-aspect crops vs scale-only.
   • This survey informs whether the integration is urgent (active project pain) or future-prep (no current consumer hitting the issue).

What's blocking

This sub-issue is dependent on the WordPress side landing first in parisek/timber-kit. Once Helpers::classifyAspect() is finalised there (vocab, tolerance, fallback semantics), the Drupal side mirrors the contract.

Until then, this issue captures:

• ✓ Shared spec (classification vocab, tolerance default, missing-metadata fallback) — from Aspect-aware image cropping in Helpers::resizeImage / |resizer — brainstorm #16
• ✓ Composition with |merge_resizer — from Aspect-aware image cropping in Helpers::resizeImage / |resizer — brainstorm #16
• ✓ Acceptance for the Drupal-side helper to behave identically

What it doesn't capture yet (deliberately deferred):

• ✗ Implementation venue (Option A / B / C above) — decide once at least one active Drupal project hits the pain point
• ✗ Tolerance override mechanism — decide alongside the venue
• ✗ Test fixture — once venue is decided, write tests against that runtime

See also

• Parent issue: parisek/timber-kit#16 — WordPress / kit spec, decided
• Sibling sub-issue: parisek/styleguide#16 — styleguide demo surface, decided

[parisek]

Concrete Drupal venue chosen: portadesign/drupal-base#7 (in-base module first; lift to a shared CMS-agnostic package if a second Drupal consumer surfaces). This upstream tracking issue can stay open as the cross-runtime umbrella, or be closed in favour of the concrete one — your call.

[parisek]

Design pivot heads-up ✏️

Both upstream Twig surfaces (parisek/timber-kit and parisek/styleguide) unified |resizer_aspect back into a polymorphic |resizer before timber-kit tagged a release. See:

• parisek/timber-kit#20 (the WP-side unification)
• parisek/styleguide#17 (parallel in the styleguide)

The Drupal-side work, when it lands, should mirror the unified shape — single |resizer filter polymorphic on its argument structure, not a separate |resizer_aspect filter. The concrete implementation issue at portadesign/drupal-base#7 has been updated accordingly.