ssr-themes 0.0.1-alpha.1

package/LICENSE.md

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,607 @@
+# ssr-themes ![ssr-themes minzip package size](https://img.shields.io/bundlephobia/minzip/ssr-themes) [![Version](https://img.shields.io/npm/v/ssr-themes.svg?colorB=green)](https://www.npmjs.com/package/ssr-themes)
+
+Themes for your React SSR app.
+
+- ✅ Perfect dark mode with no flashing
+- ✅ System setting with `prefers-color-scheme`
+- ✅ Themed browser UI with color-scheme
+- ✅ SSR support for all frameworks (including TanStack Start/Next)
+- ✅ Easy Tailwind integration
+- ✅ Sync theme across tabs
+- ✅ `useTheme` hook
+
+Check out the live examples:
+
+- Tanstack Start: []
+- Next: []
+
+## Install
+
+```bash
+npm install ssr-themes
+# or
+bun add ssr-themes
+# or
+pnpm install ssr-themes
+# or
+yarn add ssr-themes
+```
+
+## Use
+
+### With TanStack Start
+
+Add `ThemeProvider` to your root route and render `HeadContent`/`Scripts` in the document:
+
+```tsx
+// src/routes/__root.tsx
+import {
+  HeadContent,
+  Outlet,
+  Scripts,
+  createRootRoute,
+} from '@tanstack/react-router';
+import type {ReactNode} from 'react';
+import {ThemeProvider} from 'ssr-themes';
+import appCss from '../styles.css?url';
+
+function RootDocument({children}: {children: ReactNode}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <ThemeProvider attribute="class">{children}</ThemeProvider>
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export const Route = createRootRoute({
+  head: () => ({
+    links: [{rel: 'stylesheet', href: appCss}],
+  }),
+  component: function RootComponent() {
+    return (
+      <RootDocument>
+        <Outlet />
+      </RootDocument>
+    );
+  },
+});
+```
+
+> **Note!** If you do not add [suppressHydrationWarning](https://reactjs.org/docs/dom-elements.html#suppresshydrationwarning:~:text=It%20only%20works%20one%20level%20deep) to your `<html>` you will get warnings because `ssr-themes` updates that element. This property only applies one level deep, so it won't block hydration warnings on other elements.
+
+### SSR / RSC
+
+`ssr-themes` uses cookies to set the theme, so the server can use `registerTheme` to read cookies and apply the right value directly to `<html>`. The inline script will reuse that value and skip cookie reads when the theme attribute/class is already present on the `<html>` element.
+
+```tsx
+import {registerTheme, ThemeProvider} from 'ssr-themes';
+import {cookies} from 'next/headers';
+
+const cookieStore = await cookies();
+const theme = cookieStore.get('theme'); // 'dark' | 'light' | undefined
+const htmlProps = registerTheme({
+  theme,
+  attribute: 'class',
+});
+
+return (
+  <html suppressHydrationWarning {...htmlProps}>
+    <body>
+      <ThemeProvider attribute="class">{children}</ThemeProvider>
+    </body>
+  </html>
+);
+```
+
+### HTML & CSS
+
+That's it, your app fully supports dark mode, including System preference with `prefers-color-scheme`. The theme is also immediately synced between tabs. By default, ssr-themes modifies the `data-theme` attribute on the `html` element, which you can easily use to style your app:
+
+```css
+:root {
+  /* Your default theme */
+  --background: white;
+  --foreground: black;
+}
+
+[data-theme='dark'] {
+  --background: black;
+  --foreground: white;
+}
+```
+
+> **Note!** If you set the attribute of your Theme Provider to class for Tailwind ssr-themes will modify the `class` attribute on the `html` element. See [With TailwindCSS](#with-tailwindcss).
+
+### useTheme
+
+Your UI will need to know the current theme and be able to change it. The `useTheme` hook provides theme information:
+
+```jsx
+import {useTheme} from 'ssr-themes';
+
+const ThemeChanger = () => {
+  const {theme, setTheme} = useTheme();
+
+  return (
+    <div>
+      The current theme is: {theme}
+      <button onClick={() => setTheme('light')}>Light Mode</button>
+      <button onClick={() => setTheme('dark')}>Dark Mode</button>
+    </div>
+  );
+};
+```
+
+> **Warning!** The above code is hydration _unsafe_ and will throw a hydration mismatch warning when rendering with SSG or SSR. This is because we cannot know the `theme` on the server, so it will always be `undefined` until mounted on the client.
+>
+> You should delay rendering any theme toggling UI until mounted on the client. See the [example](#avoid-hydration-mismatch).
+
+## API
+
+Let's dig into the details.
+
+### ThemeProvider
+
+All your theme configuration is passed to ThemeProvider.
+
+- `cookie = { name: 'theme', path: '/', maxAge: 31536000, sameSite: 'lax' }`: Cookie configuration for the theme cookie
+- `defaultTheme = 'system'`: Default theme name (for v0.0.12 and lower the default was `light`). If `enableSystem` is false, the default theme is `light`
+- `forcedTheme`: Forced theme name for the current page (does not modify saved theme settings)
+- `enableSystem = true`: Whether to switch between `dark` and `light` based on `prefers-color-scheme`
+- `enableColorScheme = true`: Whether to indicate to browsers which color scheme is used (dark or light) for built-in UI like inputs and buttons
+- `disableTransitionOnChange = false`: Optionally disable all CSS transitions when switching themes ([example](#disable-transitions-on-theme-change))
+- `themes = ['light', 'dark']`: List of theme names
+- `attribute = 'data-theme'`: HTML attribute modified based on the active theme
+  - accepts `class` and `data-*` (meaning any data attribute, `data-mode`, `data-color`, etc.) ([example](#class-instead-of-data-attribute))
+- `value`: Optional mapping of theme name to attribute value
+  - value is an `object` where key is the theme name and value is the attribute value ([example](#differing-dom-attribute-and-theme-name))
+- `nonce`: Optional nonce passed to the injected `script` tag, used to allow-list the ssr-themes script in your CSP
+- `scriptProps`: Optional props to pass to the injected `script` tag ([example](#using-with-cloudflare-rocket-loader))
+
+### registerTheme
+
+Use `registerTheme` to generate props for your `<html>` element on the server. When a theme is provided, it applies the theme attribute/class and sets `color-scheme` (if enabled), so the client script treats the existing HTML value as authoritative.
+
+```tsx
+const htmlProps = registerTheme({
+  theme: 'dark',
+  attribute: 'class',
+});
+```
+
+If `theme` is `undefined` or `'system'`, it returns an empty object.
+
+### useTheme
+
+useTheme takes no parameters, but returns:
+
+- `theme`: Active theme name
+- `setTheme(name)`: Function to update the theme. The API is identical to the [set function](https://react.dev/reference/react/useState#setstate) returned by `useState`-hook. Pass the new theme value or use a callback to set the new theme based on the current theme.
+- `forcedTheme`: Forced page theme or falsy. If `forcedTheme` is set, you should disable any theme switching UI
+- `resolvedTheme`: If `enableSystem` is true and the active theme is "system", this returns whether the system preference resolved to "dark" or "light". Otherwise, identical to `theme`
+- `systemTheme`: If `enableSystem` is true, represents the System theme preference ("dark" or "light"), regardless what the active theme is
+- `themes`: The list of themes passed to `ThemeProvider` (with "system" appended, if `enableSystem` is true)
+
+Not too bad, right? Let's see how to use these properties with examples:
+
+## Examples
+
+The [Live Example](https://ssr-themes-example.vercel.app/) shows ssr-themes in action, with dark, light, system themes and pages with forced themes.
+
+### Use System preference by default
+
+For versions above v0.0.12, the `defaultTheme` is automatically set to "system", so to use System preference you can simply use:
+
+```jsx
+<ThemeProvider>
+```
+
+### Ignore System preference
+
+If you don't want a System theme, disable it via `enableSystem`:
+
+```jsx
+<ThemeProvider enableSystem={false}>
+```
+
+### Class instead of data attribute
+
+If your app uses a class to style the page based on the theme, change the attribute prop to `class`:
+
+```jsx
+<ThemeProvider attribute="class">
+```
+
+Now, setting the theme to "dark" will set `class="dark"` on the `html` element.
+
+### Force page to a theme
+
+Let's say your cool new marketing page is dark mode only. The page should always use the dark theme, and changing the theme should have no effect. In TanStack Start, add static data to the route and read it in the root route:
+
+```tsx
+// src/routes/dark.tsx
+import {createFileRoute} from '@tanstack/react-router';
+
+export const Route = createFileRoute('/dark')({
+  staticData: {theme: 'dark'},
+  component: DarkPage,
+});
+```
+
+```tsx
+// src/routes/__root.tsx
+import { useMatches } from '@tanstack/react-router'
+
+const matches = useMatches()
+const forcedTheme = matches.reduce<string | undefined>((theme, match) => {
+  const staticData = match.staticData as { theme?: string } | undefined
+  return staticData?.theme ?? theme
+}, undefined)
+
+<ThemeProvider forcedTheme={forcedTheme} attribute="class">
+  {children}
+</ThemeProvider>
+```
+
+Done! Your page is always dark theme (regardless of user preference), and calling `setTheme` from `useTheme` is now a no-op. However, you should make sure to disable any of your UI that would normally change the theme:
+
+```js
+const {forcedTheme} = useTheme();
+
+// Theme is forced, we shouldn't allow user to change the theme
+const disabled = !!forcedTheme;
+```
+
+### Disable transitions on theme change
+
+I wrote about [this technique here](https://paco.sh/blog/disable-theme-transitions). We can forcefully disable all CSS transitions before the theme is changed, and re-enable them immediately afterwards. This ensures your UI with different transition durations won't feel inconsistent when changing the theme.
+
+To enable this behavior, pass the `disableTransitionOnChange` prop:
+
+```jsx
+<ThemeProvider disableTransitionOnChange>
+```
+
+### Differing DOM attribute and theme name
+
+The name of the active theme is used as both the cookie value and the value of the DOM attribute. If the theme name is "pink", the cookie will contain `theme=pink` and the DOM will be `data-theme="pink"`. You **cannot** modify the cookie value, but you **can** modify the DOM value.
+
+If we want the DOM to instead render `data-theme="my-pink-theme"` when the theme is "pink", pass the `value` prop:
+
+```jsx
+<ThemeProvider value={{ pink: 'my-pink-theme' }}>
+```
+
+Done! To be extra clear, this affects only the DOM. Here's how all the values will look:
+
+```js
+const {theme} = useTheme();
+// => "pink"
+
+document.cookie;
+// => "theme=pink"
+
+document.documentElement.getAttribute('data-theme');
+// => "my-pink-theme"
+```
+
+### Using with Cloudflare Rocket Loader
+
+[Rocket Loader](https://developers.cloudflare.com/fundamentals/speed/rocket-loader/) is a Cloudflare optimization that defers the loading of inline and external scripts to prioritize the website content. Since ssr-themes relies on a script injection to avoid screen flashing on page load, Rocket Loader breaks this functionality. Individual scripts [can be ignored](https://developers.cloudflare.com/fundamentals/speed/rocket-loader/ignore-javascripts/) by adding the `data-cfasync="false"` attribute to the script tag:
+
+```jsx
+<ThemeProvider scriptProps={{ 'data-cfasync': 'false' }}>
+```
+
+### More than light and dark mode
+
+ssr-themes is designed to support any number of themes! Simply pass a list of themes:
+
+```jsx
+<ThemeProvider themes={['pink', 'red', 'blue']}>
+```
+
+> **Note!** When you pass `themes`, the default set of themes ("light" and "dark") are overridden. Make sure you include those if you still want your light and dark themes:
+
+```jsx
+<ThemeProvider themes={['pink', 'red', 'blue', 'light', 'dark']}>
+```
+
+For a starting point, check out `examples/example`.
+
+### Without CSS variables
+
+This library does not rely on your theme styling using CSS variables. You can hard-code the values in your CSS, and everything will work as expected (without any flashing):
+
+```css
+html,
+body {
+  color: #000;
+  background: #fff;
+}
+
+[data-theme='dark'],
+[data-theme='dark'] body {
+  color: #fff;
+  background: #000;
+}
+```
+
+### With Styled Components and any CSS-in-JS
+
+SSR Themes is completely CSS independent, it will work with any library. For example, with Styled Components you can wire `createGlobalStyle` in your root route:
+
+```tsx
+// src/routes/__root.tsx
+import {Outlet, createRootRoute} from '@tanstack/react-router';
+import {createGlobalStyle} from 'styled-components';
+import {ThemeProvider} from 'ssr-themes';
+
+// Your themeing variables
+const GlobalStyle = createGlobalStyle`
+  :root {
+    --fg: #000;
+    --bg: #fff;
+  }
+
+  [data-theme="dark"] {
+    --fg: #fff;
+    --bg: #000;
+  }
+`;
+
+function RootComponent() {
+  return (
+    <>
+      <GlobalStyle />
+      <ThemeProvider>
+        <Outlet />
+      </ThemeProvider>
+    </>
+  );
+}
+
+export const Route = createRootRoute({
+  component: RootComponent,
+});
+```
+
+### Avoid Hydration Mismatch
+
+Because we cannot know the `theme` on the server, many of the values returned from `useTheme` will be `undefined` until mounted on the client. This means if you try to render UI based on the current theme before mounting on the client, you will see a hydration mismatch error.
+
+The following code sample is **unsafe**:
+
+```jsx
+import {useTheme} from 'ssr-themes';
+
+// Do NOT use this! It will throw a hydration mismatch error.
+const ThemeSwitch = () => {
+  const {theme, setTheme} = useTheme();
+
+  return (
+    <select value={theme} onChange={e => setTheme(e.target.value)}>
+      <option value="system">System</option>
+      <option value="dark">Dark</option>
+      <option value="light">Light</option>
+    </select>
+  );
+};
+
+export default ThemeSwitch;
+```
+
+To fix this, make sure you only render UI that uses the current theme when the page is mounted on the client:
+
+```jsx
+import {useState, useEffect} from 'react';
+import {useTheme} from 'ssr-themes';
+
+const ThemeSwitch = () => {
+  const [mounted, setMounted] = useState(false);
+  const {theme, setTheme} = useTheme();
+
+  // useEffect only runs on the client, so now we can safely show the UI
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) {
+    return null;
+  }
+
+  return (
+    <select value={theme} onChange={e => setTheme(e.target.value)}>
+      <option value="system">System</option>
+      <option value="dark">Dark</option>
+      <option value="light">Light</option>
+    </select>
+  );
+};
+
+export default ThemeSwitch;
+```
+
+Alternatively, you could lazy load the component on the client side with `React.lazy`:
+
+```jsx
+import {Suspense, lazy} from 'react';
+
+const ThemeSwitch = lazy(() => import('./ThemeSwitch'));
+
+const ThemePage = () => {
+  return (
+    <Suspense fallback={null}>
+      <ThemeSwitch />
+    </Suspense>
+  );
+};
+
+export default ThemePage;
+```
+
+To avoid [Layout Shift](https://web.dev/cls/), consider rendering a skeleton/placeholder until mounted on the client side.
+
+#### Images
+
+Showing different images based on the current theme also suffers from the hydration mismatch problem. You can use a placeholder image until the theme is resolved:
+
+```jsx
+import {useTheme} from 'ssr-themes';
+
+function ThemedImage() {
+  const {resolvedTheme} = useTheme();
+  let src;
+
+  switch (resolvedTheme) {
+    case 'light':
+      src = '/light.png';
+      break;
+    case 'dark':
+      src = '/dark.png';
+      break;
+    default:
+      src =
+        'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
+      break;
+  }
+
+  return <img src={src} width={400} height={400} alt="" />;
+}
+
+export default ThemedImage;
+```
+
+#### CSS
+
+You can also use CSS to hide or show content based on the current theme. To avoid the hydration mismatch, you'll need to render _both_ versions of the UI, with CSS hiding the unused version. For example:
+
+```jsx
+function ThemedImage() {
+  return (
+    <>
+      {/* When the theme is dark, hide this div */}
+      <div data-hide-on-theme="dark">
+        <img src="light.png" width={400} height={400} alt="" />
+      </div>
+
+      {/* When the theme is light, hide this div */}
+      <div data-hide-on-theme="light">
+        <img src="dark.png" width={400} height={400} alt="" />
+      </div>
+    </>
+  );
+}
+
+export default ThemedImage;
+```
+
+```css
+[data-theme='dark'] [data-hide-on-theme='dark'],
+[data-theme='light'] [data-hide-on-theme='light'] {
+  display: none;
+}
+```
+
+### With TailwindCSS
+
+The example in `examples/example` uses Tailwind v4 with a class-based dark mode.
+
+Add the dark variant in your CSS:
+
+```css
+@import 'tailwindcss';
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+Set the attribute for your Theme Provider to `class`:
+
+```tsx
+<ThemeProvider attribute="class">
+```
+
+When the theme is dark, ssr-themes applies the `dark` class to the `html` element:
+
+```html
+<html class="dark">
+  <body>
+    <div class="bg-white dark:bg-black">
+      <!-- ... -->
+    </div>
+  </body>
+</html>
+```
+
+That's it! Now you can use dark-mode specific classes:
+
+```tsx
+<h1 className="text-black dark:text-white">
+```
+
+## Discussion
+
+### The Flash
+
+ThemeProvider automatically injects a script to update the `html` element with the correct attributes before the rest of your page loads. This means the page will not flash under any circumstances, including forced themes, system theme, multiple themes, and incognito. No `noflash.js` required.
+
+## FAQ
+
+---
+
+**Why is my page still flashing?**
+
+In dev mode, the page may still flash. When you build your app in production mode, there will be no flashing.
+
+---
+
+**Why do I get server/client mismatch error?**
+
+When using `useTheme`, you will use see a hydration mismatch error when rendering UI that relies on the current theme. This is because many of the values returned by `useTheme` are undefined on the server, since we can't read cookies until mounting on the client. See the [example](#avoid-hydration-mismatch) for how to fix this error.
+
+---
+
+**Do I need to use CSS variables with this library?**
+
+Nope. See the [example](#without-css-variables).
+
+---
+
+**Can I set the class or data attribute on the body or another element?**
+
+Nope. If you have a good reason for supporting this feature, please open an issue.
+
+---
+
+**Can I use this package with Gatsby or CRA?**
+
+Yes, starting from the 0.3.0 version.
+
+---
+
+**Is the injected script minified?**
+
+Yes.
+
+---
+
+**Why is `resolvedTheme` necessary?**
+
+When supporting the System theme preference, you want to make sure that's reflected in your UI. This means your buttons, selects, dropdowns, or whatever you use to indicate the current theme should say "System" when the System theme preference is active.
+
+If we didn't distinguish between `theme` and `resolvedTheme`, the UI would show "Dark" or "Light", when it should really be "System".
+
+`resolvedTheme` is then useful for modifying behavior or styles at runtime:
+
+```jsx
+const { resolvedTheme } = useTheme()
+
+<div style={{ color: resolvedTheme === 'dark' ? 'white' : 'black' }}>
+```
+
+If we didn't have `resolvedTheme` and only used `theme`, you'd lose information about the state of your UI (you would only know the theme is "system", and not what it resolved to).

package/dist/index.d.mts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { S as SystemThemeDefinition, T as ThemeProviderProps, U as UseThemeProps } from './server-CcYvjBJ6.mjs';
+export { A as Attribute, C as CookieConfig, a as CookieOptions, R as RegisterThemeOptions, b as SystemTheme, c as ThemeHtmlProps, r as registerTheme } from './server-CcYvjBJ6.mjs';
+
+declare const useTheme: () => UseThemeProps<SystemThemeDefinition>;
+declare const ThemeProvider: <TThemes extends readonly string[] = SystemThemeDefinition>(props: ThemeProviderProps<TThemes>) => React.JSX.Element;
+declare const ThemeScript: React.MemoExoticComponent<(<TThemes extends readonly string[]>({ forcedTheme, cookieName, attribute, enableSystem, enableColorScheme, defaultTheme, value, themes, nonce, scriptProps, }: Omit<ThemeProviderProps<TThemes>, "children" | "cookie"> & {
+    cookieName: string;
+    defaultTheme: string;
+}) => React.JSX.Element)>;
+
+export { ThemeProvider, ThemeProviderProps, ThemeScript, UseThemeProps, useTheme };

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { S as SystemThemeDefinition, T as ThemeProviderProps, U as UseThemeProps } from './server-CcYvjBJ6.js';
+export { A as Attribute, C as CookieConfig, a as CookieOptions, R as RegisterThemeOptions, b as SystemTheme, c as ThemeHtmlProps, r as registerTheme } from './server-CcYvjBJ6.js';
+
+declare const useTheme: () => UseThemeProps<SystemThemeDefinition>;
+declare const ThemeProvider: <TThemes extends readonly string[] = SystemThemeDefinition>(props: ThemeProviderProps<TThemes>) => React.JSX.Element;
+declare const ThemeScript: React.MemoExoticComponent<(<TThemes extends readonly string[]>({ forcedTheme, cookieName, attribute, enableSystem, enableColorScheme, defaultTheme, value, themes, nonce, scriptProps, }: Omit<ThemeProviderProps<TThemes>, "children" | "cookie"> & {
+    cookieName: string;
+    defaultTheme: string;
+}) => React.JSX.Element)>;
+
+export { ThemeProvider, ThemeProviderProps, ThemeScript, UseThemeProps, useTheme };

package/dist/index.js

@@ -0,0 +1 @@
+"use client";var F=Object.create;var w=Object.defineProperty;var W=Object.getOwnPropertyDescriptor;var z=Object.getOwnPropertyNames;var J=Object.getPrototypeOf,q=Object.prototype.hasOwnProperty;var G=(e,t)=>{for(var n in t)w(e,n,{get:t[n],enumerable:!0})},D=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of z(t))!q.call(e,i)&&i!==n&&w(e,i,{get:()=>t[i],enumerable:!(r=W(t,i))||r.enumerable});return e};var K=(e,t,n)=>(n=e!=null?F(J(e)):{},D(t||!e||!e.__esModule?w(n,"default",{value:e,enumerable:!0}):n,e)),X=e=>D(w({},"__esModule",{value:!0}),e);var ue={};G(ue,{ThemeProvider:()=>oe,ThemeScript:()=>j,registerTheme:()=>U,useTheme:()=>ne});module.exports=X(ue);var o=K(require("react"));var $=(e,t,n,r,i,s,a,u)=>{let d=document.documentElement,C=Array.isArray(e)?e:[e],g=[];for(let m of i){let h=s?s[m]:m;h&&g.push({theme:m,value:h})}let N=g.map(m=>m.value),p=m=>{let h=document.cookie.match(new RegExp(`(?:^|; )${m}=([^;]*)`));return h?decodeURIComponent(h[1]):void 0},y=()=>{for(let m of C){if(m==="class"){for(let l of g)if(d.classList.contains(l.value))return l.theme;continue}let h=d.getAttribute(m);if(h){for(let l of g)if(l.value===h)return l.theme}}};function k(m){let h=s?s[m]:m;for(let l of C)l==="class"?(d.classList.remove(...N),h&&d.classList.add(h)):h?d.setAttribute(l,h):d.removeAttribute(l);u&&(m==="light"||m==="dark")&&(d.style.colorScheme=m)}let S=()=>window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";if(r){k(r);return}let R=m=>a&&m==="system"?S():m,v=y();if(v){k(R(v));return}try{let m=p(t)||n;k(R(m))}catch(m){}};var U=({theme:e,attribute:t="class",value:n,enableColorScheme:r=!0}={})=>{if(!e||e==="system")return{};let i=n?n[e]:e;if(!i)return{};let s={},a=Array.isArray(t)?t:[t];for(let u of a)u==="class"?s.className=i:s[u]=i;return r&&(e==="light"||e==="dark")&&(s.style={colorScheme:e}),s};var V=["light","dark"],I="(prefers-color-scheme: dark)",Q=typeof window=="undefined",O=o.createContext(void 0),Y={setTheme:e=>{},themes:[]},Z={path:"/",maxAge:31536e3,sameSite:"lax"},ee=e=>{var t;return(t=e==null?void 0:e.name)!=null?t:"theme"},te=e=>{if(Q)return;let t=document.cookie?document.cookie.split("; "):[];for(let n of t){let[r,...i]=n.split("=");if(r===e)return decodeURIComponent(i.join("="))}},se=e=>{if(e)return`${e.charAt(0).toUpperCase()}${e.slice(1)}`},H=(e,t,n)=>{try{let r={...Z,...n!=null?n:{}},i=encodeURIComponent(t),s=[`${e}=${i}`];r.path&&s.push(`Path=${r.path}`),r.domain&&s.push(`Domain=${r.domain}`),typeof r.maxAge=="number"&&s.push(`Max-Age=${r.maxAge}`),r.expires&&s.push(`Expires=${r.expires.toUTCString()}`);let a=se(r.sameSite);a&&s.push(`SameSite=${a}`),r.secure&&s.push("Secure"),document.cookie=s.join("; ")}catch(r){}},ne=()=>{var e;return(e=o.useContext(O))!=null?e:Y},oe=e=>o.useContext(O)?o.createElement(o.Fragment,null,e.children):o.createElement(ie,{...e}),re=["dark","light"],ie=({forcedTheme:e,disableTransitionOnChange:t=!1,enableSystem:n=!0,enableColorScheme:r=!0,cookie:i,themes:s=re,defaultTheme:a=n?"system":"light",attribute:u="class",value:d,children:C,nonce:g,scriptProps:N})=>{let p=ee(i),[y,k]=o.useState(()=>ae(p,a,u,d,s)),[S,R]=o.useState(()=>y==="system"?E():y),v=d?Object.values(d):s,m=o.useRef(null),h=o.useCallback(c=>{let f=c;if(!f)return;c==="system"&&n&&(f=E());let T=d?d[f]:f,M=t?ce(g):null,x=document.documentElement,L=A=>{A==="class"?(x.classList.remove(...v),T&&x.classList.add(T)):A.startsWith("data-")&&(T?x.setAttribute(A,T):x.removeAttribute(A))};if(Array.isArray(u)?u.forEach(L):L(u),r){let A=V.includes(a)?a:null,_=V.includes(f)?f:A;x.style.colorScheme=_}M==null||M()},[g]),l=o.useCallback(c=>{var f;(f=m.current)==null||f.postMessage({key:p,value:c})},[p]),b=o.useCallback(c=>{typeof c=="function"?k(f=>{let T=c(f);return H(p,T,i),l(T),T}):(k(c),H(p,c,i),l(c))},[p,i,l]),P=o.useCallback(c=>{let f=E(c);R(f),y==="system"&&n&&!e&&h("system")},[y,e]);o.useEffect(()=>{let c=window.matchMedia(I);return c.addListener(P),P(c),()=>c.removeListener(P)},[P]),o.useEffect(()=>{if(typeof window=="undefined"||typeof window.BroadcastChannel=="undefined")return;let c=new BroadcastChannel(`ssr-themes:${p}`);m.current=c;let f=T=>{if(!(!T.data||T.data.key!==p)){if(!T.data.value){k(a);return}k(T.data.value)}};return c.addEventListener("message",f),()=>{c.removeEventListener("message",f),c.close(),m.current===c&&(m.current=null)}},[p,a]),o.useEffect(()=>{h(e!=null?e:y)},[e,y]);let B=o.useMemo(()=>({theme:y,setTheme:b,forcedTheme:e,resolvedTheme:y==="system"?S:y,themes:n?[...s,"system"]:s,systemTheme:n?S:void 0}),[y,b,e,S,n,s]);return o.createElement(O.Provider,{value:B},o.createElement(j,{forcedTheme:e,cookieName:p,attribute:u,enableSystem:n,enableColorScheme:r,defaultTheme:a,value:d,themes:s,nonce:g,scriptProps:N}),C)},j=o.memo(({forcedTheme:e,cookieName:t,attribute:n,enableSystem:r,enableColorScheme:i,defaultTheme:s,value:a,themes:u,nonce:d,scriptProps:C})=>{let g=JSON.stringify([n,t,s,e,u,a,r,i]).slice(1,-1);return o.createElement("script",{...C,suppressHydrationWarning:!0,nonce:typeof window=="undefined"?d:"",dangerouslySetInnerHTML:{__html:`(${$.toString()})(${g})`}})});function me(e,t,n){let r=Array.isArray(e)?e:[e],i=[];for(let s of n){let a=t?t[s]:s;a&&i.push({theme:s,value:a})}for(let s of r){if(s==="class"){for(let u of i)if(document.documentElement.classList.contains(u.value))return u.theme;continue}let a=document.documentElement.getAttribute(s);if(a){for(let u of i)if(u.value===a)return u.theme}}}function ae(e,t,n,r,i){if(Q)return;let s=me(n,r,i);if(s)return s;let a;try{a=te(e)}catch(u){}return a||t}var ce=e=>{let t=document.createElement("style");return e&&t.setAttribute("nonce",e),t.appendChild(document.createTextNode("*,*::before,*::after{-webkit-transition:none!important;-moz-transition:none!important;-o-transition:none!important;-ms-transition:none!important;transition:none!important}")),document.head.appendChild(t),()=>{window.getComputedStyle(document.body),setTimeout(()=>{document.head.removeChild(t)},1)}},E=e=>(e||(e=window.matchMedia(I)),e.matches?"dark":"light");0&&(module.exports={ThemeProvider,ThemeScript,registerTheme,useTheme});

package/dist/index.mjs

@@ -0,0 +1 @@
+"use client";import*as s from"react";var L=(e,n,i,o,a,t,m,u)=>{let d=document.documentElement,C=Array.isArray(e)?e:[e],g=[];for(let r of a){let h=t?t[r]:r;h&&g.push({theme:r,value:h})}let w=g.map(r=>r.value),p=r=>{let h=document.cookie.match(new RegExp(`(?:^|; )${r}=([^;]*)`));return h?decodeURIComponent(h[1]):void 0},y=()=>{for(let r of C){if(r==="class"){for(let l of g)if(d.classList.contains(l.value))return l.theme;continue}let h=d.getAttribute(r);if(h){for(let l of g)if(l.value===h)return l.theme}}};function k(r){let h=t?t[r]:r;for(let l of C)l==="class"?(d.classList.remove(...w),h&&d.classList.add(h)):h?d.setAttribute(l,h):d.removeAttribute(l);u&&(r==="light"||r==="dark")&&(d.style.colorScheme=r)}let S=()=>window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";if(o){k(o);return}let R=r=>m&&r==="system"?S():r,v=y();if(v){k(R(v));return}try{let r=p(n)||i;k(R(r))}catch(r){}};var Q=({theme:e,attribute:n="class",value:i,enableColorScheme:o=!0}={})=>{if(!e||e==="system")return{};let a=i?i[e]:e;if(!a)return{};let t={},m=Array.isArray(n)?n:[n];for(let u of m)u==="class"?t.className=a:t[u]=a;return o&&(e==="light"||e==="dark")&&(t.style={colorScheme:e}),t};var D=["light","dark"],U="(prefers-color-scheme: dark)",V=typeof window=="undefined",E=s.createContext(void 0),j={setTheme:e=>{},themes:[]},B={path:"/",maxAge:31536e3,sameSite:"lax"},_=e=>{var n;return(n=e==null?void 0:e.name)!=null?n:"theme"},F=e=>{if(V)return;let n=document.cookie?document.cookie.split("; "):[];for(let i of n){let[o,...a]=i.split("=");if(o===e)return decodeURIComponent(a.join("="))}},W=e=>{if(e)return`${e.charAt(0).toUpperCase()}${e.slice(1)}`},$=(e,n,i)=>{try{let o={...B,...i!=null?i:{}},a=encodeURIComponent(n),t=[`${e}=${a}`];o.path&&t.push(`Path=${o.path}`),o.domain&&t.push(`Domain=${o.domain}`),typeof o.maxAge=="number"&&t.push(`Max-Age=${o.maxAge}`),o.expires&&t.push(`Expires=${o.expires.toUTCString()}`);let m=W(o.sameSite);m&&t.push(`SameSite=${m}`),o.secure&&t.push("Secure"),document.cookie=t.join("; ")}catch(o){}},te=()=>{var e;return(e=s.useContext(E))!=null?e:j},se=e=>s.useContext(E)?s.createElement(s.Fragment,null,e.children):s.createElement(J,{...e}),z=["dark","light"],J=({forcedTheme:e,disableTransitionOnChange:n=!1,enableSystem:i=!0,enableColorScheme:o=!0,cookie:a,themes:t=z,defaultTheme:m=i?"system":"light",attribute:u="class",value:d,children:C,nonce:g,scriptProps:w})=>{let p=_(a),[y,k]=s.useState(()=>K(p,m,u,d,t)),[S,R]=s.useState(()=>y==="system"?M():y),v=d?Object.values(d):t,r=s.useRef(null),h=s.useCallback(c=>{let f=c;if(!f)return;c==="system"&&i&&(f=M());let T=d?d[f]:f,N=n?X(g):null,x=document.documentElement,b=A=>{A==="class"?(x.classList.remove(...v),T&&x.classList.add(T)):A.startsWith("data-")&&(T?x.setAttribute(A,T):x.removeAttribute(A))};if(Array.isArray(u)?u.forEach(b):b(u),o){let A=D.includes(m)?m:null,I=D.includes(f)?f:A;x.style.colorScheme=I}N==null||N()},[g]),l=s.useCallback(c=>{var f;(f=r.current)==null||f.postMessage({key:p,value:c})},[p]),O=s.useCallback(c=>{typeof c=="function"?k(f=>{let T=c(f);return $(p,T,a),l(T),T}):(k(c),$(p,c,a),l(c))},[p,a,l]),P=s.useCallback(c=>{let f=M(c);R(f),y==="system"&&i&&!e&&h("system")},[y,e]);s.useEffect(()=>{let c=window.matchMedia(U);return c.addListener(P),P(c),()=>c.removeListener(P)},[P]),s.useEffect(()=>{if(typeof window=="undefined"||typeof window.BroadcastChannel=="undefined")return;let c=new BroadcastChannel(`ssr-themes:${p}`);r.current=c;let f=T=>{if(!(!T.data||T.data.key!==p)){if(!T.data.value){k(m);return}k(T.data.value)}};return c.addEventListener("message",f),()=>{c.removeEventListener("message",f),c.close(),r.current===c&&(r.current=null)}},[p,m]),s.useEffect(()=>{h(e!=null?e:y)},[e,y]);let H=s.useMemo(()=>({theme:y,setTheme:O,forcedTheme:e,resolvedTheme:y==="system"?S:y,themes:i?[...t,"system"]:t,systemTheme:i?S:void 0}),[y,O,e,S,i,t]);return s.createElement(E.Provider,{value:H},s.createElement(q,{forcedTheme:e,cookieName:p,attribute:u,enableSystem:i,enableColorScheme:o,defaultTheme:m,value:d,themes:t,nonce:g,scriptProps:w}),C)},q=s.memo(({forcedTheme:e,cookieName:n,attribute:i,enableSystem:o,enableColorScheme:a,defaultTheme:t,value:m,themes:u,nonce:d,scriptProps:C})=>{let g=JSON.stringify([i,n,t,e,u,m,o,a]).slice(1,-1);return s.createElement("script",{...C,suppressHydrationWarning:!0,nonce:typeof window=="undefined"?d:"",dangerouslySetInnerHTML:{__html:`(${L.toString()})(${g})`}})});function G(e,n,i){let o=Array.isArray(e)?e:[e],a=[];for(let t of i){let m=n?n[t]:t;m&&a.push({theme:t,value:m})}for(let t of o){if(t==="class"){for(let u of a)if(document.documentElement.classList.contains(u.value))return u.theme;continue}let m=document.documentElement.getAttribute(t);if(m){for(let u of a)if(u.value===m)return u.theme}}}function K(e,n,i,o,a){if(V)return;let t=G(i,o,a);if(t)return t;let m;try{m=F(e)}catch(u){}return m||n}var X=e=>{let n=document.createElement("style");return e&&n.setAttribute("nonce",e),n.appendChild(document.createTextNode("*,*::before,*::after{-webkit-transition:none!important;-moz-transition:none!important;-o-transition:none!important;-ms-transition:none!important;transition:none!important}")),document.head.appendChild(n),()=>{window.getComputedStyle(document.body),setTimeout(()=>{document.head.removeChild(n)},1)}},M=e=>(e||(e=window.matchMedia(U)),e.matches?"dark":"light");export{se as ThemeProvider,q as ThemeScript,Q as registerTheme,te as useTheme};

package/dist/server-CcYvjBJ6.d.mts

@@ -0,0 +1,87 @@
+import * as React from 'react';
+
+interface ValueObject {
+    [themeName: string]: string;
+}
+interface CookieOptions {
+    /** Cookie path attribute */
+    path?: string;
+    /** Cookie max-age attribute in seconds */
+    maxAge?: number;
+    /** Cookie expires attribute */
+    expires?: Date;
+    /** Cookie SameSite attribute */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /** Cookie domain attribute */
+    domain?: string;
+    /** Cookie secure attribute */
+    secure?: boolean;
+}
+interface CookieConfig extends CookieOptions {
+    /** Cookie name used to store theme preference */
+    name?: string;
+}
+type SystemThemeDefinition = readonly ['dark', 'light'];
+type SystemTheme = SystemThemeDefinition[number];
+type DataAttribute = `data-${string}`;
+interface ScriptProps extends React.DetailedHTMLProps<React.ScriptHTMLAttributes<HTMLScriptElement>, HTMLScriptElement> {
+    [dataAttribute: DataAttribute]: any;
+}
+interface UseThemeProps<TThemes extends readonly string[] = SystemThemeDefinition> {
+    /** List of all available theme names */
+    themes: TThemes;
+    /** Forced theme name for the current page */
+    forcedTheme?: ThemeName<TThemes> | undefined;
+    /** Update the theme */
+    setTheme: React.Dispatch<React.SetStateAction<string>>;
+    /** Active theme name */
+    theme?: ThemeName<TThemes> | undefined;
+    /** If `enableSystem` is true and the active theme is "system", this returns whether the system preference resolved to "dark" or "light". Otherwise, identical to `theme` */
+    resolvedTheme?: ThemeName<TThemes> | undefined;
+    /** If enableSystem is true, returns the System theme preference ("dark" or "light"), regardless what the active theme is */
+    systemTheme?: SystemTheme | undefined;
+}
+type Attribute = DataAttribute | 'class';
+type ThemeName<T extends readonly string[]> = T[number];
+type ThemeHtmlProps = {
+    className?: string;
+    style?: React.CSSProperties;
+} & Partial<Record<DataAttribute, string>>;
+interface RegisterThemeOptions<TThemes extends readonly string[] = SystemThemeDefinition> {
+    /** Resolved theme name to apply to the html element */
+    theme?: ThemeName<TThemes> | undefined;
+    /** HTML attribute modified based on the active theme */
+    attribute?: Attribute | Attribute[] | undefined;
+    /** Mapping of theme name to HTML attribute value */
+    value?: ValueObject | undefined;
+    /** Whether to indicate to browsers which color scheme is used */
+    enableColorScheme?: boolean | undefined;
+}
+interface ThemeProviderProps<TThemes extends readonly string[] = SystemThemeDefinition> extends React.PropsWithChildren<unknown> {
+    /** List of all available theme names */
+    themes?: TThemes | undefined;
+    /** Forced theme name for the current page */
+    forcedTheme?: ThemeName<TThemes> | undefined;
+    /** Whether to switch between dark and light themes based on prefers-color-scheme */
+    enableSystem?: boolean | undefined;
+    /** Disable all CSS transitions when switching themes */
+    disableTransitionOnChange?: boolean | undefined;
+    /** Whether to indicate to browsers which color scheme is used (dark or light) for built-in UI like inputs and buttons */
+    enableColorScheme?: boolean | undefined;
+    /** Cookie configuration used to store theme preference */
+    cookie?: CookieConfig | undefined;
+    /** Default theme name (for v0.0.12 and lower the default was light). If `enableSystem` is false, the default theme is light */
+    defaultTheme?: ThemeName<TThemes> | undefined;
+    /** HTML attribute modified based on the active theme. Accepts `class`, `data-*` (meaning any data attribute, `data-mode`, `data-color`, etc.), or an array which could include both */
+    attribute?: Attribute | Attribute[] | undefined;
+    /** Mapping of theme name to HTML attribute value. Object where key is the theme name and value is the attribute value */
+    value?: ValueObject | undefined;
+    /** Nonce string to pass to the inline script and style elements for CSP headers */
+    nonce?: string;
+    /** Props to pass the inline script */
+    scriptProps?: ScriptProps;
+}
+
+declare const registerTheme: <TThemes extends readonly string[] = SystemThemeDefinition>({ theme, attribute, value, enableColorScheme, }?: RegisterThemeOptions<TThemes>) => ThemeHtmlProps;
+
+export { type Attribute as A, type CookieConfig as C, type RegisterThemeOptions as R, type SystemThemeDefinition as S, type ThemeProviderProps as T, type UseThemeProps as U, type CookieOptions as a, type SystemTheme as b, type ThemeHtmlProps as c, registerTheme as r };

package/dist/server-CcYvjBJ6.d.ts

@@ -0,0 +1,87 @@
+import * as React from 'react';
+
+interface ValueObject {
+    [themeName: string]: string;
+}
+interface CookieOptions {
+    /** Cookie path attribute */
+    path?: string;
+    /** Cookie max-age attribute in seconds */
+    maxAge?: number;
+    /** Cookie expires attribute */
+    expires?: Date;
+    /** Cookie SameSite attribute */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /** Cookie domain attribute */
+    domain?: string;
+    /** Cookie secure attribute */
+    secure?: boolean;
+}
+interface CookieConfig extends CookieOptions {
+    /** Cookie name used to store theme preference */
+    name?: string;
+}
+type SystemThemeDefinition = readonly ['dark', 'light'];
+type SystemTheme = SystemThemeDefinition[number];
+type DataAttribute = `data-${string}`;
+interface ScriptProps extends React.DetailedHTMLProps<React.ScriptHTMLAttributes<HTMLScriptElement>, HTMLScriptElement> {
+    [dataAttribute: DataAttribute]: any;
+}
+interface UseThemeProps<TThemes extends readonly string[] = SystemThemeDefinition> {
+    /** List of all available theme names */
+    themes: TThemes;
+    /** Forced theme name for the current page */
+    forcedTheme?: ThemeName<TThemes> | undefined;
+    /** Update the theme */
+    setTheme: React.Dispatch<React.SetStateAction<string>>;
+    /** Active theme name */
+    theme?: ThemeName<TThemes> | undefined;
+    /** If `enableSystem` is true and the active theme is "system", this returns whether the system preference resolved to "dark" or "light". Otherwise, identical to `theme` */
+    resolvedTheme?: ThemeName<TThemes> | undefined;
+    /** If enableSystem is true, returns the System theme preference ("dark" or "light"), regardless what the active theme is */
+    systemTheme?: SystemTheme | undefined;
+}
+type Attribute = DataAttribute | 'class';
+type ThemeName<T extends readonly string[]> = T[number];
+type ThemeHtmlProps = {
+    className?: string;
+    style?: React.CSSProperties;
+} & Partial<Record<DataAttribute, string>>;
+interface RegisterThemeOptions<TThemes extends readonly string[] = SystemThemeDefinition> {
+    /** Resolved theme name to apply to the html element */
+    theme?: ThemeName<TThemes> | undefined;
+    /** HTML attribute modified based on the active theme */
+    attribute?: Attribute | Attribute[] | undefined;
+    /** Mapping of theme name to HTML attribute value */
+    value?: ValueObject | undefined;
+    /** Whether to indicate to browsers which color scheme is used */
+    enableColorScheme?: boolean | undefined;
+}
+interface ThemeProviderProps<TThemes extends readonly string[] = SystemThemeDefinition> extends React.PropsWithChildren<unknown> {
+    /** List of all available theme names */
+    themes?: TThemes | undefined;
+    /** Forced theme name for the current page */
+    forcedTheme?: ThemeName<TThemes> | undefined;
+    /** Whether to switch between dark and light themes based on prefers-color-scheme */
+    enableSystem?: boolean | undefined;
+    /** Disable all CSS transitions when switching themes */
+    disableTransitionOnChange?: boolean | undefined;
+    /** Whether to indicate to browsers which color scheme is used (dark or light) for built-in UI like inputs and buttons */
+    enableColorScheme?: boolean | undefined;
+    /** Cookie configuration used to store theme preference */
+    cookie?: CookieConfig | undefined;
+    /** Default theme name (for v0.0.12 and lower the default was light). If `enableSystem` is false, the default theme is light */
+    defaultTheme?: ThemeName<TThemes> | undefined;
+    /** HTML attribute modified based on the active theme. Accepts `class`, `data-*` (meaning any data attribute, `data-mode`, `data-color`, etc.), or an array which could include both */
+    attribute?: Attribute | Attribute[] | undefined;
+    /** Mapping of theme name to HTML attribute value. Object where key is the theme name and value is the attribute value */
+    value?: ValueObject | undefined;
+    /** Nonce string to pass to the inline script and style elements for CSP headers */
+    nonce?: string;
+    /** Props to pass the inline script */
+    scriptProps?: ScriptProps;
+}
+
+declare const registerTheme: <TThemes extends readonly string[] = SystemThemeDefinition>({ theme, attribute, value, enableColorScheme, }?: RegisterThemeOptions<TThemes>) => ThemeHtmlProps;
+
+export { type Attribute as A, type CookieConfig as C, type RegisterThemeOptions as R, type SystemThemeDefinition as S, type ThemeProviderProps as T, type UseThemeProps as U, type CookieOptions as a, type SystemTheme as b, type ThemeHtmlProps as c, registerTheme as r };

package/dist/server.d.mts

@@ -0,0 +1,2 @@
+export { A as Attribute, C as CookieConfig, a as CookieOptions, R as RegisterThemeOptions, b as SystemTheme, c as ThemeHtmlProps, T as ThemeProviderProps, U as UseThemeProps, r as registerTheme } from './server-CcYvjBJ6.mjs';
+import 'react';

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export { A as Attribute, C as CookieConfig, a as CookieOptions, R as RegisterThemeOptions, b as SystemTheme, c as ThemeHtmlProps, T as ThemeProviderProps, U as UseThemeProps, r as registerTheme } from './server-CcYvjBJ6.js';
+import 'react';

package/dist/server.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var y=Object.prototype.hasOwnProperty;var l=(e,s)=>{for(var o in s)m(e,o,{get:s[o],enumerable:!0})},c=(e,s,o,t)=>{if(s&&typeof s=="object"||typeof s=="function")for(let r of h(s))!y.call(e,r)&&r!==o&&m(e,r,{get:()=>s[r],enumerable:!(t=f(s,r))||t.enumerable});return e};var a=e=>c(m({},"__esModule",{value:!0}),e);var g={};l(g,{registerTheme:()=>p});module.exports=a(g);var p=({theme:e,attribute:s="class",value:o,enableColorScheme:t=!0}={})=>{if(!e||e==="system")return{};let r=o?o[e]:e;if(!r)return{};let i={},T=Array.isArray(s)?s:[s];for(let n of T)n==="class"?i.className=r:i[n]=r;return t&&(e==="light"||e==="dark")&&(i.style={colorScheme:e}),i};0&&(module.exports={registerTheme});

package/dist/server.mjs

@@ -0,0 +1 @@
+var p=({theme:e,attribute:r="class",value:t,enableColorScheme:m=!0}={})=>{if(!e||e==="system")return{};let o=t?t[e]:e;if(!o)return{};let s={},n=Array.isArray(r)?r:[r];for(let i of n)i==="class"?s.className=o:s[i]=o;return m&&(e==="light"||e==="dark")&&(s.style={colorScheme:e}),s};export{p as registerTheme};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "ssr-themes",
+  "version": "0.0.1-alpha.1",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE.md",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-server": "./dist/server.mjs",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    }
+  },
+  "scripts": {
+    "prepublish": "bun run build",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run __tests__",
+    "clean": "rm -rf dist node_modules"
+  },
+  "peerDependencies": {
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  },
+  "devDependencies": {
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xcadams/ssr-themes.git"
+  }
+}