[Request]: Evolve `@clack/prompts` `box()` for broader layout interoperability

[dreyfus92]

Is your feature request related to a problem? Please describe.

@clack/prompts box() and boxen solve similar CLI layout problems but have different APIs and layout semantics, which makes migration and parity expectations confusing.

Clack box() is currently stream-first (void return with output.write) and supports a focused subset of features (width, titleAlign, contentAlign, titlePadding, contentPadding, rounded, formatBorder, withGuide). For teams moving from boxen(text, options?), expected options like margin shorthand semantics, float positioning, richer border styles, and clearer compatibility guarantees are not first-class yet.

This leads to custom wrappers for spacing/offset behavior and ambiguity around which differences are intentional vs missing.

Describe the solution you'd like

Introduce a documented compatibility strategy and phased implementation that improves interoperability while preserving native Clack behavior by default.

Proposed scope:

• Define a compatibility contract for box-style options:
  • supported directly,
  • supported via adapter,
  • intentionally omitted.
• Keep existing box(message, title, opts) behavior unchanged for current users.
• Add a compatibility-oriented API surface (name TBD), potentially:
  • formatBox(text, options?) => string, and/or
  • printBox(text, options?) => void.
• Prioritize geometry/layout parity:
  • margin and padding object + numeric shorthand (top/bottom = n, left/right = 3n),
  • optional float alignment (left | center | right),
  • title/width behavior with explicit fixture tests.
• Expand styling parity where practical:
  • border style presets,
  • border/background color options in compatibility mode.
• Decide and document support/defer status for height and fullscreen.
• Add fixture-based compatibility tests and README migration guidance.

Acceptance goals:

• Clear migration path for common box-style callsites.
• No regressions in current native Clack box() behavior.
• Explicit docs for intentional differences and non-goals.

Describe alternatives you've considered

• Keep current box() unchanged and rely on app-level wrappers.
  • Low API churn, but repeats custom logic and keeps parity unclear.
• Make native box() fully mimic boxen behavior.
  • Familiar to migrators, but higher regression risk for existing Clack prompt UX.
• Document differences only (no new API/features).
  • Low effort, but does not solve missing primitives or wrapper burden.

Preferred approach: add a compatibility layer/adapter with clear docs/tests, rather than changing native defaults.

Additional context

Current behavior already covers guide handling, title/content alignment, truncation, rounded/square corners, and wide character rendering.

Implementation checklist:

• Write feature-by-feature compatibility matrix.
• Decide public API names for compatibility mode.
• Implement margin/padding shorthand + per-side objects.
• Implement optional float alignment.
• Add border style preset mapping.
• Add color options for compatibility mode.
• Decide support/defer status for height and fullscreen.
• Add fixture-based compatibility tests.
• Add migration guidance to README.

cc. @natemoo-re @43081j

[43081j]

im not sure this is the right direction 👀

when i added the box prompt, i did it the "clack way" because i'd argue boxen is poorly designed. it being overly configurable is part of why its such a bloated package (amongst other reasons). now is our chance to do it better.

i think the migration path being slightly less drop-in is worth it to avoid turning clack into the mess that boxen is.

as time goes on, it probably makes sense to slightly expand the functionality but in a well designed way. e.g. we may one day want a way to pass in custom borders, just like how spinner accepts custom frames.

it is better to design it our way than adopt tech debt from other libraries i think