@marwes-ui/react 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img alt="Marwes Design System" src="https://raw.githubusercontent.com/niklas-westman/marwes/main/.github/assets/banner-light.png" width="100%" style="border-radius: 40px;">
+<img alt="Marwes Design System" src="https://raw.githubusercontent.com/niklas-westman/marwes/main/.github/assets/banner.png" width="100%" style="border-radius: 40px;">
 
 <br>
 <br>
@@ -312,6 +312,72 @@ export function App() {
 
 `defaultMode` sets the initial uncontrolled mode. `toggleMode()` updates the provider, so Marwes components, preset CSS, and custom app styles that use `--mw-*` variables all move together without duplicating local theme state.
 
+### System And Persisted Preference
+
+`mode` is always the rendered visual mode: `ThemeMode.light` or `ThemeMode.dark`. `preference` is the app or user choice: `ThemeMode.light`, `ThemeMode.dark`, or `"system"`. Use `preference` and `defaultPreference` when your UI needs a system option; keep using `mode`, `defaultMode`, and `onModeChange` when you only need concrete light/dark compatibility.
+
+```tsx
+import { Button, ButtonVariant, MarwesProvider, ThemeMode, useThemeMode } from "@marwes-ui/react"
+
+function ThemeMenu() {
+  const { mode, preference, systemMode, isSystem, setPreference, setMode } = useThemeMode()
+
+  return (
+    <div>
+      <p>
+        Rendering {mode}; preference is {preference}; system is {systemMode}.
+      </p>
+      <Button variant={ButtonVariant.secondary} onClick={() => setPreference("system")}>
+        Use system
+      </Button>
+      <Button variant={ButtonVariant.secondary} onClick={() => setMode(ThemeMode.dark)}>
+        Use dark
+      </Button>
+      {isSystem ? "Following system" : null}
+    </div>
+  )
+}
+
+export function App() {
+  return (
+    <MarwesProvider
+      defaultPreference="system"
+      storageKey="marwes-theme"
+      enableSystem
+    >
+      <ThemeMenu />
+      <AppShell />
+    </MarwesProvider>
+  )
+}
+```
+
+`useThemeMode().mode` never returns `"system"`; it is always the concrete mode Marwes rendered. `useThemeMode().preference` returns the active app/user preference, and `setPreference("system")` is the system-capable setter. `setMode(mode)` remains a concrete light/dark convenience.
+
+`storageKey` is opt-in and defaults to `false`. Storage reads and writes are failure-safe, so private browsing or unavailable storage will fall back to normal provider state. `enableSystem` defaults to `true`; set it to `false` to avoid `matchMedia` detection and resolve `"system"` through the light fallback.
+
+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.
+
 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

@@ -1,26 +1,41 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ThemeInput, ThemeMode, FontLoadingConfig, ResolvedTheme, ButtonOptions, InputOptions, SelectOptions, SelectAppearance as SelectAppearance$1, SelectOption as SelectOption$1, TextareaOptions, RichTextOptions, InputOtpOptions, CurrencyCode, iconRegistry, IconSize, IconStrokeWidth, AvatarOptions, CheckboxProps as CheckboxProps$1, DividerOptions, DividerSize, DividerOrientation, SpinnerOptions, SpacingOptions, SpacingSize, HeadingOptions, HeadingSize, ParagraphOptions, ParagraphSize, ToastOptions, ToastVariant, ToastIntent, ToastPlacement, TooltipOptions, IconNameType, RadioOptions, BadgeOptions, SwitchOptions, SliderOptions, TabOptions, DialogOptions } from '@marwes-ui/core';
-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, ToneName, createFontStack, mwAvailableFonts, mwFontFallbacks, mwGoogleFontFamilies, mwStyledTheme, mwThemeVarNames, mwThemeVars, mwVar } from '@marwes-ui/core';
+import { ThemeInput, ThemePreference, ThemeMode, FontLoadingConfig, ResolvedTheme, ButtonOptions, InputOptions, SelectOptions, SelectAppearance as SelectAppearance$1, SelectOption as SelectOption$1, TextareaOptions, RichTextOptions, InputOtpOptions, CurrencyCode, iconRegistry, IconSize, IconStrokeWidth, AvatarOptions, CheckboxProps as CheckboxProps$1, DividerOptions, DividerSize, DividerOrientation, SpinnerOptions, SpacingOptions, SpacingSize, HeadingOptions, HeadingSize, ParagraphOptions, ParagraphSize, ToastOptions, ToastVariant, ToastIntent, ToastPlacement, TooltipOptions, IconNameType, RadioOptions, BadgeOptions, SwitchOptions, SliderOptions, TabOptions, DialogOptions } from '@marwes-ui/core';
+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;
+    preference?: ThemePreference;
     defaultMode?: ThemeMode;
     mode?: ThemeMode;
     fontLoading?: FontLoadingConfig;
+    onPreferenceChange?: (preference: ThemePreference) => void;
     onModeChange?: (mode: ThemeMode) => void;
+    storageKey?: string | false;
+    enableSystem?: boolean;
+    target?: ThemeTarget;
+    attribute?: ThemeAttribute;
+    disableTransitionOnChange?: boolean;
     children: React.ReactNode;
 };
-declare function MarwesProvider({ theme, defaultMode, mode: controlledMode, fontLoading, onModeChange, 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;
 
 type ThemeModeContextValue = {
     mode: ThemeMode;
+    preference: ThemePreference;
+    systemMode: ThemeMode;
     setMode: (mode: ThemeMode) => void;
+    setPreference: (preference: ThemePreference) => void;
     toggleMode: () => void;
     isDark: boolean;
     isLight: boolean;
+    isSystem: boolean;
 };
 declare function useThemeMode(): ThemeModeContextValue;