@marwes-ui/react 1.0.2 → 1.0.4

package/README.md

@@ -358,6 +358,43 @@ export function App() {
 
 This layer does not provide SSR no-flash behavior. Server output can still render the fallback mode before the client applies a stored or system preference. Use it for client-side preference and persistence, not for a no-flash SSR guarantee.
 
+### Root Target Sync
+
+By default Marwes keeps theme state scoped to the provider element. If your app shell also needs the resolved mode on `html` or `body`, set `target` and `attribute`:
+
+```tsx
+<MarwesProvider
+  defaultPreference="system"
+  storageKey="marwes-theme"
+  target="html"
+  attribute="class"
+  disableTransitionOnChange
+>
+  <AppShell />
+</MarwesProvider>
+```
+
+`target` can be `"provider"`, `"html"`, or `"body"`. `attribute` can be `"class"`, `"data-theme"`, or `"data-mode"`. Class mode only adds the active `light` / `dark` class and removes the opposite one; unrelated classes are preserved. The provider root still keeps `mw-theme--light` / `mw-theme--dark` and provider-scoped `--mw-*` variables in every target mode.
+
+Use one global-target provider per app shell. If multiple providers target `html` or `body`, deciding which provider owns that global element is app-owned behavior.
+
+### Tailwind And shadcn Compatibility
+
+Marwes is compatible with Tailwind and shadcn-style dark variants through `target="html" attribute="class"`. App-owned Tailwind tokens can also reference Marwes `--mw-*` variables when rendered inside the provider subtree.
+
+```tsx
+<MarwesProvider
+  defaultPreference="system"
+  storageKey="marwes-theme"
+  target="html"
+  attribute="class"
+>
+  <AppShell />
+</MarwesProvider>
+```
+
+Read the [Tailwind and shadcn integration guide](https://github.com/niklas-westman/marwes/blob/main/docs/guides/tailwind-shadcn-integration.md) for Tailwind v3/v4 examples, token mapping, provider-scoped variable limits, and the SSR no-flash boundary.
+
 For a simple brand pass, override shared values once and let Marwes fill the rest. If your product needs different brand colors in light and dark mode, control `mode` and switch between two small `ThemeInput` override objects:
 
 ```tsx

package/dist/index.d.ts

@@ -3,6 +3,9 @@ import { ThemeInput, ThemePreference, ThemeMode, FontLoadingConfig, ResolvedThem
 export { AvatarSize, AvatarType, BadgeVariant, ButtonAction, ButtonSize, ButtonVariant, Density, FontLoadingConfig, FontLoadingMode, FontLoadingOptions, IconName, MwAvailableFont, MwFontFallback, MwGoogleFontFamily, MwStyledTheme, MwThemeVarName, MwThemeVarNames, MwThemeVarReference, MwThemeVars, ResolvedTheme, SpacingSize, Spacings, SwitchSize, Theme, ThemeInput, ThemeMode, ThemePreference, ToneName, createFontStack, mwAvailableFonts, mwFontFallbacks, mwGoogleFontFamilies, mwStyledTheme, mwThemeVarNames, mwThemeVars, mwVar } from '@marwes-ui/core';
 import * as React from 'react';
 
+type ThemeTarget = "provider" | "html" | "body";
+type ThemeAttribute = "class" | "data-theme" | "data-mode";
+
 type MarwesProviderProps = {
     theme?: ThemeInput;
     defaultPreference?: ThemePreference;
@@ -14,9 +17,12 @@ type MarwesProviderProps = {
     onModeChange?: (mode: ThemeMode) => void;
     storageKey?: string | false;
     enableSystem?: boolean;
+    target?: ThemeTarget;
+    attribute?: ThemeAttribute;
+    disableTransitionOnChange?: boolean;
     children: React.ReactNode;
 };
-declare function MarwesProvider({ theme, defaultPreference, preference: controlledPreference, defaultMode, mode: controlledMode, fontLoading, onPreferenceChange, onModeChange, storageKey, enableSystem, children, }: MarwesProviderProps): react_jsx_runtime.JSX.Element;
+declare function MarwesProvider({ theme, defaultPreference, preference: controlledPreference, defaultMode, mode: controlledMode, fontLoading, onPreferenceChange, onModeChange, storageKey, enableSystem, target, attribute, disableTransitionOnChange, children, }: MarwesProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function useTheme(): ResolvedTheme;
 

package/dist/index.js

@@ -103,6 +103,42 @@ function writeStoredThemePreference(storageKey, preference) {
   } catch {
   }
 }
+function applyModeAttribute({
+  target,
+  providerElement,
+  mode,
+  attribute
+}) {
+  const element = getTargetElement(target, providerElement);
+  if (!element) return;
+  if (attribute === "class") {
+    const oppositeMode = mode === ThemeMode.dark ? ThemeMode.light : ThemeMode.dark;
+    element.classList.remove(oppositeMode);
+    element.classList.add(mode);
+    return;
+  }
+  element.setAttribute(attribute, mode);
+}
+function withoutModeTransitions(callback) {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    callback();
+    return;
+  }
+  const style = document.createElement("style");
+  style.dataset.marwesDisableTransitions = "true";
+  style.textContent = "* { transition: none !important; }";
+  document.head.appendChild(style);
+  callback();
+  window.getComputedStyle(document.body);
+  window.requestAnimationFrame(() => {
+    style.remove();
+  });
+}
+function getTargetElement(target, providerElement) {
+  if (target === "provider") return providerElement;
+  if (typeof document === "undefined") return null;
+  return target === "html" ? document.documentElement : document.body;
+}
 function MarwesProvider({
   theme,
   defaultPreference,
@@ -114,6 +150,9 @@ function MarwesProvider({
   onModeChange,
   storageKey = false,
   enableSystem = true,
+  target = "provider",
+  attribute = "class",
+  disableTransitionOnChange = false,
   children
 }) {
   const rootRef = React2.useRef(null);
@@ -176,6 +215,22 @@ function MarwesProvider({
       applyThemeToElement(rootRef.current, resolved);
     }
   }, [resolved]);
+  React2.useEffect(() => {
+    if (target === "provider") return;
+    const apply = () => {
+      applyModeAttribute({
+        target,
+        providerElement: rootRef.current,
+        mode: activeMode,
+        attribute
+      });
+    };
+    if (disableTransitionOnChange) {
+      withoutModeTransitions(apply);
+      return;
+    }
+    apply();
+  }, [activeMode, attribute, disableTransitionOnChange, target]);
   React2.useEffect(() => {
     loadThemeFonts(resolved, fontLoading);
   }, [resolved, fontLoading]);