Improve `'num'` prop's UI/UX: refine variants, add new attributes, RFC on new variants

[luisvasq]

📌 Tasks

• Review and refine UI/UX for all existing 'num' prop variants
• Update related API examples
• Update docs and validator (cave_utils)

---

🚀 New attributes introduced in 3.3.0

• fullWidth ('field' & 'slider' variants only):
  Follows MUI’s fullWidth behavior. However, it defaults to true in 3.3.0 to maintain backward compatibility. Will default to false in 4.0.0.

• readOnly ('field' variant only):
  Prevents value changes while retaining the visual style of an enabled prop, i.e. similar behavior to enabled: false, but styled as enabled.

• placement (all variants):
  Aligns the prop within its container. Valid options: 'topLeft', 'topCenter', 'topRight', 'center', 'left', 'right', 'bottomLeft', 'bottomCenter', and 'bottomRight'.

• propStyle (all variants):
  Escape hatch for applying custom styles directly to the prop (not its container).

  • Named propStyle to avoid confusion with the existing style key, which currently targets the container via the layout structure.
  • Will be renamed to style in 4.0.0 as part of a prop-level style refactor.

---

🚀 New attributes introduced in 3.5.0

• spinner ('field' & 'slider' variants only):
  Controls the visibility and placement of the spin buttons used for incrementing/decrementing values. Defaults to right.

  • Open question: Should this behavior be always-on for numeric inputs, removing the need for this explicit attribute?
  • Valid options:
    • 'right' | true: Displays the spinner on the right side of the input field.
    • 'left': Displays the spinner on the left side of the input field.
    • 'leftAndRight': Displays a decrement button on the left and an increment button on the right, centering the input value between them.
    • false: Hides the spinner control entirely.

• step ('field' & 'slider' variants):
  Defines the default increment/decrement step when the value changes (e.g. via arrow keys, spinner buttons, or drag interactions).

  • Default: 1

• smallStep ('field' & 'slider' variants):
  Defines a finer-grained step used for more precise adjustments (typically triggered via modifier keys such as Alt).

  • Default: A decimal value derived from numberFormat.precision (i.e. $10^{-<precision>}$); if not available, falls back to 0.1.
  • Example: if numberFormat.precision is 3, the default smallStep is 0.001.

• largeStep ('field' & 'slider' variants):
  Defines a larger increment step for faster value changes (typically triggered via modifier keys such as Shift).

  • Default: 10

• scale ('slider' variant only):
  Allows value scaling using linear (default), log, pow, exp, etc.

  • Considering piecewise scaling. I'm not sure if we have enough use cases that justify it.

• scaleParams ('slider' variant only):
  Supplies extra config for scale, e.g. exponent for pow, base for log or exp.

  • If piecewise is added, this may include cutoff values and nested scale definitions.

---

💬 RFC

• Should we introduce any new variants or attributes for the 'num' prop?
• Are there existing UX or styling issues that we should handle?
• Is the spinner attribute necessary, or should it be integrated into default 'num' behavior?
• How should step attributes behave under non-linear scale transformations?

Feel free to share thoughts or feedback.