feat: enhance theme detection with auto mode and multiple strategies

[brionmario]

Purpose

This pull request introduces a major refactor and enhancement to the theme detection and switching logic across the JavaScript, Browser, and React packages. It unifies and extends theme detection strategies, replacing the old 'class' mode with a more flexible 'auto' mode that supports detection via data attributes, CSS classes, and system preferences, with configurable strategy and priority. The React ThemeProvider and related APIs are updated to leverage these new capabilities, providing more robust and customizable theme handling.

Theme detection and configuration enhancements:

• Added a new ThemeDetectionStrategy type and expanded the ThemeDetection interface to support detection via data attributes, CSS classes, and system preferences, with configurable strategy and priority ('auto' mode now replaces 'class' mode). [1] [2]
• Introduced new observer utilities: createDataAttributeObserver and createAutoObserver for robust theme change detection based on the configured strategy and priority. [1] [2]
• Refactored detectThemeMode to support the new strategies and fallback logic, and deprecated the 'class' mode in favor of 'auto'. [1] [2]
• Updated exports and types to reflect new capabilities, including exporting ThemeDetectionStrategy and BrowserThemeDetection. [1] [2]

React ThemeProvider and context updates:

• Updated the ThemeProvider to use the new 'auto' mode by default, support the new detection strategies, and clean up observers properly. The old 'class' and 'branding' modes are removed or replaced. [1] [2] [3] [4]
• Updated the ThemeContext and related types to use the new ThemeMode and detection logic.

API and type improvements:

• Improved the createTheme API to exclude runtime detection properties from its config, clarifying its intended use.
• Updated theme config and detection types for better clarity and extensibility. [1] [2]

Code quality and consistency:

• Refactored code for better naming, type safety, and maintainability (e.g., consistent use of DOMTokenList, explicit type annotations, and improved observer setup/cleanup). [1] [2]

These changes collectively provide a more flexible, reliable, and extensible foundation for theme management in applications using these packages.

Related Issues

• Fixes feat: detect the application color scheme automatically based on common strategies (class based, data attr based) #236

Related PRs

• N/A

Checklist

• Followed the CONTRIBUTING guidelines.
• Manual test round performed and verified.
• Documentation provided. (Add links if there are any)
• Unit tests provided. (Add links if there are any)

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines?
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets?

[asgardeo-github-bot]

⚠️ No Changeset found

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go.

If these changes should result in a version bump, you need to add a changeset.

Refer Release Documentation to learn how to add a changeset.