Summary

To improve support for right-to-left (RTL) languages like Hebrew and Arabic, we propose replacing physical direction values ("left" and "right") with logical equivalents ("start" and "end") across our components. This aligns with modern CSS practices, specifically the use of CSS Logical Properties and Values, and enhances consistency in our component APIs.

Problem Statement

Our components currently use physical direction values ("left" and "right") to specify the alignment of text or indicators (e.g., checkboxes, radio buttons) relative to labels. These values become confusing in RTL languages, where layout directions are reversed.

We also have an Alignment type shared across components, but its valid values differ. For example:

• In <Button>, the alignText prop accepts "left", "right", or "center".
• In <Checkbox>, the alignIndicator prop uses the same Alignment type but only "left" or "right" are valid. Passing "center" has no effect since center alignment isn't applicable for the indicator on checkbox.

This inconsistency can lead to confusion and unexpected behavior.

Proposal

We propose the following changes:

1. Expand Alignment to include logical direction values

// Current
type Alignment = "center" | "left" | "right";

// Updated
type Alignment = "center" | "left" | "right" | "start" | "end";

2. Map "start" and "end" to existing implementations

• "start" maps to Classes.ALIGN_LEFT.
• "end" maps to Classes.ALIGN_RIGHT.

This mapping currently occurs via Classes.alignmentClass(...)

3. Deprecate physical direction values

• Mark "left" and "right" as deprecated in all components using Alignment.
• Provide deprecation warnings in development mode.
• Update documentation to promote "start" and "end".

4. Introduce a new TextAlignment type

type TextAlignment = "center" | "start" | "end";

Use TextAlignment in <Button> and <ButtonGroup> components for text alignment, separating it from Alignment used in other components where "center" isn't valid.

5. Future: Remove physical values and update class names

In a future major version:

• Remove "left", "right", and "center" values from Alignment, leaving only "start" and "end".

// Before
type Alignment = "center" | "left" | "right" | "start" | "end";

// After
type Alignment = "start" | "end"

• Update class names:
  • Classes.ALIGN_LEFT → Classes.ALIGN_START
  • Classes.ALIGN_RIGHT → Classes.ALIGN_END
• Replace Alignment type with TextAlignment in <Button> and <ButtonGroup>.

Plan of Action

Phase 1: Immediate Changes

• Add "start" and "end" to Alignment.
• Introduce TextAlignment.
• Deprecate "left" and "right" in components using Alignment and add deprecation warnings in development mode.
• Revise documentation and examples to use "start" and "end".
• Include clear migration guidelines in release notes.
• Provide a codemod script to automate the replacement of "left"/"right" with "start"/"end" in existing codebases.

Phase 2: Future Breaking Changes

• Remove "left" and "right", and "center" values from Alignment.
• Rename CSS classes and use logical CSS properties in implementation:
  • Classes.ALIGN_LEFT → Classes.ALIGN_START
  • Classes.ALIGN_RIGHT → Classes.ALIGN_END
• Replace Alignment type with TextAlignment in <Button> and <ButtonGroup> components.

These changes will constitute a breaking change and be scheduled for a major version update.

Affected Components

• <AnchorButton>
• <Button>
• <ButtonGroup>
• <Checkbox>
• <CheckboxCard>
• <NavbarGroup>
• <Radio>
• <RadioCard>
• <Switch>
• <SwitchCard>

References

• MDN: CSS Logical Properties and Values
• MDN: text-align Property
• CSS Logical Properties Draft