@refraction-ui/react 0.12.2 → 0.13.0

package/dist/internal/react-status-indicator/index.d.cts

@@ -1,32 +1,19 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import { StatusType } from '../status-indicator/index.cjs';
 export { StatusProps as CoreStatusProps, STATUS_COLORS, STATUS_LABELS, StatusAPI, StatusType, statusContainerStyles, statusDotVariants, statusLabelStyles, statusPulseVariants } from '../status-indicator/index.cjs';
 
 interface StatusIndicatorProps {
     type: StatusType;
+    /** Explicit text label. Takes precedence over `children`. */
     label?: string;
+    /** Composable label content. Used when `label` is omitted. */
+    children?: React.ReactNode;
     pulse?: boolean;
     showLabel?: boolean;
     className?: string;
 }
-declare function StatusIndicator({ type, label, pulse, showLabel, className, }: StatusIndicatorProps): React.DetailedReactHTMLElement<{
-    className: string;
-    role?: string | undefined;
-    tabIndex?: number | undefined;
-    'aria-label'?: string | undefined;
-    'aria-labelledby'?: string | undefined;
-    'aria-describedby'?: string | undefined;
-    'aria-controls'?: string | undefined;
-    'aria-expanded'?: boolean | undefined;
-    'aria-selected'?: boolean | undefined;
-    'aria-hidden'?: boolean | undefined;
-    'aria-disabled'?: boolean | undefined;
-    'aria-pressed'?: boolean | "mixed" | undefined;
-    'aria-checked'?: boolean | "mixed" | undefined;
-    'aria-current'?: boolean | "page" | "step" | "location" | "date" | "time" | undefined;
-    'aria-live'?: "off" | "assertive" | "polite" | undefined;
-    'aria-atomic'?: boolean | undefined;
-}, HTMLElement>;
+declare function StatusIndicator({ type, label, children, pulse, showLabel, className, }: StatusIndicatorProps): react_jsx_runtime.JSX.Element;
 declare namespace StatusIndicator {
     var displayName: string;
 }

package/dist/internal/react-status-indicator/index.d.ts

@@ -1,32 +1,19 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import { StatusType } from '../status-indicator/index.js';
 export { StatusProps as CoreStatusProps, STATUS_COLORS, STATUS_LABELS, StatusAPI, StatusType, statusContainerStyles, statusDotVariants, statusLabelStyles, statusPulseVariants } from '../status-indicator/index.js';
 
 interface StatusIndicatorProps {
     type: StatusType;
+    /** Explicit text label. Takes precedence over `children`. */
     label?: string;
+    /** Composable label content. Used when `label` is omitted. */
+    children?: React.ReactNode;
     pulse?: boolean;
     showLabel?: boolean;
     className?: string;
 }
-declare function StatusIndicator({ type, label, pulse, showLabel, className, }: StatusIndicatorProps): React.DetailedReactHTMLElement<{
-    className: string;
-    role?: string | undefined;
-    tabIndex?: number | undefined;
-    'aria-label'?: string | undefined;
-    'aria-labelledby'?: string | undefined;
-    'aria-describedby'?: string | undefined;
-    'aria-controls'?: string | undefined;
-    'aria-expanded'?: boolean | undefined;
-    'aria-selected'?: boolean | undefined;
-    'aria-hidden'?: boolean | undefined;
-    'aria-disabled'?: boolean | undefined;
-    'aria-pressed'?: boolean | "mixed" | undefined;
-    'aria-checked'?: boolean | "mixed" | undefined;
-    'aria-current'?: boolean | "page" | "step" | "location" | "date" | "time" | undefined;
-    'aria-live'?: "off" | "assertive" | "polite" | undefined;
-    'aria-atomic'?: boolean | undefined;
-}, HTMLElement>;
+declare function StatusIndicator({ type, label, children, pulse, showLabel, className, }: StatusIndicatorProps): react_jsx_runtime.JSX.Element;
 declare namespace StatusIndicator {
     var displayName: string;
 }

package/dist/internal/react-theme/index.d.cts

@@ -28,14 +28,32 @@ declare function ThemeToggle({ className, variant }: ThemeToggleProps): React.De
 }, HTMLDivElement>;
 
 interface ThemeScriptProps {
+    /** localStorage key the ThemeProvider reads. */
     storageKey?: string;
+    /** Attribute strategy. `class` toggles `light`/`dark` on <html>; otherwise an HTML attribute. */
     attribute?: 'class' | 'data-theme';
+    /**
+     * Theme to apply when nothing is stored. Match this to `<ThemeProvider defaultMode>`
+     * so the pre-paint script and provider agree on the no-storage path. Defaults
+     * to `'system'` (current behaviour — OS preference wins). Issue #317.
+     */
+    defaultMode?: ThemeMode;
+    /**
+     * When `false` the inline script never reads `prefers-color-scheme`; the
+     * `defaultMode` is applied as-is for first-time visitors. Default `true`.
+     */
+    enableSystem?: boolean;
 }
 /**
  * Renders an inline <script> that prevents theme flash on SSR pages.
  * Place this in the <head> of your document (in Next.js layout.tsx, Remix root, etc.)
+ *
+ * Mirror the props your <ThemeProvider> uses so first-paint and React mount stay in sync:
+ *
+ *     <ThemeScript defaultMode="light" storageKey="app_theme" />
+ *     <ThemeProvider defaultMode="light" storageKey="app_theme">…</ThemeProvider>
  */
-declare function ThemeScript({ storageKey, attribute, }: ThemeScriptProps): React.DetailedReactHTMLElement<{
+declare function ThemeScript({ storageKey, attribute, defaultMode, enableSystem, }: ThemeScriptProps): React.DetailedReactHTMLElement<{
     dangerouslySetInnerHTML: {
         __html: string;
     };

package/dist/internal/react-theme/index.d.ts

@@ -28,14 +28,32 @@ declare function ThemeToggle({ className, variant }: ThemeToggleProps): React.De
 }, HTMLDivElement>;
 
 interface ThemeScriptProps {
+    /** localStorage key the ThemeProvider reads. */
     storageKey?: string;
+    /** Attribute strategy. `class` toggles `light`/`dark` on <html>; otherwise an HTML attribute. */
     attribute?: 'class' | 'data-theme';
+    /**
+     * Theme to apply when nothing is stored. Match this to `<ThemeProvider defaultMode>`
+     * so the pre-paint script and provider agree on the no-storage path. Defaults
+     * to `'system'` (current behaviour — OS preference wins). Issue #317.
+     */
+    defaultMode?: ThemeMode;
+    /**
+     * When `false` the inline script never reads `prefers-color-scheme`; the
+     * `defaultMode` is applied as-is for first-time visitors. Default `true`.
+     */
+    enableSystem?: boolean;
 }
 /**
  * Renders an inline <script> that prevents theme flash on SSR pages.
  * Place this in the <head> of your document (in Next.js layout.tsx, Remix root, etc.)
+ *
+ * Mirror the props your <ThemeProvider> uses so first-paint and React mount stay in sync:
+ *
+ *     <ThemeScript defaultMode="light" storageKey="app_theme" />
+ *     <ThemeProvider defaultMode="light" storageKey="app_theme">…</ThemeProvider>
  */
-declare function ThemeScript({ storageKey, attribute, }: ThemeScriptProps): React.DetailedReactHTMLElement<{
+declare function ThemeScript({ storageKey, attribute, defaultMode, enableSystem, }: ThemeScriptProps): React.DetailedReactHTMLElement<{
     dangerouslySetInnerHTML: {
         __html: string;
     };

package/dist/internal/segmented-control/index.d.cts

@@ -0,0 +1,56 @@
+import { AccessibilityProps } from '../shared/index.cjs';
+
+type SegmentedControlSize = 'sm' | 'md';
+/** Value identifying a single segment. */
+type SegmentedControlValue = string;
+interface SegmentedControlProps {
+    /** Currently selected segment value (controlled). */
+    value?: SegmentedControlValue;
+    /** Visual size of the control. */
+    size?: SegmentedControlSize;
+}
+interface SegmentedControlAPI {
+    /** ARIA attributes to spread on the group element. */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Data attributes for CSS styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Build the framework-agnostic group props for a segmented control.
+ *
+ * Returns `role="radiogroup"` plus data attributes; adapters spread these
+ * onto their group element and handle their own rendering/state.
+ */
+declare function createSegmentedControl(props?: SegmentedControlProps): SegmentedControlAPI;
+/**
+ * Pure keyboard-navigation rule shared by every adapter.
+ *
+ * Given the current index, the pressed key, and the item count, returns the
+ * index that focus/selection should move to. Arrow keys wrap; Home/End jump
+ * to the ends. Unhandled keys (or an empty group) return `current` unchanged.
+ *
+ * - ArrowRight / ArrowDown → next (wraps to 0 past the end)
+ * - ArrowLeft  / ArrowUp   → previous (wraps to last before 0)
+ * - Home                   → first
+ * - End                    → last
+ */
+declare function getNextSegmentIndex(current: number, key: string, count: number): number;
+
+/** Pill-shaped container that holds the segments (`role="radiogroup"`). */
+declare const segmentedControlVariants: (props?: ({
+    size?: "sm" | "md" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * A single segment (`role="radio"`). The `state` variant carries the
+ * active vs inactive visual treatment so adapters never inline these classes.
+ */
+declare const segmentedControlItemVariants: (props?: ({
+    size?: "sm" | "md" | undefined;
+    state?: "checked" | "unchecked" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type SegmentedControlAPI, type SegmentedControlProps, type SegmentedControlSize, type SegmentedControlValue, createSegmentedControl, getNextSegmentIndex, segmentedControlItemVariants, segmentedControlVariants };

package/dist/internal/segmented-control/index.d.ts

@@ -0,0 +1,56 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+type SegmentedControlSize = 'sm' | 'md';
+/** Value identifying a single segment. */
+type SegmentedControlValue = string;
+interface SegmentedControlProps {
+    /** Currently selected segment value (controlled). */
+    value?: SegmentedControlValue;
+    /** Visual size of the control. */
+    size?: SegmentedControlSize;
+}
+interface SegmentedControlAPI {
+    /** ARIA attributes to spread on the group element. */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Data attributes for CSS styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Build the framework-agnostic group props for a segmented control.
+ *
+ * Returns `role="radiogroup"` plus data attributes; adapters spread these
+ * onto their group element and handle their own rendering/state.
+ */
+declare function createSegmentedControl(props?: SegmentedControlProps): SegmentedControlAPI;
+/**
+ * Pure keyboard-navigation rule shared by every adapter.
+ *
+ * Given the current index, the pressed key, and the item count, returns the
+ * index that focus/selection should move to. Arrow keys wrap; Home/End jump
+ * to the ends. Unhandled keys (or an empty group) return `current` unchanged.
+ *
+ * - ArrowRight / ArrowDown → next (wraps to 0 past the end)
+ * - ArrowLeft  / ArrowUp   → previous (wraps to last before 0)
+ * - Home                   → first
+ * - End                    → last
+ */
+declare function getNextSegmentIndex(current: number, key: string, count: number): number;
+
+/** Pill-shaped container that holds the segments (`role="radiogroup"`). */
+declare const segmentedControlVariants: (props?: ({
+    size?: "sm" | "md" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * A single segment (`role="radio"`). The `state` variant carries the
+ * active vs inactive visual treatment so adapters never inline these classes.
+ */
+declare const segmentedControlItemVariants: (props?: ({
+    size?: "sm" | "md" | undefined;
+    state?: "checked" | "unchecked" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type SegmentedControlAPI, type SegmentedControlProps, type SegmentedControlSize, type SegmentedControlValue, createSegmentedControl, getNextSegmentIndex, segmentedControlItemVariants, segmentedControlVariants };

package/dist/internal/separator/index.d.cts

@@ -0,0 +1,55 @@
+import { AccessibilityProps } from '../shared/index.cjs';
+
+type SeparatorOrientation = 'horizontal' | 'vertical';
+interface SeparatorProps {
+    /** Orientation of the separator. Defaults to `'horizontal'`. */
+    orientation?: SeparatorOrientation;
+    /**
+     * When `true` (the default) the separator is purely visual and is hidden
+     * from assistive tech (`role="none"`). When `false` it is exposed as a
+     * semantic `role="separator"` with the appropriate `aria-orientation`.
+     */
+    decorative?: boolean;
+}
+/**
+ * ARIA attributes for a separator. Extends the shared base with
+ * `aria-orientation`, which is specific to the `separator` role.
+ */
+interface SeparatorAriaProps extends Partial<AccessibilityProps> {
+    'aria-orientation'?: SeparatorOrientation;
+}
+interface SeparatorAPI {
+    /** ARIA attributes to spread on the element. */
+    ariaProps: SeparatorAriaProps;
+    /** Data attributes for CSS styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Headless separator core — computes ARIA semantics and data attributes for
+ * a separator rule. JSX-free so it can be shared across framework adapters.
+ *
+ * Per ARIA, a decorative separator must not be announced (`role="none"`),
+ * while a semantic one exposes `role="separator"` and `aria-orientation`.
+ */
+declare function createSeparator(props?: SeparatorProps): SeparatorAPI;
+
+/**
+ * Visual variants for the separator rule.
+ *
+ * - `orientation: horizontal` → a full-width 1px line.
+ * - `orientation: vertical` → a full-height 1px line.
+ * - `labeled` → flex layout used by the labeled-divider variant, which
+ *   arranges a centered label between two flanking lines.
+ */
+declare const separatorVariants: (props?: ({
+    orientation?: "horizontal" | "vertical" | undefined;
+    labeled?: "true" | "false" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Class for each flanking line in the labeled-divider variant. */
+declare const separatorLineClass = "h-px flex-1 bg-border";
+/** Class for the centered label in the labeled-divider variant. */
+declare const separatorLabelClass = "px-3 text-xs uppercase tracking-wide text-muted-foreground";
+
+export { type SeparatorAPI, type SeparatorOrientation, type SeparatorProps, createSeparator, separatorLabelClass, separatorLineClass, separatorVariants };

package/dist/internal/separator/index.d.ts

@@ -0,0 +1,55 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+type SeparatorOrientation = 'horizontal' | 'vertical';
+interface SeparatorProps {
+    /** Orientation of the separator. Defaults to `'horizontal'`. */
+    orientation?: SeparatorOrientation;
+    /**
+     * When `true` (the default) the separator is purely visual and is hidden
+     * from assistive tech (`role="none"`). When `false` it is exposed as a
+     * semantic `role="separator"` with the appropriate `aria-orientation`.
+     */
+    decorative?: boolean;
+}
+/**
+ * ARIA attributes for a separator. Extends the shared base with
+ * `aria-orientation`, which is specific to the `separator` role.
+ */
+interface SeparatorAriaProps extends Partial<AccessibilityProps> {
+    'aria-orientation'?: SeparatorOrientation;
+}
+interface SeparatorAPI {
+    /** ARIA attributes to spread on the element. */
+    ariaProps: SeparatorAriaProps;
+    /** Data attributes for CSS styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Headless separator core — computes ARIA semantics and data attributes for
+ * a separator rule. JSX-free so it can be shared across framework adapters.
+ *
+ * Per ARIA, a decorative separator must not be announced (`role="none"`),
+ * while a semantic one exposes `role="separator"` and `aria-orientation`.
+ */
+declare function createSeparator(props?: SeparatorProps): SeparatorAPI;
+
+/**
+ * Visual variants for the separator rule.
+ *
+ * - `orientation: horizontal` → a full-width 1px line.
+ * - `orientation: vertical` → a full-height 1px line.
+ * - `labeled` → flex layout used by the labeled-divider variant, which
+ *   arranges a centered label between two flanking lines.
+ */
+declare const separatorVariants: (props?: ({
+    orientation?: "horizontal" | "vertical" | undefined;
+    labeled?: "true" | "false" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Class for each flanking line in the labeled-divider variant. */
+declare const separatorLineClass = "h-px flex-1 bg-border";
+/** Class for the centered label in the labeled-divider variant. */
+declare const separatorLabelClass = "px-3 text-xs uppercase tracking-wide text-muted-foreground";
+
+export { type SeparatorAPI, type SeparatorOrientation, type SeparatorProps, createSeparator, separatorLabelClass, separatorLineClass, separatorVariants };

package/dist/internal/social-auth-button/index.d.cts

@@ -0,0 +1,47 @@
+type SocialProvider = 'google' | 'github' | 'microsoft' | 'apple';
+/** "Continue with …" label shown on each provider's button. */
+declare const PROVIDER_LABELS: Record<SocialProvider, string>;
+/**
+ * Which providers render their brand mark monochrome (currentColor). GitHub and
+ * Apple are monochrome by design so they read correctly on dark/outline
+ * surfaces; Google and Microsoft keep their full brand color.
+ */
+declare const PROVIDER_MONO: Record<SocialProvider, boolean>;
+interface SocialAuthButtonProps {
+    /** Identity provider this button authenticates against. */
+    provider: SocialProvider;
+}
+interface SocialAuthButtonAPI {
+    /** Data attributes for CSS styling hooks. */
+    dataAttributes: Record<string, string>;
+    /** "Continue with …" label for the provider. */
+    label: string;
+    /** Whether the brand mark should render monochrome. */
+    mono: boolean;
+}
+/**
+ * Framework-agnostic core for a social sign-in button. Returns the provider
+ * label, monochrome hint, and the `data-provider` styling hook. No React/JSX.
+ */
+declare function createSocialAuthButton(props: SocialAuthButtonProps): SocialAuthButtonAPI;
+
+/** Wrapper around an individual social auth button (positions the lastUsed badge). */
+declare const socialAuthButtonVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Responsive grid wrapper: one column on mobile, two columns from `sm` up. */
+declare const socialAuthRowVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Floating "Last used" badge anchored to the top-right of a button. */
+declare const lastUsedBadgeVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { PROVIDER_LABELS, PROVIDER_MONO, type SocialAuthButtonAPI, type SocialAuthButtonProps, type SocialProvider, createSocialAuthButton, lastUsedBadgeVariants, socialAuthButtonVariants, socialAuthRowVariants };

package/dist/internal/social-auth-button/index.d.ts

@@ -0,0 +1,47 @@
+type SocialProvider = 'google' | 'github' | 'microsoft' | 'apple';
+/** "Continue with …" label shown on each provider's button. */
+declare const PROVIDER_LABELS: Record<SocialProvider, string>;
+/**
+ * Which providers render their brand mark monochrome (currentColor). GitHub and
+ * Apple are monochrome by design so they read correctly on dark/outline
+ * surfaces; Google and Microsoft keep their full brand color.
+ */
+declare const PROVIDER_MONO: Record<SocialProvider, boolean>;
+interface SocialAuthButtonProps {
+    /** Identity provider this button authenticates against. */
+    provider: SocialProvider;
+}
+interface SocialAuthButtonAPI {
+    /** Data attributes for CSS styling hooks. */
+    dataAttributes: Record<string, string>;
+    /** "Continue with …" label for the provider. */
+    label: string;
+    /** Whether the brand mark should render monochrome. */
+    mono: boolean;
+}
+/**
+ * Framework-agnostic core for a social sign-in button. Returns the provider
+ * label, monochrome hint, and the `data-provider` styling hook. No React/JSX.
+ */
+declare function createSocialAuthButton(props: SocialAuthButtonProps): SocialAuthButtonAPI;
+
+/** Wrapper around an individual social auth button (positions the lastUsed badge). */
+declare const socialAuthButtonVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Responsive grid wrapper: one column on mobile, two columns from `sm` up. */
+declare const socialAuthRowVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Floating "Last used" badge anchored to the top-right of a button. */
+declare const lastUsedBadgeVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { PROVIDER_LABELS, PROVIDER_MONO, type SocialAuthButtonAPI, type SocialAuthButtonProps, type SocialProvider, createSocialAuthButton, lastUsedBadgeVariants, socialAuthButtonVariants, socialAuthRowVariants };

package/dist/internal/theme/index.d.cts

@@ -43,7 +43,41 @@ declare function createTheme(config?: ThemeConfig, storage?: StorageAdapter, med
  * Inject this as a <script> tag in the <head> before any CSS.
  * Works with any framework (React, Astro, plain HTML).
  */
-declare function getThemeScript(storageKey?: string, attribute?: 'class' | 'data-theme'): string;
+
+interface ThemeScriptOptions {
+    /** localStorage key the corresponding ThemeProvider reads. */
+    storageKey?: string;
+    /** Attribute strategy: 'class' toggles `light`/`dark` classes; otherwise an HTML attribute. */
+    attribute?: 'class' | 'data-theme';
+    /**
+     * Theme to apply when nothing is stored AND `enableSystem` is false
+     * (or `defaultMode` is explicitly 'light'/'dark'). Match this to your
+     * ThemeProvider's `defaultMode` so the pre-paint script and provider agree.
+     * Defaults to `'system'` — current behavior, OS preference wins.
+     *
+     * Issue #317.
+     */
+    defaultMode?: ThemeMode;
+    /**
+     * When `true` (default) and `defaultMode === 'system'`, the script falls
+     * through to `prefers-color-scheme`. When `false`, the script applies
+     * `defaultMode` directly and never reads the OS preference.
+     */
+    enableSystem?: boolean;
+}
+/**
+ * Build the pre-paint inline script. Mirrors the resolution order used by
+ * the React/Astro `ThemeProvider`:
+ *
+ *   1. stored value (light|dark|system)
+ *   2. if no stored value: `defaultMode` (light|dark applied as-is)
+ *   3. if stored or default is 'system' AND `enableSystem`: matchMedia
+ *   4. else: 'light'
+ *
+ * Back-compat: with no options the script behaves exactly as before —
+ * stored value, then matchMedia, then 'light'.
+ */
+declare function getThemeScript(storageKeyOrOptions?: string | ThemeScriptOptions, attribute?: 'class' | 'data-theme'): string;
 
 /**
  * Browser DOM adapters for the theme machine.

package/dist/internal/theme/index.d.ts

@@ -43,7 +43,41 @@ declare function createTheme(config?: ThemeConfig, storage?: StorageAdapter, med
  * Inject this as a <script> tag in the <head> before any CSS.
  * Works with any framework (React, Astro, plain HTML).
  */
-declare function getThemeScript(storageKey?: string, attribute?: 'class' | 'data-theme'): string;
+
+interface ThemeScriptOptions {
+    /** localStorage key the corresponding ThemeProvider reads. */
+    storageKey?: string;
+    /** Attribute strategy: 'class' toggles `light`/`dark` classes; otherwise an HTML attribute. */
+    attribute?: 'class' | 'data-theme';
+    /**
+     * Theme to apply when nothing is stored AND `enableSystem` is false
+     * (or `defaultMode` is explicitly 'light'/'dark'). Match this to your
+     * ThemeProvider's `defaultMode` so the pre-paint script and provider agree.
+     * Defaults to `'system'` — current behavior, OS preference wins.
+     *
+     * Issue #317.
+     */
+    defaultMode?: ThemeMode;
+    /**
+     * When `true` (default) and `defaultMode === 'system'`, the script falls
+     * through to `prefers-color-scheme`. When `false`, the script applies
+     * `defaultMode` directly and never reads the OS preference.
+     */
+    enableSystem?: boolean;
+}
+/**
+ * Build the pre-paint inline script. Mirrors the resolution order used by
+ * the React/Astro `ThemeProvider`:
+ *
+ *   1. stored value (light|dark|system)
+ *   2. if no stored value: `defaultMode` (light|dark applied as-is)
+ *   3. if stored or default is 'system' AND `enableSystem`: matchMedia
+ *   4. else: 'light'
+ *
+ * Back-compat: with no options the script behaves exactly as before —
+ * stored value, then matchMedia, then 'light'.
+ */
+declare function getThemeScript(storageKeyOrOptions?: string | ThemeScriptOptions, attribute?: 'class' | 'data-theme'): string;
 
 /**
  * Browser DOM adapters for the theme machine.

package/dist/theme.cjs

@@ -90,8 +90,29 @@ function createTheme(config = {}, storage, mediaQuery) {
     }
   };
 }
-function getThemeScript(storageKey = "rfr-theme", attribute = "class") {
-  return `(function(){try{var m=localStorage.getItem('${storageKey}');var s=window.matchMedia('(prefers-color-scheme:dark)').matches;var t=m==='dark'||(m!=='light'&&s)?'dark':'light';var d=document.documentElement;${attribute === "class" ? "d.classList.remove('light','dark');d.classList.add(t);" : `d.setAttribute('${attribute}',t);`}d.style.colorScheme=t;}catch(e){}})()`;
+function getThemeScript(storageKeyOrOptions = "rfr-theme", attribute = "class") {
+  const opts = typeof storageKeyOrOptions === "string" ? {
+    storageKey: storageKeyOrOptions,
+    attribute,
+    defaultMode: "system",
+    enableSystem: true
+  } : {
+    storageKey: storageKeyOrOptions.storageKey ?? "rfr-theme",
+    attribute: storageKeyOrOptions.attribute ?? "class",
+    defaultMode: storageKeyOrOptions.defaultMode ?? "system",
+    enableSystem: storageKeyOrOptions.enableSystem ?? true
+  };
+  const noSystemFallback = opts.defaultMode === "light" || opts.defaultMode === "dark" || !opts.enableSystem;
+  const safeDefault = opts.defaultMode === "dark" ? "dark" : "light";
+  const resolveExpr = noSystemFallback ? (
+    // Stored wins → else hard default. No matchMedia call at all.
+    `var t=m==='dark'?'dark':(m==='light'?'light':'${safeDefault}');`
+  ) : (
+    // Original behaviour: stored → else matchMedia → else light.
+    `var s=window.matchMedia('(prefers-color-scheme:dark)').matches;var t=m==='dark'||(m!=='light'&&s)?'dark':'light';`
+  );
+  const applyExpr = opts.attribute === "class" ? "d.classList.remove('light','dark');d.classList.add(t);" : `d.setAttribute('${opts.attribute}',t);`;
+  return `(function(){try{var m=localStorage.getItem('${opts.storageKey}');${resolveExpr}var d=document.documentElement;${applyExpr}d.style.colorScheme=t;}catch(e){}})()`;
 }
 function createLocalStorageAdapter() {
   return {
@@ -330,11 +351,13 @@ function ThemeToggle({ className, variant = "segmented" }) {
 }
 function ThemeScript({
   storageKey = "rfr-theme",
-  attribute = "class"
+  attribute = "class",
+  defaultMode = "system",
+  enableSystem = true
 }) {
   return React2__namespace.createElement("script", {
     dangerouslySetInnerHTML: {
-      __html: getThemeScript(storageKey, attribute)
+      __html: getThemeScript({ storageKey, attribute, defaultMode, enableSystem })
     }
   });
 }