@marwes-ui/vue 1.0.0 → 1.0.2

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
 
-<img alt="Marwes Design System" src="https://raw.githubusercontent.com/niklas-westman/marwes/main/.github/assets/banner-light.png" width="100%">
+<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>
 
 # Marwes Design System - Vue
 
-**Vue 3 components with first edition styling, typed theme tokens, accessibility contracts, and AI-readable semantics built in.**
+**Vue 3 components with default Marwes styling, typed theme tokens, accessibility contracts, and AI-readable semantics built in.**
 
 Vue 3.4+ • TypeScript-first • Default CSS included • ThemeInput • Google Fonts DX • Purpose components
 
@@ -21,7 +21,7 @@ Vue 3.4+ • TypeScript-first • Default CSS included • ThemeInput • Google
 
 Marwes gives Vue apps a ready design-system base without requiring custom CSS setup or local component forks.
 
-- **One package for Vue apps**: components, provider, default first edition CSS, theme helpers, and typed props.
+- **One package for Vue apps**: components, provider, default preset CSS, theme helpers, and typed props.
 - **Vue-native binding**: common controls support `v-model` while preserving Marwes semantic contracts.
 - **Consequential theming**: a `ThemeInput` object changes colors, fonts, radius, density, typography, and component visuals through shared CSS variables.
 - **Purpose components**: `SubmitButton`, `CancelButton`, and `DestructiveButton` make intent machine-readable so tests, audits, and AI agents can handle actions safely.
@@ -36,7 +36,7 @@ For a Vue app, install this package first. It includes the Vue adapter, loads th
 | `@marwes-ui/vue` | You are building a Vue app. |
 | `@marwes-ui/react` | You are building a React app instead. |
 | `@marwes-ui/core` | You are building adapters, tests, tooling, or framework-agnostic integrations. |
-| `@marwes-ui/presets` | You need standalone first edition CSS or preset theme exports. |
+| `@marwes-ui/presets` | You need standalone preset CSS or preset theme exports. |
 
 This split keeps installation simple for app teams while giving humans and AI agents clear package boundaries: adapters render, core defines contracts, presets style.
 
@@ -46,14 +46,14 @@ This split keeps installation simple for app teams while giving humans and AI ag
 pnpm add @marwes-ui/vue vue
 ```
 
-No preset CSS import is needed. `@marwes-ui/vue` depends on `@marwes-ui/presets` and loads the first edition CSS automatically.
+No preset CSS import is needed. `@marwes-ui/vue` depends on `@marwes-ui/presets` and loads the default Marwes CSS automatically.
 
 ## Quick Start
 
 ```vue
 <script setup lang="ts">
 import { ref } from "vue"
-import { Button, Checkbox, Input, MarwesProvider, SubmitButton } from "@marwes-ui/vue"
+import { Button, ButtonVariant, Checkbox, Input, MarwesProvider, SubmitButton } from "@marwes-ui/vue"
 
 const email = ref("")
 const subscribed = ref(false)
@@ -63,7 +63,7 @@ const subscribed = ref(false)
   <MarwesProvider>
     <Input v-model="email" placeholder="Email" ariaLabel="Email" />
     <Checkbox v-model="subscribed" ariaLabel="Subscribe" />
-    <Button variant="secondary">Preview</Button>
+    <Button :variant="ButtonVariant.secondary">Preview</Button>
     <SubmitButton>Save</SubmitButton>
   </MarwesProvider>
 </template>
@@ -75,7 +75,7 @@ Marwes components pick up provider tokens automatically. Your own Vue styling ca
 
 ```vue
 <script setup lang="ts">
-import { Button, MarwesProvider, mwThemeVars } from "@marwes-ui/vue"
+import { Button, ButtonVariant, MarwesProvider, mwThemeVars } from "@marwes-ui/vue"
 
 const panelStyle = {
   padding: mwThemeVars.spacing.sp24,
@@ -90,7 +90,7 @@ const panelStyle = {
     <main class="app-shell">
       <aside class="primary-callout">Launch workspace</aside>
       <section class="feature-panel" :style="panelStyle">
-        <Button variant="primary">Save</Button>
+        <Button :variant="ButtonVariant.primary">Save</Button>
       </section>
     </main>
   </MarwesProvider>
@@ -136,7 +136,9 @@ import {
   StatusBadge,
   SubmitButton,
   type ButtonProps,
+  type HeadingProps,
   type InputFieldProps,
+  type ParagraphProps,
 } from "@marwes-ui/vue"
 
 const primaryAction: ButtonProps = {
@@ -152,6 +154,14 @@ const emailField: InputFieldProps = {
     placeholder: "you@example.com",
   },
 }
+
+const titleProps: HeadingProps = {
+  size: "h2",
+}
+
+const descriptionProps: ParagraphProps = {
+  size: "md",
+}
 </script>
 
 <template>
@@ -159,8 +169,8 @@ const emailField: InputFieldProps = {
     <template #title>Project setup</template>
     <StatusBadge :variant="BadgeVariant.success">Ready</StatusBadge>
     <Spacer :spacing="Spacings.sp16" />
-    <H1 size="h2">Launch workspace</H1>
-    <Paragraph size="md">
+    <H1 v-bind="titleProps">Launch workspace</H1>
+    <Paragraph v-bind="descriptionProps">
       Components share theme tokens, typed variants, spacing, and semantic metadata.
     </Paragraph>
     <InputField v-bind="emailField" />
@@ -223,11 +233,11 @@ Typed tokens and helpers:
 
 ## Theme In Seconds
 
-First edition is the default. Pass `theme` only when a brand or design file needs to change the baseline.
+The default Marwes theme is already active. If you already have a good-looking design library or brand system, pass a small typed `ThemeInput` override instead of rebuilding component CSS.
 
 ```vue
 <script setup lang="ts">
-import { MarwesProvider, mwAvailableFonts } from "@marwes-ui/vue"
+import { MarwesProvider, mwAvailableFonts, type ThemeInput } from "@marwes-ui/vue"
 
 const brandTheme = {
   color: {
@@ -251,7 +261,7 @@ const brandTheme = {
     radius: 10,
     density: "comfortable",
   },
-}
+} satisfies ThemeInput
 </script>
 
 <template>
@@ -263,6 +273,133 @@ const brandTheme = {
 
 The provider resolves `ThemeInput` into `--mw-*` CSS variables. Preset CSS consumes those variables across the full component system.
 
+Marwes is designed to look great from the beginning. Start with the default preset, then override only the colors, fonts, radius, or density that belong to your product. Unspecified values keep the polished Marwes defaults.
+
+## Light And Dark Mode
+
+MarwesProvider can own the active mode for the app. Use `ThemeMode.light` and `ThemeMode.dark` instead of string literals, then read or change the active mode with `useThemeMode()` anywhere under the provider. Every component under the provider receives the matching `--mw-*` variables and `mw-theme--light` / `mw-theme--dark` class.
+
+```vue
+<script setup lang="ts">
+import { Button, ButtonVariant, ThemeMode, useThemeMode } from "@marwes-ui/vue"
+
+const { mode, toggleMode } = useThemeMode()
+</script>
+
+<template>
+  <Button :variant="ButtonVariant.secondary" @click="toggleMode">
+    Use {{ mode === ThemeMode.dark ? ThemeMode.light : ThemeMode.dark }} mode
+  </Button>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import { MarwesProvider, ThemeMode } from "@marwes-ui/vue"
+import ThemeToggle from "./theme-toggle.vue"
+</script>
+
+<template>
+  <MarwesProvider :default-mode="ThemeMode.light">
+    <ThemeToggle />
+    <AppShell />
+  </MarwesProvider>
+</template>
+```
+
+`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.
+
+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
+<script setup lang="ts">
+import { ref } from "vue"
+import { MarwesProvider, ThemeMode, type ThemeInput } from "@marwes-ui/vue"
+import ThemeToggle from "./theme-toggle.vue"
+
+const mode = ref<ThemeMode>(ThemeMode.light)
+
+const themeByMode = {
+  [ThemeMode.light]: {
+    color: {
+      primary: "#2457FF",
+      background: "#F8FAFC",
+      surface: "#FFFFFF",
+      text: "#111827",
+      border: "#D1D5DB",
+      focus: "#2457FF",
+    },
+  },
+  [ThemeMode.dark]: {
+    color: {
+      primary: "#8BA2FF",
+      background: "#0B1020",
+      surface: "#111827",
+      text: "#F8FAFC",
+      border: "#334155",
+      focus: "#93C5FD",
+    },
+  },
+} satisfies Record<ThemeMode, ThemeInput>
+
+function setMode(nextMode: ThemeMode) {
+  mode.value = nextMode
+}
+</script>
+
+<template>
+  <MarwesProvider :mode="mode" :theme="themeByMode[mode]" :on-mode-change="setMode">
+    <ThemeToggle />
+    <AppShell />
+  </MarwesProvider>
+</template>
+```
+
+Mode-specific defaults fill every omitted token, so each override can stay small. `:theme="{ mode: ThemeMode.dark }"` is still enough for the default dark baseline.
+
 ## Custom Styling Tokens
 
 `MarwesProvider` resolves `ThemeInput` into `--mw-*` CSS variables. Marwes components and preset CSS consume those variables automatically. The custom styling token helpers let app-owned Vue styles, script-driven style objects, and build-time config use the same provider-scoped values instead of hard-coding colors, spacing, radius, typography, or duplicated `var(...)` strings.
@@ -331,14 +468,14 @@ Most Google Font use cases only need `mwAvailableFonts`; no `fontLoading` prop i
 
 ```vue
 <script setup lang="ts">
-import { mwAvailableFonts } from "@marwes-ui/vue"
+import { MarwesProvider, mwAvailableFonts, type ThemeInput } from "@marwes-ui/vue"
 
 const theme = {
   font: {
     primary: mwAvailableFonts.Poppins,
     secondary: mwAvailableFonts.Lora,
   },
-}
+} satisfies ThemeInput
 </script>
 
 <template>
@@ -402,16 +539,18 @@ Example:
 
 ```vue
 <script setup lang="ts">
-import { InputField } from "@marwes-ui/vue"
+import { InputField, type InputFieldProps } from "@marwes-ui/vue"
+
+const receiptEmailField = {
+  label: "Email",
+  helperText: "Used for receipts.",
+  error: "Enter a valid email.",
+  input: { type: "email", placeholder: "you@example.com" },
+} satisfies InputFieldProps
 </script>
 
 <template>
-  <InputField
-    label="Email"
-    helperText="Used for receipts."
-    error="Enter a valid email."
-    :input="{ type: 'email', placeholder: 'you@example.com' }"
-  />
+  <InputField v-bind="receiptEmailField" />
 </template>
 ```
 
@@ -434,7 +573,7 @@ The important part is that the same label, helper, error, and invalid contract i
 ## Package Boundaries
 
 - `@marwes-ui/core` owns recipes, theme resolution, a11y mapping, and semantic metadata.
-- `@marwes-ui/presets` owns first edition CSS.
+- `@marwes-ui/presets` owns default preset CSS.
 - `@marwes-ui/vue` owns Vue rendering and provider behavior.
 
 ## Scripts

package/dist/index.d.ts

@@ -1,28 +1,62 @@
 import * as vue from 'vue';
-import { VNodeChild } from 'vue';
+import { ComputedRef, VNodeChild } from 'vue';
 import * as _marwes_ui_core from '@marwes-ui/core';
-import { ThemeInput, FontLoadingConfig, ThemeMode, 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 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;
 };
 declare const MarwesProvider: vue.DefineComponent<{
+    mode?: any;
     theme?: any;
+    defaultPreference?: any;
+    preference?: any;
+    defaultMode?: any;
     fontLoading?: any;
+    onPreferenceChange?: any;
     onModeChange?: any;
+    storageKey?: any;
+    enableSystem?: any;
 }, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<{
+    mode?: any;
     theme?: any;
+    defaultPreference?: any;
+    preference?: any;
+    defaultMode?: any;
     fontLoading?: any;
+    onPreferenceChange?: any;
     onModeChange?: any;
+    storageKey?: any;
+    enableSystem?: 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;
+
 type ButtonProps = ButtonOptions & {
     onClick?: (event: MouseEvent) => void;
     className?: string;
@@ -2853,4 +2887,4 @@ declare const InfoDialog: vue.DefineComponent<{
     onAcknowledge?: any;
 }> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
-export { Accordion, AccordionField, type AccordionFieldItem, type AccordionFieldProps, type AccordionProps, Avatar, AvatarBadge, type AvatarBadgeProps, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarProps, Badge, BadgeGroup, type BadgeGroupProps, type BadgeProps, BrightnessSlider, type BrightnessSliderProps, Button, type ButtonProps, ButtonSpinner, type ButtonSpinnerProps, CancelButton, type CancelButtonProps, Card, type CardProps, Checkbox, CheckboxField, type CheckboxFieldProps, CheckboxGroupField, type CheckboxGroupFieldOption, type CheckboxGroupFieldProps, type CheckboxProps, CloseButton, type CloseButtonProps, ConfirmButton, type ConfirmButtonProps, ConfirmDialog, type ConfirmDialogProps, ContentTabs, type ContentTabsProps, CopyButton, type CopyButtonProps, CreateButton, type CreateButtonProps, CurrencyField, type CurrencyFieldProps, DateOfBirthField, type DateOfBirthFieldProps, DestructiveButton, type DestructiveButtonProps, DestructiveDialog, type DestructiveDialogProps, Dialog, type DialogFooterControls, DialogModal, type DialogModalProps, type DialogProps, Divider, type DividerProps, DownloadButton, type DownloadButtonProps, DropdownButton, type DropdownButtonProps, DropdownField, type DropdownFieldProps, EditButton, type EditButtonProps, EmailField, type EmailFieldProps, EmptyStateSpinner, type EmptyStateSpinnerProps, ErrorToast, type ErrorToastProps, FAQAccordion, type FAQAccordionProps, FeatureToggle, type FeatureToggleProps, FilterButton, type FilterButtonProps, H1, H2, H3, type HeadingLevel, type HeadingProps, Icon, type IconProps, InfoDialog, type InfoDialogProps, InfoToast, type InfoToastProps, Input, InputField, type InputFieldProps, InputOtp, type InputOtpProps, type InputProps, LinkButton, type LinkButtonProps, type ManagedToast, MarwesProvider, type MarwesProviderProps, NavigationTabs, type NavigationTabsProps, NotificationBadge, type NotificationBadgeProps, OptionRadioGroup, type OptionRadioGroupProps, Paragraph, type ParagraphProps, PasswordField, type PasswordFieldProps, PermissionSwitch, type PermissionSwitchProps, PhoneField, type PhoneFieldProps, PreferenceSwitch, type PreferenceSwitchProps, PresenceAvatar, type PresenceAvatarProps, PrimaryButton, type PrimaryButtonProps, PriorityBadge, type PriorityBadgeProps, ProductCard, type ProductCardProps, ProfileAvatar, type ProfileAvatarProps, ProfileCard, type ProfileCardProps, Radio, RadioGroupField, type RadioGroupFieldOption, type RadioGroupFieldProps, type RadioProps, RadiusSlider, type RadiusSliderProps, RatingRadioGroup, type RatingRadioGroupProps, RefreshButton, type RefreshButtonProps, RichText, RichTextField, type RichTextFieldProps, type RichTextProps, SaveButton, type SaveButtonProps, SearchButton, type SearchButtonProps, SearchField, type SearchFieldProps, SecondaryButton, type SecondaryButtonProps, SectionsAccordion, type SectionsAccordionProps, Select, type SelectAppearance, SelectField, type SelectFieldProps, type SelectOption, type SelectProps, SettingsAccordion, type SettingsAccordionProps, SettingsTabs, type SettingsTabsProps, type ShowToastOptions, Slider, SliderField, type SliderFieldProps, type SliderProps, SortButton, type SortButtonProps, Spacer, type SpacerProps, Spacing, type SpacingProps, Spinner, type SpinnerProps, StatCard, type StatCardProps, StatusBadge, type StatusBadgeProps, SubmitButton, type SubmitButtonProps, SuccessButton, type SuccessButtonProps, SuccessToast, type SuccessToastProps, Switch, SwitchField, type SwitchFieldProps, type SwitchProps, Tab, TabGroup, type TabGroupItem, type TabGroupProps, TabPanel, type TabPanelProps, type TabProps, TeamAvatarGroup, type TeamAvatarGroupProps, TextButton, type TextButtonProps, Textarea, TextareaField, type TextareaFieldProps, type TextareaProps, Toast, ToastContainer, type ToastContainerProps, type ToastController, type ToastProps, ToastProvider, type ToastProviderProps, Tooltip, TooltipGroup, type TooltipGroupProps, type TooltipProps, URLField, type URLFieldProps, UploadButton, type UploadButtonProps, VerifyButton, type VerifyButtonProps, VolumeSlider, type VolumeSliderProps, WarningToast, type WarningToastProps, YesNoRadioGroup, type YesNoRadioGroupProps, ZipCodeField, type ZipCodeFieldProps, createHeadingComponent, useTheme, useToast };
+export { Accordion, AccordionField, type AccordionFieldItem, type AccordionFieldProps, type AccordionProps, Avatar, AvatarBadge, type AvatarBadgeProps, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarProps, Badge, BadgeGroup, type BadgeGroupProps, type BadgeProps, BrightnessSlider, type BrightnessSliderProps, Button, type ButtonProps, ButtonSpinner, type ButtonSpinnerProps, CancelButton, type CancelButtonProps, Card, type CardProps, Checkbox, CheckboxField, type CheckboxFieldProps, CheckboxGroupField, type CheckboxGroupFieldOption, type CheckboxGroupFieldProps, type CheckboxProps, CloseButton, type CloseButtonProps, ConfirmButton, type ConfirmButtonProps, ConfirmDialog, type ConfirmDialogProps, ContentTabs, type ContentTabsProps, CopyButton, type CopyButtonProps, CreateButton, type CreateButtonProps, CurrencyField, type CurrencyFieldProps, DateOfBirthField, type DateOfBirthFieldProps, DestructiveButton, type DestructiveButtonProps, DestructiveDialog, type DestructiveDialogProps, Dialog, type DialogFooterControls, DialogModal, type DialogModalProps, type DialogProps, Divider, type DividerProps, DownloadButton, type DownloadButtonProps, DropdownButton, type DropdownButtonProps, DropdownField, type DropdownFieldProps, EditButton, type EditButtonProps, EmailField, type EmailFieldProps, EmptyStateSpinner, type EmptyStateSpinnerProps, ErrorToast, type ErrorToastProps, FAQAccordion, type FAQAccordionProps, FeatureToggle, type FeatureToggleProps, FilterButton, type FilterButtonProps, H1, H2, H3, type HeadingLevel, type HeadingProps, Icon, type IconProps, InfoDialog, type InfoDialogProps, InfoToast, type InfoToastProps, Input, InputField, type InputFieldProps, InputOtp, type InputOtpProps, type InputProps, LinkButton, type LinkButtonProps, type ManagedToast, MarwesProvider, type MarwesProviderProps, NavigationTabs, type NavigationTabsProps, NotificationBadge, type NotificationBadgeProps, OptionRadioGroup, type OptionRadioGroupProps, Paragraph, type ParagraphProps, PasswordField, type PasswordFieldProps, PermissionSwitch, type PermissionSwitchProps, PhoneField, type PhoneFieldProps, PreferenceSwitch, type PreferenceSwitchProps, PresenceAvatar, type PresenceAvatarProps, PrimaryButton, type PrimaryButtonProps, PriorityBadge, type PriorityBadgeProps, ProductCard, type ProductCardProps, ProfileAvatar, type ProfileAvatarProps, ProfileCard, type ProfileCardProps, Radio, RadioGroupField, type RadioGroupFieldOption, type RadioGroupFieldProps, type RadioProps, RadiusSlider, type RadiusSliderProps, RatingRadioGroup, type RatingRadioGroupProps, RefreshButton, type RefreshButtonProps, RichText, RichTextField, type RichTextFieldProps, type RichTextProps, SaveButton, type SaveButtonProps, SearchButton, type SearchButtonProps, SearchField, type SearchFieldProps, SecondaryButton, type SecondaryButtonProps, SectionsAccordion, type SectionsAccordionProps, Select, type SelectAppearance, SelectField, type SelectFieldProps, type SelectOption, type SelectProps, SettingsAccordion, type SettingsAccordionProps, SettingsTabs, type SettingsTabsProps, type ShowToastOptions, Slider, SliderField, type SliderFieldProps, type SliderProps, SortButton, type SortButtonProps, Spacer, type SpacerProps, Spacing, type SpacingProps, Spinner, type SpinnerProps, StatCard, type StatCardProps, StatusBadge, type StatusBadgeProps, SubmitButton, type SubmitButtonProps, SuccessButton, type SuccessButtonProps, SuccessToast, type SuccessToastProps, Switch, SwitchField, type SwitchFieldProps, type SwitchProps, Tab, TabGroup, type TabGroupItem, type TabGroupProps, TabPanel, type TabPanelProps, type TabProps, TeamAvatarGroup, type TeamAvatarGroupProps, TextButton, type TextButtonProps, Textarea, TextareaField, type TextareaFieldProps, type TextareaProps, type ThemeModeContextValue, Toast, ToastContainer, type ToastContainerProps, type ToastController, type ToastProps, ToastProvider, type ToastProviderProps, Tooltip, TooltipGroup, type TooltipGroupProps, type TooltipProps, URLField, type URLFieldProps, UploadButton, type UploadButtonProps, VerifyButton, type VerifyButtonProps, VolumeSlider, type VolumeSliderProps, WarningToast, type WarningToastProps, YesNoRadioGroup, type YesNoRadioGroupProps, ZipCodeField, type ZipCodeFieldProps, createHeadingComponent, useTheme, useThemeMode, useToast };

package/dist/index.js

@@ -1,7 +1,7 @@
 import '@marwes-ui/presets/firstEdition/styles.css';
-import { 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';
-export { AvatarSize, AvatarType, BadgeVariant, ButtonAction, ButtonSize, ButtonVariant, IconName, Spacings, SwitchSize, createFontStack, mwAvailableFonts, mwFontFallbacks, mwGoogleFontFamilies, mwStyledTheme, mwThemeVarNames, mwThemeVars, mwVar } from '@marwes-ui/core';
-import { defineComponent, computed, ref, onMounted, watch, provide, h, useAttrs, onBeforeUnmount, shallowRef, Fragment, nextTick, Teleport, inject } from 'vue';
+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, onUnmounted, watch, provide, h, useAttrs, onBeforeUnmount, shallowRef, Fragment, nextTick, Teleport, inject } from 'vue';
 
 // src/index.ts
 
@@ -61,26 +61,142 @@ 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 {
+  }
+}
 
 // src/provider/marwes-provider.ts
 var MarwesProvider = defineComponent({
   name: "MarwesProvider",
-  props: ["theme", "fontLoading", "onModeChange"],
+  props: [
+    "theme",
+    "defaultPreference",
+    "preference",
+    "defaultMode",
+    "mode",
+    "fontLoading",
+    "onPreferenceChange",
+    "onModeChange",
+    "storageKey",
+    "enableSystem"
+  ],
   setup(rawProps, { slots }) {
     const props = rawProps;
-    const resolved = computed(() => resolveThemeInput(props.theme ?? {}));
+    const internalPreference = ref(
+      props.defaultPreference ?? props.defaultMode ?? ThemeMode.light
+    );
+    const systemMode = ref(
+      props.enableSystem === false ? ThemeMode.light : getSystemThemeMode()
+    );
+    const enableSystem = computed(() => props.enableSystem !== false);
+    const storageKey = computed(() => props.storageKey ?? false);
+    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 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(nextThemeMode(activeMode.value));
+    }
     function syncThemeToRuntime() {
       if (rootRef.value) {
         applyThemeToElement(rootRef.value, resolved.value);
       }
       loadThemeFonts(resolved.value, props.fontLoading ?? "auto");
     }
-    onMounted(syncThemeToRuntime);
+    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();
+    });
+    onUnmounted(() => {
+      unsubscribeSystemThemeMode?.();
+    });
     watch(resolved, syncThemeToRuntime);
+    watch([activePreference, enableSystem], syncSystemThemeSubscription);
     provide(marwesContextKey, {
       theme: resolved,
-      onModeChange: props.onModeChange
+      mode: activeMode,
+      preference: activePreference,
+      systemMode: computed(() => systemMode.value),
+      setMode,
+      setPreference,
+      toggleMode
     });
     return () => h(
       "div",
@@ -101,6 +217,23 @@ function useTheme() {
   }
   return context.theme.value;
 }
+function useThemeMode() {
+  const context = inject(marwesContextKey, null);
+  if (!context) {
+    throw new Error("MarwesProvider is missing. Wrap your app in <MarwesProvider />.");
+  }
+  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),
+    isSystem: computed(() => context.preference.value === "system")
+  };
+}
 
 // src/internal/render-utils.ts
 function mergeClassNames(...parts) {
@@ -6520,6 +6653,6 @@ var InfoDialog = defineComponent({
   }
 });
 
-export { Accordion, AccordionField, Avatar, AvatarBadge, AvatarGroup, Badge, BadgeGroup, BrightnessSlider, Button, ButtonSpinner, CancelButton, Card, Checkbox, CheckboxField, CheckboxGroupField, CloseButton, ConfirmButton, ConfirmDialog, ContentTabs, CopyButton, CreateButton, CurrencyField, DateOfBirthField, DestructiveButton, DestructiveDialog, Dialog, DialogModal, Divider, DownloadButton, DropdownButton, DropdownField, EditButton, EmailField, EmptyStateSpinner, ErrorToast, FAQAccordion, FeatureToggle, FilterButton, H1, H2, H3, Icon, InfoDialog, InfoToast, Input, InputField, InputOtp, LinkButton, MarwesProvider, NavigationTabs, NotificationBadge, OptionRadioGroup, Paragraph, PasswordField, PermissionSwitch, PhoneField, PreferenceSwitch, PresenceAvatar, PrimaryButton, PriorityBadge, ProductCard, ProfileAvatar, ProfileCard, Radio, RadioGroupField, RadiusSlider, RatingRadioGroup, RefreshButton, RichText, RichTextField, SaveButton, SearchButton, SearchField, SecondaryButton, SectionsAccordion, Select, SelectField, SettingsAccordion, SettingsTabs, Slider, SliderField, SortButton, Spacer, Spacing, Spinner, StatCard, StatusBadge, SubmitButton, SuccessButton, SuccessToast, Switch, SwitchField, Tab, TabGroup, TabPanel, TeamAvatarGroup, TextButton, Textarea, TextareaField, Toast, ToastContainer, ToastProvider, Tooltip, TooltipGroup, URLField, UploadButton, VerifyButton, VolumeSlider, WarningToast, YesNoRadioGroup, ZipCodeField, createHeadingComponent, useTheme, useToast };
+export { Accordion, AccordionField, Avatar, AvatarBadge, AvatarGroup, Badge, BadgeGroup, BrightnessSlider, Button, ButtonSpinner, CancelButton, Card, Checkbox, CheckboxField, CheckboxGroupField, CloseButton, ConfirmButton, ConfirmDialog, ContentTabs, CopyButton, CreateButton, CurrencyField, DateOfBirthField, DestructiveButton, DestructiveDialog, Dialog, DialogModal, Divider, DownloadButton, DropdownButton, DropdownField, EditButton, EmailField, EmptyStateSpinner, ErrorToast, FAQAccordion, FeatureToggle, FilterButton, H1, H2, H3, Icon, InfoDialog, InfoToast, Input, InputField, InputOtp, LinkButton, MarwesProvider, NavigationTabs, NotificationBadge, OptionRadioGroup, Paragraph, PasswordField, PermissionSwitch, PhoneField, PreferenceSwitch, PresenceAvatar, PrimaryButton, PriorityBadge, ProductCard, ProfileAvatar, ProfileCard, Radio, RadioGroupField, RadiusSlider, RatingRadioGroup, RefreshButton, RichText, RichTextField, SaveButton, SearchButton, SearchField, SecondaryButton, SectionsAccordion, Select, SelectField, SettingsAccordion, SettingsTabs, Slider, SliderField, SortButton, Spacer, Spacing, Spinner, StatCard, StatusBadge, SubmitButton, SuccessButton, SuccessToast, Switch, SwitchField, Tab, TabGroup, TabPanel, TeamAvatarGroup, TextButton, Textarea, TextareaField, Toast, ToastContainer, ToastProvider, Tooltip, TooltipGroup, URLField, UploadButton, VerifyButton, VolumeSlider, WarningToast, YesNoRadioGroup, ZipCodeField, createHeadingComponent, useTheme, useThemeMode, useToast };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map