[release]: upgrade stable version to react 19

[halvaradop]

Description

This issue outlines the official upgrade of the stable React version used in the library—from React 18 to React 19. Initially, the library was built using React 18 (published on [insert React 18 release date]) as it was the latest stable version at the time. As React 19 (released on [insert React 19 release date]) introduced significant improvements and changes, the decision was made to upgrade to React 19. However, this upgrade required handling multiple breaking changes that affected the components and core packages of the library.

---

Breaking Changes Between React 18 and React 19

1. React.cloneElement Behavior

   • In React 18, it was acceptable to pass undefined props to cloneElement.
   • React 19 throws errors when undefined props are passed, which caused build issues—particularly within the @halvaradop/ui-core package and its Slot component.

2. forwardRef Usage

   • In React 18, forwardRef was used widely to forward references.
   • In React 19, ref forwarding has improved and is more SSR-friendly. This resulted in a simplification, where forwardRef usage was reduced or removed in many components.

3. Client Components Directive

   • React 19 enhances SSR (server-side rendering) support.
   • To explicitly mark client-side components, developers must add "use client" at the top of the file when using React hooks (which are not supported on the server). This directive is now required in several files across the library.

---

Versioning Strategy

To support both major React versions, the library temporarily maintained two separate branches:

• master: Contained the stable version (React 18)
• beta: Contained the React 19 version under development

At the time React 19 was still in release candidate status, React 18 was kept as the stable default. However, now that React 19 is officially stable, the decision has been made to:

• Promote React 19 as the new stable version
• Reclassify React 18 as the legacy version

This transition was discussed and documented in detail in issue #X.

---

Supporting Changes for the Upgrade

To ensure a smooth and professional transition, the following changes were introduced across the repository:

• New and updated documentation:
  • README.md
  • ARCHITECTURE.md
  • CONTRIBUTING.md
  • CHANGELOG.md for each package (following Keep a Changelog and Semantic Versioning)
• New modular package structure:
  • @halvaradop/ui-utils
  • @halvaradop/ui-core
  • @halvaradop/ui-slot
• Build process improvements and automated publishing using Bash scripts

---

Purpose of This Issue

This issue serves as the main reference point documenting:

• The motivation and reasoning behind the upgrade
• The major breaking changes that were addressed
• The steps taken to modernize and improve the library
• The versioning strategy and current status

---

[halvaradop]

Following the recent updates in the master branch aimed at preparing for the stable upgrade to React 19 — including package fixes, performance improvements, accessibility enhancements, and more — these changes have been synchronized with the sync/beta branch. This branch reflects the latest progress from master, ensuring all enhancements are aligned across both versions. The synchronization and related documentation are available in #160.

Versioning Strategy

The library follows a clear versioning and release strategy, structured as follows:

Branch	React Version	Format	NPM Tag
master	React 18	0.y.z	latest
master	React 18	0.y.z-rc.1	rc
beta	React 19	0.y.z-beta.n	beta
beta	React 19	1.0.0-next.1	next

This approach adheres to Semantic Versioning principles and uses NPM tags to clearly define the purpose of each release:

• rc and next tags are used to validate stability on React 18 and React 19 respectively, before promoting React 19 to stable and marking React 18 as legacy.

Release Candidates

• The rc prepublish was introduced in #170 via commit 89c14c9
• The next prepublish was handled in #160 via commit 6eef05f

Next Steps

Once the release candidates (rc and next) have been validated in real environments, the next steps will be:

• Promote React 19 to the new stable version
• Mark React 18 as legacy

This transition will be reflected in all future releases and documentation updates accordingly.

[halvaradop]

• chore(release): bump to v1.0.0 for React 19 compatibility #182