[FEATURE] UI customization. Add Box primitive component

[zhuje]

Description

Create Box primitive component as part of this initiative perses/perses#3570

Previous PRs towards this initiative:

• [FEATURE] UI Customization: Component Provider  #241
• [FEATURE] UI Customization. Add next component directory with Button and Alert primitives #213
• [FEATURE] create @perses-dev/design-tokens package #198

Ladel Story showcasing Box component

Checklist

• Pull request has a descriptive title and context useful to a reviewer.
• Pull request title follows the [<catalog_entry>] <commit message> naming convention using one of the
  following catalog_entry values: FEATURE, ENHANCEMENT, BUGFIX, BREAKINGCHANGE, DOC,IGNORE.
• All commits have DCO signoffs.

UI Changes

• Changes that impact the UI include screenshots and/or screencasts of the relevant changes.
• Code follows the UI guidelines.
• E2E tests are stable and unlikely to be flaky.
  See e2e docs for more details. Common issues include:
  • Is the data inconsistent? You need to mock API requests.
  • Does the time change? You need to use consistent time values or mock time utilities.
  • Does it have loading states? You need to wait for loading to complete.

[zhuje]

HOLD

TDepends on this #300 merging first to fix CI issue due BREAKINGCHANGES with Node upgrade and removal of CommonJS

[jgbernalp]

Suggested change

	p?: SpacingToken;
	p?: Responsive<SpacingToken>;

in which SpacingToken could be something similar to

// 1. Define your supported breakpoints
export type Breakpoint = 'default' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';

// 2. Create a mapped type where each breakpoint is an optional key for type T
export type ResponsiveObject<T> = {
  [Key in Breakpoint]?: T;
};

// 3. Create the final generic type: either a direct value OR the responsive object
export type Responsive<T> = T | ResponsiveObject<T>;

[zhuje]

Addressed. Responsive<T>, ResponsiveObject<T>, and Breakpoint are defined in the shared primitive system utility. Box spacing props now use Responsive<SpacingToken>.

[jgbernalp]

we might need to adjust previously created components to include this, can you create a follow UP PR with this.

[zhuje]

I reviewed the existing primitives and their usage. I do not think Button, Alert, or Divider need responsive props by default.

Their responsive behavior should be controlled by the surrounding layout. A parent container can change direction, wrap content, adjust available space, or hide controls at breakpoints, while these primitives retain consistent behavior and accessible sizing. Divider already adjusts to its parent: horizontal dividers use the full available width, and vertical dividers use the available height.

The shared responsive utility is most useful for layout primitives such as Box, where properties like display, flexDirection, gap, and width often need to change across breakpoints. We can add responsive behavior to another primitive later if a specific product requirement shows that it is needed.

[jgbernalp]

The problem of adding later is that it might be a breaking api change, more difficult to change for users that use the new components. I find valuable to include responsiveness on the button sizes for example: In mobile you might want to use an md button, aligning with a11y so the button fits in a human thumb, but on large screens you might want to use an xs button as the mouse might allow smaller buttons to be clicked. I agree the divider does not need responsiveness as it is already designed with that in mind.

[zhuje]

Follow up PR

• Button [FEATURE] UI Customization. Modify Button with responsive resizing.  #352
• Alert [FEATURE] UI Customization. Modify Alert with responsive resizing  #353