@marwes-ui/core 1.0.3 → 1.0.5

package/README.md

@@ -122,6 +122,23 @@ resolveMode(ThemeMode.dark)
 
 Most apps should use `useThemeMode()` from `@marwes-ui/react` or `@marwes-ui/vue`. Core is the framework-agnostic piece that makes the resolved variables and mode classes consistent across adapters.
 
+### SSR Theme Rules
+
+SSR adapters can use the same core theme engine to emit light and dark CSS variable rules before hydration. These helpers are pure string utilities; React and Vue expose framework-specific SSR helpers on top.
+
+```ts
+import { ThemeMode, resolveThemeInput, themeModesToCSSRules } from "@marwes-ui/core"
+
+const css = themeModesToCSSRules({
+  light: resolveThemeInput({ mode: ThemeMode.light }),
+  dark: resolveThemeInput({ mode: ThemeMode.dark }),
+  rootTarget: "html",
+  rootAttribute: "class",
+})
+```
+
+The generated rules target `[data-marwes-theme][data-marwes-mode="light"]` and `[data-marwes-theme][data-marwes-mode="dark"]`. When `rootTarget` is provided, matching `html.light` / `html.dark` or data-attribute selectors are included so a pre-hydration script can switch the resolved mode before provider roots hydrate.
+
 ## Theme Variables
 
 Marwes components are styled by CSS custom properties on the `MarwesProvider` root. The theme variable helpers expose that same token surface to application code, adapters, and tooling without creating a second runtime theme system.
@@ -234,6 +251,10 @@ This is intentionally practical. A destructive action can carry `data-destructiv
 Theme:
 - `resolveThemeInput`
 - `themeToCSSVars`
+- `themeToCSSRule`
+- `themeModesToCSSRules`
+- `createMarwesThemeScript`
+- `createMarwesThemeStyle`
 - `mwThemeVars`
 - `mwThemeVarNames`
 - `mwStyledTheme`

package/dist/index.d.ts

@@ -42,6 +42,7 @@ declare const ThemeMode: {
 };
 type ThemeMode = (typeof ThemeMode)[keyof typeof ThemeMode];
 type ThemePreference = ThemeMode | "system";
+type ThemeVariableStrategy = "inline" | "style-tag";
 type Theme = {
     /**
      * The current theme mode. This determines which color defaults are applied.
@@ -173,19 +174,6 @@ declare function isThemePreference(value: unknown): value is ThemePreference;
 declare function resolveThemePreference(preference: ThemePreference, systemMode: SystemThemeMode): ThemeMode;
 declare function nextThemeMode(mode: ThemeMode): ThemeMode;
 
-/**
- * Light theme defaults (default mode).
- * Uses dark text on light backgrounds.
- * Colors mapped from Figma design tokens (node 1:120).
- */
-declare const lightThemeDefaults: Theme;
-/**
- * Dark theme defaults.
- * Uses light text on dark backgrounds.
- * Colors are inverted from light theme for optimal dark mode experience.
- */
-declare const darkThemeDefaults: Theme;
-
 interface ResolvedTheme {
     mode: ThemeMode;
     color: {
@@ -264,6 +252,51 @@ interface ResolvedTheme {
  * Variable naming follows D11: --mw-color-{role}-{state}, --mw-font-*, etc.
  */
 declare function themeToCSSVars(theme: ResolvedTheme): Record<string, string>;
+type ThemeModeAttribute = "class" | "data-theme" | "data-mode";
+type ThemeModeRootTarget = "html" | "body";
+type ThemeModeCSSRulesOptions = {
+    light: ResolvedTheme;
+    dark: ResolvedTheme;
+    selector?: string;
+    rootTarget?: ThemeModeRootTarget;
+    rootAttribute?: ThemeModeAttribute;
+};
+declare function themeToCSSRule(selector: string, theme: ResolvedTheme): string;
+declare function themeModesToCSSRules({ light, dark, selector, rootTarget, rootAttribute, }: ThemeModeCSSRulesOptions): string;
+
+type MarwesThemeScriptOptions = {
+    storageKey?: string | false;
+    defaultPreference?: ThemePreference;
+    enableSystem?: boolean;
+    target?: ThemeModeRootTarget;
+    attribute?: ThemeModeAttribute;
+};
+type MarwesThemeStyleOptions = {
+    lightTheme?: ThemeInput;
+    darkTheme?: ThemeInput;
+    selector?: string;
+    target?: ThemeModeRootTarget;
+    attribute?: ThemeModeAttribute;
+};
+declare function createMarwesThemeScript({ storageKey, defaultPreference, enableSystem, target, attribute, }?: MarwesThemeScriptOptions): string;
+declare function createMarwesThemeStyle({ lightTheme, darkTheme, selector, target, attribute, }?: MarwesThemeStyleOptions): string;
+declare function resolveServerThemeMode({ preference, systemFallback, }?: {
+    preference?: ThemePreference;
+    systemFallback?: ThemeMode;
+}): ThemeMode;
+
+/**
+ * Light theme defaults (default mode).
+ * Uses dark text on light backgrounds.
+ * Colors mapped from Figma design tokens (node 1:120).
+ */
+declare const lightThemeDefaults: Theme;
+/**
+ * Dark theme defaults.
+ * Uses light text on dark backgrounds.
+ * Colors are inverted from light theme for optimal dark mode experience.
+ */
+declare const darkThemeDefaults: Theme;
 
 /**
  * Converts a consumer ThemeInput into a fully-resolved ResolvedTheme.
@@ -9134,4 +9167,4 @@ type SpacingRenderKit = {
 
 declare function createSpacingRecipe(opts?: SpacingOptions): SpacingRenderKit;
 
-export { type AccordionA11yProps, type AccordionOptions, type AccordionRenderKit, type AvatarA11yProps, type AvatarDataAttributes, type AvatarOptions, type AvatarRenderContent, type AvatarRenderKit, AvatarSize, AvatarType, type BadgeA11yProps, type BadgeOptions, type BadgeRenderKit, BadgeVariant, type ButtonA11yProps, ButtonAction, type ButtonLoadingOptions, type ButtonOptions, type ButtonRenderKit, ButtonSize, ButtonVariant, type CardOptions, type CardRenderKit, type CheckboxA11y, type CheckboxProps, type CheckboxRenderKit, type CheckboxState, type ColorInput, type ColorRole, type CssVars, type CurrencyCode, DENSITY_SCALES, type Density, type DensityScale, type DialogA11yProps, type DialogOptions, type DialogRenderKit, type DialogSize, type DividerA11y, type DividerDataAttributes, type DividerOptions, type DividerOrientation, type DividerRenderKit, type DividerSize, type FamilySemanticDefinition, type FieldComparisonRow, type FontLoadingConfig, type FontLoadingMode, type FontLoadingOptions, type HeadingA11y, type HeadingLevel, type HeadingOptions, type HeadingRenderKit, type HeadingSize, type IconA11yProps, type IconColor, IconName, IconName as IconNameType, type IconOptions, type IconPreset, type IconRenderKit, type IconSize, type IconSizeKey, type IconStrokeWidth, type IconStrokeWidthKey, type InputA11yProps, type InputOptions, type InputOtpA11yProps, type InputOtpOptions, type InputOtpRenderKit, type InputRenderKit, type InputTone, type LabeledCopy, type MwAvailableFont, type MwFontFallback, type MwGoogleFontFamily, type MwStyledTheme, type MwThemeVarName, type MwThemeVarNames, type MwThemeVarReference, type MwThemeVars, type ParagraphA11y, type ParagraphOptions, type ParagraphRenderKit, type ParagraphSize, type PurposeSemanticDefinition, type RadioA11y, type RadioOptions, type RadioRenderKit, type ResolvedButtonLoading, type ResolvedTheme, type RichTextA11yProps, type RichTextFormat, type RichTextOptions, type RichTextRenderKit, type SecondaryColorRole, type SelectA11yProps, type SelectAppearance, type SelectMode, type SelectOption, type SelectOptions, type SelectRenderKit, type SemanticAttributeDefinition, type SemanticAttributeName, type SemanticAttributeValue, type SemanticAttributes, type SemanticFamily, type SemanticIntent, type SemanticLayer, type SemanticOrientation, type SemanticOutcome, type SemanticPurpose, type SliderA11yProps, type SliderDataAttributes, type SliderOptions, type SliderRenderKit, type SpacingA11y, type SpacingDataAttributes, type SpacingOptions, type SpacingRenderKit, type SpacingSize, Spacings, type SpinnerA11yProps, type SpinnerDataAttributes, type SpinnerOptions, type SpinnerRenderKit, type SpinnerSize, type SpinnerSvgDefinition, type SpinnerSvgElement, type SpinnerSvgNode, SpinnerVariant, SpinnerVariants, type SvgElementType, type SvgNode, type SwitchA11yProps, type SwitchOptions, type SwitchRenderKit, SwitchSize, type SystemThemeMode, type TabA11yProps, type TabGroupA11yIds, type TabGroupItemState, type TabNavigationDirection, type TabOptions, type TabRenderKit, type TextareaA11yProps, type TextareaOptions, type TextareaRenderKit, type TextareaResize, type Theme, type ThemeInput, type ThemeInputColor, ThemeMode, type ThemePreference, type ToastA11yProps, type ToastContainerOptions, type ToastIntent, type ToastOptions, type ToastPlacement, type ToastRenderKit, type ToastVariant, type ToneName, type TooltipA11yProps, type TooltipDataAttributes, type TooltipOptions, type TooltipRenderKit, accordionPurposeComponentReference, accordionWhyPurposeComponents, avatarPurposeSemantics, avatarPurposes, badgePurposeComponentReference, badgePurposeSemantics, badgePurposes, badgeWhyPurposeComponents, buildAccordionFieldA11yIds, buildCheckboxA11y, buildCheckboxFieldA11yIds, buildCheckboxGroupFieldA11yIds, buildCurrencyHelperText, buildGoogleFontsUrl, buildHeadingA11y, buildInputFieldA11yIds, buildRadioA11y, buildRadioGroupFieldA11yIds, buildRichTextFieldA11yIds, buildSliderFieldA11yIds, buildSwitchFieldA11yIds, buildTabGroupA11yIds, buttonActionSemanticPurposes, buttonPurposeSemantics, buttonPurposes, buttonVariantVisualStyles, buttonWhySemanticComponents, canonicalSemanticAttributeNames, canonicalSemanticAttributeRegistry, canonicalSemanticAttributes, cardPurposeComponentReference, cardWhyPurposeComponents, checkboxRecipe, createAccordionRecipe, createAvatarRecipe, createBadgeRecipe, createButtonRecipe, createCardRecipe, createDialogRecipe, createDividerRecipe, createFamilySemanticAttributes, createFontStack, createIconRecipe, createInputOtpRecipe, createInputRecipe, createPurposeSemanticAttributes, createRichTextRecipe, createSelectRecipe, createSliderRecipe, createSpacingRecipe, createSpinnerRecipe, createSwitchRecipe, createTabRecipe, createTextareaRecipe, createToastRecipe, createTooltipRecipe, currencyCodes, darkThemeDefaults, densityToCSSVars, dialogPurposeComponentReference, dialogPurposeSemantics, dialogPurposes, dialogWhyPurposeComponents, emptySemanticAttributes, escapeRichTextHtml, extractFontFamilyName, extractUsedWeights, familySemanticsRegistry, fieldComparisonRows, fieldWhyPurposeComponents, filterUndefinedSemanticAttributes, getCurrencySymbol, headingRecipe, iconNames, iconNamesList, iconRegistry, iconSizeScale, iconStrokeWidthScale, isRichTextHtmlEmpty, isSystemFont, isThemeMode, isThemePreference, lightThemeDefaults, mergeIdRefs, mergeSemanticAttributes, moveTabSelection, mwAvailableFonts, mwFontFallbacks, mwGoogleFontFamilies, mwStyledTheme, mwThemeVarNames, mwThemeVars, mwVar, nextThemeMode, normalizeRichTextHtml, paragraphRecipe, purposeSemanticsRegistry, radioPurposeComponentReference, radioRecipe, radioWhyPurposeComponents, resolveAccordionA11y, resolveAvatarA11y, resolveBadgeA11y, resolveButtonLoading, resolveDialogA11y, resolveIconA11y, resolveIconSize, resolveIconStrokeWidth, resolveRichTextAllowedFormats, resolveSelectMode, resolveSliderA11y, resolveSpinnerA11y, resolveSpinnerSize, resolveSwitchA11y, resolveTabA11y, resolveTabValue, resolveThemeInput, resolveThemePreference, resolveToastA11y, resolveTone, resolveTooltipA11y, richTextCommandByFormat, richTextFormattingReference, richTextWhyUseIt, sanitizeCurrencyValue, sanitizeInputOtpValue, semanticFamilies, semanticFrameworkSupport, semanticIntents, semanticLayers, semanticOrientations, semanticOutcomes, semanticPurposes, shouldLoadGoogleFont, sliderPurposeComponentReference, sliderWhyPurposeComponents, spinnerSizeScale, spinnerSizes, spinnerVariants, storybookA11yPolicy, storybookButtonGeneralArgTypes, storybookButtonIconArgTypes, storybookButtonPurposeArgTypes, storybookCheckboxArgTypes, storybookDividerArgTypes, storybookDocsDescription, storybookIconGalleryArgTypes, storybookIconGalleryDefaults, storybookIconNames, storybookLayout, storybookOptionalIconNames, storybookRadioArgTypes, storybookSliderArgTypes, storybookSpacingArgTypes, storybookSpinnerArgTypes, switchPurposeComponentReference, switchWhyPurposeComponents, tabPurposeComponentReference, tabWhyPurposeComponents, themeToCSSVars, toastPurposeComponentReference, toastPurposeSemantics, toastPurposes, toastWhyPurposeComponents, validateSemanticRegistry };
+export { type AccordionA11yProps, type AccordionOptions, type AccordionRenderKit, type AvatarA11yProps, type AvatarDataAttributes, type AvatarOptions, type AvatarRenderContent, type AvatarRenderKit, AvatarSize, AvatarType, type BadgeA11yProps, type BadgeOptions, type BadgeRenderKit, BadgeVariant, type ButtonA11yProps, ButtonAction, type ButtonLoadingOptions, type ButtonOptions, type ButtonRenderKit, ButtonSize, ButtonVariant, type CardOptions, type CardRenderKit, type CheckboxA11y, type CheckboxProps, type CheckboxRenderKit, type CheckboxState, type ColorInput, type ColorRole, type CssVars, type CurrencyCode, DENSITY_SCALES, type Density, type DensityScale, type DialogA11yProps, type DialogOptions, type DialogRenderKit, type DialogSize, type DividerA11y, type DividerDataAttributes, type DividerOptions, type DividerOrientation, type DividerRenderKit, type DividerSize, type FamilySemanticDefinition, type FieldComparisonRow, type FontLoadingConfig, type FontLoadingMode, type FontLoadingOptions, type HeadingA11y, type HeadingLevel, type HeadingOptions, type HeadingRenderKit, type HeadingSize, type IconA11yProps, type IconColor, IconName, IconName as IconNameType, type IconOptions, type IconPreset, type IconRenderKit, type IconSize, type IconSizeKey, type IconStrokeWidth, type IconStrokeWidthKey, type InputA11yProps, type InputOptions, type InputOtpA11yProps, type InputOtpOptions, type InputOtpRenderKit, type InputRenderKit, type InputTone, type LabeledCopy, type MarwesThemeScriptOptions, type MarwesThemeStyleOptions, type MwAvailableFont, type MwFontFallback, type MwGoogleFontFamily, type MwStyledTheme, type MwThemeVarName, type MwThemeVarNames, type MwThemeVarReference, type MwThemeVars, type ParagraphA11y, type ParagraphOptions, type ParagraphRenderKit, type ParagraphSize, type PurposeSemanticDefinition, type RadioA11y, type RadioOptions, type RadioRenderKit, type ResolvedButtonLoading, type ResolvedTheme, type RichTextA11yProps, type RichTextFormat, type RichTextOptions, type RichTextRenderKit, type SecondaryColorRole, type SelectA11yProps, type SelectAppearance, type SelectMode, type SelectOption, type SelectOptions, type SelectRenderKit, type SemanticAttributeDefinition, type SemanticAttributeName, type SemanticAttributeValue, type SemanticAttributes, type SemanticFamily, type SemanticIntent, type SemanticLayer, type SemanticOrientation, type SemanticOutcome, type SemanticPurpose, type SliderA11yProps, type SliderDataAttributes, type SliderOptions, type SliderRenderKit, type SpacingA11y, type SpacingDataAttributes, type SpacingOptions, type SpacingRenderKit, type SpacingSize, Spacings, type SpinnerA11yProps, type SpinnerDataAttributes, type SpinnerOptions, type SpinnerRenderKit, type SpinnerSize, type SpinnerSvgDefinition, type SpinnerSvgElement, type SpinnerSvgNode, SpinnerVariant, SpinnerVariants, type SvgElementType, type SvgNode, type SwitchA11yProps, type SwitchOptions, type SwitchRenderKit, SwitchSize, type SystemThemeMode, type TabA11yProps, type TabGroupA11yIds, type TabGroupItemState, type TabNavigationDirection, type TabOptions, type TabRenderKit, type TextareaA11yProps, type TextareaOptions, type TextareaRenderKit, type TextareaResize, type Theme, type ThemeInput, type ThemeInputColor, ThemeMode, type ThemeModeAttribute, type ThemeModeCSSRulesOptions, type ThemeModeRootTarget, type ThemePreference, type ThemeVariableStrategy, type ToastA11yProps, type ToastContainerOptions, type ToastIntent, type ToastOptions, type ToastPlacement, type ToastRenderKit, type ToastVariant, type ToneName, type TooltipA11yProps, type TooltipDataAttributes, type TooltipOptions, type TooltipRenderKit, accordionPurposeComponentReference, accordionWhyPurposeComponents, avatarPurposeSemantics, avatarPurposes, badgePurposeComponentReference, badgePurposeSemantics, badgePurposes, badgeWhyPurposeComponents, buildAccordionFieldA11yIds, buildCheckboxA11y, buildCheckboxFieldA11yIds, buildCheckboxGroupFieldA11yIds, buildCurrencyHelperText, buildGoogleFontsUrl, buildHeadingA11y, buildInputFieldA11yIds, buildRadioA11y, buildRadioGroupFieldA11yIds, buildRichTextFieldA11yIds, buildSliderFieldA11yIds, buildSwitchFieldA11yIds, buildTabGroupA11yIds, buttonActionSemanticPurposes, buttonPurposeSemantics, buttonPurposes, buttonVariantVisualStyles, buttonWhySemanticComponents, canonicalSemanticAttributeNames, canonicalSemanticAttributeRegistry, canonicalSemanticAttributes, cardPurposeComponentReference, cardWhyPurposeComponents, checkboxRecipe, createAccordionRecipe, createAvatarRecipe, createBadgeRecipe, createButtonRecipe, createCardRecipe, createDialogRecipe, createDividerRecipe, createFamilySemanticAttributes, createFontStack, createIconRecipe, createInputOtpRecipe, createInputRecipe, createMarwesThemeScript, createMarwesThemeStyle, createPurposeSemanticAttributes, createRichTextRecipe, createSelectRecipe, createSliderRecipe, createSpacingRecipe, createSpinnerRecipe, createSwitchRecipe, createTabRecipe, createTextareaRecipe, createToastRecipe, createTooltipRecipe, currencyCodes, darkThemeDefaults, densityToCSSVars, dialogPurposeComponentReference, dialogPurposeSemantics, dialogPurposes, dialogWhyPurposeComponents, emptySemanticAttributes, escapeRichTextHtml, extractFontFamilyName, extractUsedWeights, familySemanticsRegistry, fieldComparisonRows, fieldWhyPurposeComponents, filterUndefinedSemanticAttributes, getCurrencySymbol, headingRecipe, iconNames, iconNamesList, iconRegistry, iconSizeScale, iconStrokeWidthScale, isRichTextHtmlEmpty, isSystemFont, isThemeMode, isThemePreference, lightThemeDefaults, mergeIdRefs, mergeSemanticAttributes, moveTabSelection, mwAvailableFonts, mwFontFallbacks, mwGoogleFontFamilies, mwStyledTheme, mwThemeVarNames, mwThemeVars, mwVar, nextThemeMode, normalizeRichTextHtml, paragraphRecipe, purposeSemanticsRegistry, radioPurposeComponentReference, radioRecipe, radioWhyPurposeComponents, resolveAccordionA11y, resolveAvatarA11y, resolveBadgeA11y, resolveButtonLoading, resolveDialogA11y, resolveIconA11y, resolveIconSize, resolveIconStrokeWidth, resolveRichTextAllowedFormats, resolveSelectMode, resolveServerThemeMode, resolveSliderA11y, resolveSpinnerA11y, resolveSpinnerSize, resolveSwitchA11y, resolveTabA11y, resolveTabValue, resolveThemeInput, resolveThemePreference, resolveToastA11y, resolveTone, resolveTooltipA11y, richTextCommandByFormat, richTextFormattingReference, richTextWhyUseIt, sanitizeCurrencyValue, sanitizeInputOtpValue, semanticFamilies, semanticFrameworkSupport, semanticIntents, semanticLayers, semanticOrientations, semanticOutcomes, semanticPurposes, shouldLoadGoogleFont, sliderPurposeComponentReference, sliderWhyPurposeComponents, spinnerSizeScale, spinnerSizes, spinnerVariants, storybookA11yPolicy, storybookButtonGeneralArgTypes, storybookButtonIconArgTypes, storybookButtonPurposeArgTypes, storybookCheckboxArgTypes, storybookDividerArgTypes, storybookDocsDescription, storybookIconGalleryArgTypes, storybookIconGalleryDefaults, storybookIconNames, storybookLayout, storybookOptionalIconNames, storybookRadioArgTypes, storybookSliderArgTypes, storybookSpacingArgTypes, storybookSpinnerArgTypes, switchPurposeComponentReference, switchWhyPurposeComponents, tabPurposeComponentReference, tabWhyPurposeComponents, themeModesToCSSRules, themeToCSSRule, themeToCSSVars, toastPurposeComponentReference, toastPurposeSemantics, toastPurposes, toastWhyPurposeComponents, validateSemanticRegistry };