@marwes-ui/vue 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>
@@ -309,6 +309,71 @@ import ThemeToggle from "./theme-toggle.vue"
 
 `default-mode` 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 `default-preference` when your UI needs a system option; keep using `mode`, `default-mode`, and `on-mode-change` when you only need concrete light/dark compatibility.
+
+```vue
+<script setup lang="ts">
+import { Button, ButtonVariant, ThemeMode, useThemeMode } from "@marwes-ui/vue"
+
+const { mode, preference, systemMode, isSystem, setPreference, setMode } = useThemeMode()
+</script>
+
+<template>
+  <p>Rendering {{ mode }}; preference is {{ preference }}; system is {{ systemMode }}.</p>
+  <Button :variant="ButtonVariant.secondary" @click="setPreference('system')">
+    Use system
+  </Button>
+  <Button :variant="ButtonVariant.secondary" @click="setMode(ThemeMode.dark)">
+    Use dark
+  </Button>
+  <span v-if="isSystem">Following system</span>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import { MarwesProvider } from "@marwes-ui/vue"
+import ThemeMenu from "./theme-menu.vue"
+</script>
+
+<template>
+  <MarwesProvider default-preference="system" storage-key="marwes-theme" enable-system>
+    <ThemeMenu />
+    <AppShell />
+  </MarwesProvider>
+</template>
+```
+
+`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.
+
+`storage-key` 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. `enable-system` 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`:
+
+```vue
+<template>
+  <MarwesProvider
+    default-preference="system"
+    storage-key="marwes-theme"
+    target="html"
+    attribute="class"
+    disable-transition-on-change
+  >
+    <AppShell />
+  </MarwesProvider>
+</template>
+```
+
+`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:
 
 ```vue

package/dist/index.d.ts

@@ -1,40 +1,71 @@
 import * as vue from 'vue';
 import { ComputedRef, VNodeChild } from 'vue';
 import * as _marwes_ui_core from '@marwes-ui/core';
-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';
+
+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;
 };
 declare const MarwesProvider: vue.DefineComponent<{
     mode?: any;
+    target?: any;
+    attribute?: any;
     theme?: any;
+    defaultPreference?: any;
+    preference?: any;
     defaultMode?: any;
     fontLoading?: any;
+    onPreferenceChange?: any;
     onModeChange?: any;
+    storageKey?: any;
+    enableSystem?: any;
+    disableTransitionOnChange?: any;
 }, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<{
     mode?: any;
+    target?: any;
+    attribute?: any;
     theme?: any;
+    defaultPreference?: any;
+    preference?: any;
     defaultMode?: any;
     fontLoading?: any;
+    onPreferenceChange?: any;
     onModeChange?: any;
+    storageKey?: any;
+    enableSystem?: any;
+    disableTransitionOnChange?: any;
 }> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
 declare function useTheme(): ResolvedTheme;
 
 type ThemeModeContextValue = {
     mode: ComputedRef<ThemeMode>;
+    preference: ComputedRef<ThemePreference>;
+    systemMode: ComputedRef<ThemeMode>;
     setMode: (mode: ThemeMode) => void;
+    setPreference: (preference: ThemePreference) => void;
     toggleMode: () => void;
     isDark: ComputedRef<boolean>;
     isLight: ComputedRef<boolean>;
+    isSystem: ComputedRef<boolean>;
 };
 declare function useThemeMode(): ThemeModeContextValue;
 

package/dist/index.js

@@ -1,7 +1,7 @@
 import '@marwes-ui/presets/firstEdition/styles.css';
-import { ThemeMode, resolveThemeInput, resolveIconSize, resolveIconStrokeWidth, iconRegistry, resolveIconA11y, createSpinnerRecipe, createButtonRecipe, ButtonAction, ButtonVariant, IconName, createInputRecipe, createSelectRecipe, resolveSelectMode, createTextareaRecipe, createRichTextRecipe, resolveRichTextAllowedFormats, normalizeRichTextHtml, isRichTextHtmlEmpty, paragraphRecipe, buildInputFieldA11yIds, sanitizeInputOtpValue, createInputOtpRecipe, buildRichTextFieldA11yIds, buildCurrencyHelperText, getCurrencySymbol, sanitizeCurrencyValue, createAvatarRecipe, createPurposeSemanticAttributes, checkboxRecipe, buildCheckboxFieldA11yIds, buildCheckboxGroupFieldA11yIds, createDividerRecipe, createSpacingRecipe, createCardRecipe, createToastRecipe, createTooltipRecipe, createAccordionRecipe, buildAccordionFieldA11yIds, radioRecipe, buildRadioGroupFieldA11yIds, createBadgeRecipe, createSwitchRecipe, buildSwitchFieldA11yIds, createSliderRecipe, buildSliderFieldA11yIds, createTabRecipe, resolveTabValue, buildTabGroupA11yIds, createDialogRecipe, themeToCSSVars, richTextCommandByFormat, headingRecipe, moveTabSelection, extractUsedWeights, extractFontFamilyName, shouldLoadGoogleFont, buildGoogleFontsUrl } from '@marwes-ui/core';
+import { ThemeMode, resolveThemePreference, resolveThemeInput, resolveIconSize, resolveIconStrokeWidth, iconRegistry, resolveIconA11y, createSpinnerRecipe, createButtonRecipe, ButtonAction, ButtonVariant, IconName, createInputRecipe, createSelectRecipe, resolveSelectMode, createTextareaRecipe, createRichTextRecipe, resolveRichTextAllowedFormats, normalizeRichTextHtml, isRichTextHtmlEmpty, paragraphRecipe, buildInputFieldA11yIds, sanitizeInputOtpValue, createInputOtpRecipe, buildRichTextFieldA11yIds, buildCurrencyHelperText, getCurrencySymbol, sanitizeCurrencyValue, createAvatarRecipe, createPurposeSemanticAttributes, checkboxRecipe, buildCheckboxFieldA11yIds, buildCheckboxGroupFieldA11yIds, createDividerRecipe, createSpacingRecipe, createCardRecipe, createToastRecipe, createTooltipRecipe, createAccordionRecipe, buildAccordionFieldA11yIds, radioRecipe, buildRadioGroupFieldA11yIds, createBadgeRecipe, createSwitchRecipe, buildSwitchFieldA11yIds, createSliderRecipe, buildSliderFieldA11yIds, createTabRecipe, resolveTabValue, buildTabGroupA11yIds, createDialogRecipe, isThemePreference, nextThemeMode, themeToCSSVars, richTextCommandByFormat, headingRecipe, moveTabSelection, extractUsedWeights, extractFontFamilyName, shouldLoadGoogleFont, buildGoogleFontsUrl } from '@marwes-ui/core';
 export { AvatarSize, AvatarType, BadgeVariant, ButtonAction, ButtonSize, ButtonVariant, IconName, Spacings, SwitchSize, ThemeMode, createFontStack, mwAvailableFonts, mwFontFallbacks, mwGoogleFontFamilies, mwStyledTheme, mwThemeVarNames, mwThemeVars, mwVar } from '@marwes-ui/core';
-import { defineComponent, ref, computed, onMounted, watch, provide, h, useAttrs, onBeforeUnmount, shallowRef, Fragment, nextTick, Teleport, inject } from 'vue';
+import { defineComponent, ref, computed, onMounted, onUnmounted, watch, provide, h, useAttrs, onBeforeUnmount, shallowRef, Fragment, nextTick, Teleport, inject } from 'vue';
 
 // src/index.ts
 
@@ -61,32 +61,141 @@ function loadThemeFonts(theme, config = "auto") {
     }
   }
 }
+var mediaQuery = "(prefers-color-scheme: dark)";
+function getSystemThemeMode() {
+  if (typeof window === "undefined") return ThemeMode.light;
+  return window.matchMedia?.(mediaQuery).matches ? ThemeMode.dark : ThemeMode.light;
+}
+function subscribeToSystemThemeMode(onChange) {
+  if (typeof window === "undefined" || !window.matchMedia) return () => {
+  };
+  const media = window.matchMedia(mediaQuery);
+  const listener = (event) => {
+    onChange(event.matches ? ThemeMode.dark : ThemeMode.light);
+  };
+  if (media.addEventListener) {
+    media.addEventListener("change", listener);
+  } else {
+    media.addListener?.(listener);
+  }
+  return () => {
+    if (media.removeEventListener) {
+      media.removeEventListener("change", listener);
+    } else {
+      media.removeListener?.(listener);
+    }
+  };
+}
+function readStoredThemePreference(storageKey) {
+  if (!storageKey || typeof window === "undefined") return void 0;
+  try {
+    const value = window.localStorage.getItem(storageKey);
+    return isThemePreference(value) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function writeStoredThemePreference(storageKey, preference) {
+  if (!storageKey || typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(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;
+}
 
 // src/provider/marwes-provider.ts
 var MarwesProvider = defineComponent({
   name: "MarwesProvider",
-  props: ["theme", "defaultMode", "mode", "fontLoading", "onModeChange"],
+  props: [
+    "theme",
+    "defaultPreference",
+    "preference",
+    "defaultMode",
+    "mode",
+    "fontLoading",
+    "onPreferenceChange",
+    "onModeChange",
+    "storageKey",
+    "enableSystem",
+    "target",
+    "attribute",
+    "disableTransitionOnChange"
+  ],
   setup(rawProps, { slots }) {
     const props = rawProps;
-    const internalMode = ref(props.defaultMode ?? ThemeMode.light);
-    const activeMode = computed(
-      () => props.mode ?? props.theme?.mode ?? internalMode.value
+    const internalPreference = ref(
+      props.defaultPreference ?? props.defaultMode ?? ThemeMode.light
     );
-    const isModeControlled = computed(
-      () => props.mode !== void 0 || props.theme?.mode !== void 0
+    const systemMode = ref(
+      props.enableSystem === false ? ThemeMode.light : getSystemThemeMode()
+    );
+    const enableSystem = computed(() => props.enableSystem !== false);
+    const storageKey = computed(() => props.storageKey ?? false);
+    const target = computed(() => props.target ?? "provider");
+    const attribute = computed(() => props.attribute ?? "class");
+    const disableTransitionOnChange = computed(() => props.disableTransitionOnChange === true);
+    const isPreferenceControlled = computed(
+      () => props.preference !== void 0 || props.mode !== void 0 || props.theme?.mode !== void 0
+    );
+    const activePreference = computed(
+      () => props.preference ?? props.mode ?? props.theme?.mode ?? internalPreference.value
+    );
+    const activeMode = computed(
+      () => resolveThemePreference(activePreference.value, systemMode.value)
     );
     const resolved = computed(
       () => resolveThemeInput({ ...props.theme ?? {}, mode: activeMode.value })
     );
     const rootRef = ref(null);
-    function setMode(nextMode) {
-      if (!isModeControlled.value) {
-        internalMode.value = nextMode;
+    function setPreference(nextPreference) {
+      if (!isPreferenceControlled.value) {
+        internalPreference.value = nextPreference;
       }
+      writeStoredThemePreference(storageKey.value, nextPreference);
+      props.onPreferenceChange?.(nextPreference);
+    }
+    function setMode(nextMode) {
+      setPreference(nextMode);
       props.onModeChange?.(nextMode);
     }
     function toggleMode() {
-      setMode(activeMode.value === ThemeMode.dark ? ThemeMode.light : ThemeMode.dark);
+      setMode(nextThemeMode(activeMode.value));
     }
     function syncThemeToRuntime() {
       if (rootRef.value) {
@@ -94,12 +203,59 @@ var MarwesProvider = defineComponent({
       }
       loadThemeFonts(resolved.value, props.fontLoading ?? "auto");
     }
-    onMounted(syncThemeToRuntime);
+    function syncTargetModeAttribute() {
+      if (target.value === "provider") return;
+      const apply = () => {
+        applyModeAttribute({
+          target: target.value,
+          providerElement: rootRef.value,
+          mode: activeMode.value,
+          attribute: attribute.value
+        });
+      };
+      if (disableTransitionOnChange.value) {
+        withoutModeTransitions(apply);
+        return;
+      }
+      apply();
+    }
+    let unsubscribeSystemThemeMode;
+    function syncSystemThemeSubscription() {
+      unsubscribeSystemThemeMode?.();
+      unsubscribeSystemThemeMode = void 0;
+      if (!enableSystem.value) {
+        systemMode.value = ThemeMode.light;
+        return;
+      }
+      systemMode.value = getSystemThemeMode();
+      if (activePreference.value === "system") {
+        unsubscribeSystemThemeMode = subscribeToSystemThemeMode((nextMode) => {
+          systemMode.value = nextMode;
+        });
+      }
+    }
+    onMounted(() => {
+      const storedPreference = readStoredThemePreference(storageKey.value);
+      if (storedPreference !== void 0 && !isPreferenceControlled.value) {
+        internalPreference.value = storedPreference;
+      }
+      syncSystemThemeSubscription();
+      syncThemeToRuntime();
+      syncTargetModeAttribute();
+    });
+    onUnmounted(() => {
+      unsubscribeSystemThemeMode?.();
+    });
     watch(resolved, syncThemeToRuntime);
+    watch([activeMode, target, attribute, disableTransitionOnChange], syncTargetModeAttribute);
+    watch([activePreference, enableSystem], syncSystemThemeSubscription);
     provide(marwesContextKey, {
       theme: resolved,
       mode: activeMode,
+      preference: activePreference,
+      systemMode: computed(() => systemMode.value),
       setMode,
+      setPreference,
       toggleMode
     });
     return () => h(
@@ -128,10 +284,14 @@ function useThemeMode() {
   }
   return {
     mode: context.mode,
+    preference: context.preference,
+    systemMode: context.systemMode,
     setMode: context.setMode,
+    setPreference: context.setPreference,
     toggleMode: context.toggleMode,
     isDark: computed(() => context.mode.value === ThemeMode.dark),
-    isLight: computed(() => context.mode.value === ThemeMode.light)
+    isLight: computed(() => context.mode.value === ThemeMode.light),
+    isSystem: computed(() => context.preference.value === "system")
   };
 }