@puzzle-ui/theme 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @puzzle-ui/theme
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Puzzle's theme system: semantic design tokens, light/dark color schemes,
+typography, Google Fonts, and configurable link and image components.
+
+> Puzzle is under active development. APIs and framework compatibility may
+> change; use it for experimentation and evaluation rather than production.
+
+## Installation
+
+```sh
+npm install @puzzle-ui/theme
+# or
+bun add @puzzle-ui/theme
+# or
+pnpm add @puzzle-ui/theme
+# or
+yarn add @puzzle-ui/theme
+```
+
+Requires React and React DOM 19 (`^19.0.0`) and a CSS-aware application
+bundler. Styles are imported by the package; no separate stylesheet or
+Tailwind setup is required.
+
+## Usage
+
+```tsx
+import { Theme } from "@puzzle-ui/theme";
+
+export const App = () => (
+  <Theme
+    theme="system"
+    tokens={{ radius: { md: "0.5rem" } }}
+  >
+    <main>Your application</main>
+  </Theme>
+);
+```
+
+Use one root theme for your application. By default it follows the system
+color scheme, emits `--puzzle-*` CSS custom properties, and applies global
+styles. Set `globalStyles={false}` to opt out of the global defaults.
+
+## Configuration
+
+| Prop | Purpose |
+| --- | --- |
+| `theme` | `"light"`, `"dark"`, or `"system"`; defaults to `"system"`. |
+| `scope` | `"root"` for document-wide styling or `"local"` for a subtree. |
+| `tokens` | Deep-partial overrides of color, typography, spacing, radius, layout, motion, and other design tokens. |
+| `colorTheme` | Select a built-in palette, such as `"cobalt-sky"`. |
+| `fonts` | Configure Google Fonts for heading, body, and accent roles. |
+| `components` | Override link and image rendering. |
+| `nonce` | CSP nonce for injected style elements. |
+
+Local themes do not apply global styles. Fonts configured through `fonts`
+load external Google Fonts stylesheets; omit this prop to avoid those
+requests.
+
+## Use tokens in your styles
+
+```css
+.panel {
+  color: var(--puzzle-color-text);
+  background: var(--puzzle-color-surface);
+  padding: var(--puzzle-space-4);
+  border-radius: var(--puzzle-radius-md);
+}
+```
+
+## Router integration
+
+For routers whose links use `to`, configure the destination prop:
+
+```tsx
+import { Link } from "@tanstack/react-router";
+
+<Theme components={{ link: { component: Link, hrefProp: "to" } }}>
+  <AppContent />
+</Theme>;
+```
+
+Components using `href` can be passed directly. Use `link: null` or
+`image: null` to restore native elements in a subtree.
+
+## Exports
+
+The root exports `Theme`, `GoogleFont`, `createGoogleFontUrl`, `BREAKPOINTS`,
+and their configuration types. Context helpers are available through
+`@puzzle-ui/theme/components-context` and `@puzzle-ui/theme/scope-context`.
+
+ESM and CommonJS builds with matching TypeScript declarations are included.
+CSS imports require a bundler rather than a bare Node.js runtime.
+
+See the repository's [theme documentation](../../apps/site/content/docs/theme)
+for token references, fonts, colors, and component overrides.
+
+## Development
+
+```sh
+# From the repository root
+npm run build --workspace=@puzzle-ui/theme
+
+# From this package directory
+bun run vitest
+```
+
+`prepack` rebuilds the package before packing or publishing. See the root
+[publishing guide](../../README.md#publishing-packages).
+
+## License
+
+MIT. See [LICENSE](../../LICENSE); the published license is at `dist/LICENSE`.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sjoerd van Den Berg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/breakpoints.cjs

@@ -0,0 +1,10 @@
+// src/breakpoints.ts
+const BREAKPOINTS = {
+	compact: 480,
+	tablet: 768,
+	desktop: 1024,
+	hd: 1440
+};
+exports.BREAKPOINTS = BREAKPOINTS;
+
+//# sourceMappingURL=breakpoints.cjs.map

package/dist/breakpoints.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoints.cjs","names":[],"sources":["../src/breakpoints.ts"],"sourcesContent":["export const BREAKPOINTS = {\n  compact: 480,\n  tablet: 768,\n  desktop: 1024,\n  hd: 1440,\n} as const;\n\nexport type Breakpoint = keyof typeof BREAKPOINTS;\n"],"mappings":";AAAA,MAAa,cAAc;CACzB,SAAS;CACT,QAAQ;CACR,SAAS;CACT,IAAI;AACN"}

package/dist/breakpoints.d.cts

@@ -0,0 +1,7 @@
+export declare const BREAKPOINTS: {
+  readonly compact: 480;
+  readonly tablet: 768;
+  readonly desktop: 1024;
+  readonly hd: 1440;
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;

package/dist/breakpoints.d.ts

@@ -0,0 +1,7 @@
+export declare const BREAKPOINTS: {
+  readonly compact: 480;
+  readonly tablet: 768;
+  readonly desktop: 1024;
+  readonly hd: 1440;
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;

package/dist/breakpoints.js

@@ -0,0 +1,10 @@
+// src/breakpoints.ts
+const BREAKPOINTS = {
+	compact: 480,
+	tablet: 768,
+	desktop: 1024,
+	hd: 1440
+};
+export { BREAKPOINTS };
+
+//# sourceMappingURL=breakpoints.js.map

package/dist/breakpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoints.js","names":[],"sources":["../src/breakpoints.ts"],"sourcesContent":["export const BREAKPOINTS = {\n  compact: 480,\n  tablet: 768,\n  desktop: 1024,\n  hd: 1440,\n} as const;\n\nexport type Breakpoint = keyof typeof BREAKPOINTS;\n"],"mappings":";AAAA,MAAa,cAAc;CACzB,SAAS;CACT,QAAQ;CACR,SAAS;CACT,IAAI;AACN"}

package/dist/components-context.cjs

@@ -0,0 +1,19 @@
+"use client";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let react_jsx_runtime = require("react/jsx-runtime");
+let react = require("react");
+// src/components-context.tsx
+const ThemeComponentsContext = (0, react.createContext)(void 0);
+const ThemeComponentsProvider = ({ components, children }) => {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ThemeComponentsContext.Provider, {
+		value: components,
+		children
+	});
+};
+const useThemeComponents = () => {
+	return (0, react.useContext)(ThemeComponentsContext);
+};
+exports.ThemeComponentsProvider = ThemeComponentsProvider;
+exports.useThemeComponents = useThemeComponents;
+
+//# sourceMappingURL=components-context.cjs.map

package/dist/components-context.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"components-context.cjs","names":["createContext","useContext"],"sources":["../src/components-context.tsx"],"sourcesContent":["\"use client\";\n\nimport { createContext, useContext, type PropsWithChildren } from \"react\";\nimport type { ThemeComponents } from \"./components.types\";\n\nconst ThemeComponentsContext = createContext<ThemeComponents | undefined>(\n  undefined,\n);\n\ntype ThemeComponentsProviderProps = PropsWithChildren<{\n  components: ThemeComponents;\n}>;\n\nconst ThemeComponentsProvider = ({\n  components,\n  children,\n}: ThemeComponentsProviderProps) => {\n  return (\n    <ThemeComponentsContext.Provider value={components}>\n      {children}\n    </ThemeComponentsContext.Provider>\n  );\n};\n\nconst useThemeComponents = () => {\n  return useContext(ThemeComponentsContext);\n};\n\nexport { ThemeComponentsProvider, useThemeComponents };\n"],"mappings":";;;;;AAKA,MAAM,0BAAA,GAAyBA,MAAAA,cAAAA,CAC7B,KAAA,CACF;AAMA,MAAM,2BAA2B,EAC/B,YACA,eACkC;CAClC,OACE,iBAAA,GAAA,kBAAA,IAAA,CAAC,uBAAuB,UAAxB;EAAiC,OAAO;EACrC;CAC8B,CAAA;AAErC;AAEA,MAAM,2BAA2B;CAC/B,QAAA,GAAOC,MAAAA,WAAAA,CAAW,sBAAsB;AAC1C"}

package/dist/components-context.d.cts

@@ -0,0 +1,8 @@
+import { ThemeComponents } from "./components.types.cjs";
+import { PropsWithChildren } from "react";
+type ThemeComponentsProviderProps = PropsWithChildren<{
+  components: ThemeComponents;
+}>;
+declare const ThemeComponentsProvider: ({ components, children }: ThemeComponentsProviderProps) => import("react").JSX.Element;
+declare const useThemeComponents: () => ThemeComponents | undefined;
+export { ThemeComponentsProvider, useThemeComponents };

package/dist/components-context.d.ts

@@ -0,0 +1,8 @@
+import { ThemeComponents } from "./components.types.js";
+import { PropsWithChildren } from "react";
+type ThemeComponentsProviderProps = PropsWithChildren<{
+  components: ThemeComponents;
+}>;
+declare const ThemeComponentsProvider: ({ components, children }: ThemeComponentsProviderProps) => import("react").JSX.Element;
+declare const useThemeComponents: () => ThemeComponents | undefined;
+export { ThemeComponentsProvider, useThemeComponents };

package/dist/components-context.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+// src/components-context.tsx
+const ThemeComponentsContext = createContext(void 0);
+const ThemeComponentsProvider = ({ components, children }) => {
+	return /* @__PURE__ */ jsx(ThemeComponentsContext.Provider, {
+		value: components,
+		children
+	});
+};
+const useThemeComponents = () => {
+	return useContext(ThemeComponentsContext);
+};
+export { ThemeComponentsProvider, useThemeComponents };
+
+//# sourceMappingURL=components-context.js.map

package/dist/components-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"components-context.js","names":[],"sources":["../src/components-context.tsx"],"sourcesContent":["\"use client\";\n\nimport { createContext, useContext, type PropsWithChildren } from \"react\";\nimport type { ThemeComponents } from \"./components.types\";\n\nconst ThemeComponentsContext = createContext<ThemeComponents | undefined>(\n  undefined,\n);\n\ntype ThemeComponentsProviderProps = PropsWithChildren<{\n  components: ThemeComponents;\n}>;\n\nconst ThemeComponentsProvider = ({\n  components,\n  children,\n}: ThemeComponentsProviderProps) => {\n  return (\n    <ThemeComponentsContext.Provider value={components}>\n      {children}\n    </ThemeComponentsContext.Provider>\n  );\n};\n\nconst useThemeComponents = () => {\n  return useContext(ThemeComponentsContext);\n};\n\nexport { ThemeComponentsProvider, useThemeComponents };\n"],"mappings":";;;;AAKA,MAAM,yBAAyB,cAC7B,KAAA,CACF;AAMA,MAAM,2BAA2B,EAC/B,YACA,eACkC;CAClC,OACE,oBAAC,uBAAuB,UAAxB;EAAiC,OAAO;EACrC;CAC8B,CAAA;AAErC;AAEA,MAAM,2BAA2B;CAC/B,OAAO,WAAW,sBAAsB;AAC1C"}

package/dist/components.types.d.cts

@@ -0,0 +1,46 @@
+import { ElementType } from "react";
+/**
+ * Configuration for a custom Link component.
+ *
+ * Use this form when the component uses a different prop name
+ * for its destination, such as TanStack Router's `to`.
+ */
+export type ThemeLinkComponentConfig = {
+  /** The component used to render links. */
+  component: ElementType;
+  /**
+   * The prop used by the component for its destination.
+   *
+   * Defaults to "href".
+   */
+  hrefProp?: "href" | "to";
+};
+/**
+ * Component used to render Puzzle links.
+ *
+ * A component can either follow the standard `href` contract
+ * or use an explicit configuration object.
+ *
+ * When passing components through a React Server Component boundary,
+ * use a component reference exported from a "use client" module.
+ */
+export type ThemeLinkComponent = ElementType | ThemeLinkComponentConfig | null;
+/**
+ * Component used to render Puzzle images.
+ *
+ * Defaults to the native HTML img element.
+ *
+ * This can be overridden with framework-specific image components,
+ * such as Next.js Image or a custom image CDN component.
+ *
+ * When passing components through a React Server Component boundary,
+ * use a component reference exported from a "use client" module.
+ */
+export type ThemeImageComponent = ElementType | null;
+/**
+ * Global component overrides provided by Theme.
+ */
+export type ThemeComponents = {
+  link?: ThemeLinkComponent;
+  image?: ThemeImageComponent;
+};

package/dist/components.types.d.ts

@@ -0,0 +1,46 @@
+import { ElementType } from "react";
+/**
+ * Configuration for a custom Link component.
+ *
+ * Use this form when the component uses a different prop name
+ * for its destination, such as TanStack Router's `to`.
+ */
+export type ThemeLinkComponentConfig = {
+  /** The component used to render links. */
+  component: ElementType;
+  /**
+   * The prop used by the component for its destination.
+   *
+   * Defaults to "href".
+   */
+  hrefProp?: "href" | "to";
+};
+/**
+ * Component used to render Puzzle links.
+ *
+ * A component can either follow the standard `href` contract
+ * or use an explicit configuration object.
+ *
+ * When passing components through a React Server Component boundary,
+ * use a component reference exported from a "use client" module.
+ */
+export type ThemeLinkComponent = ElementType | ThemeLinkComponentConfig | null;
+/**
+ * Component used to render Puzzle images.
+ *
+ * Defaults to the native HTML img element.
+ *
+ * This can be overridden with framework-specific image components,
+ * such as Next.js Image or a custom image CDN component.
+ *
+ * When passing components through a React Server Component boundary,
+ * use a component reference exported from a "use client" module.
+ */
+export type ThemeImageComponent = ElementType | null;
+/**
+ * Global component overrides provided by Theme.
+ */
+export type ThemeComponents = {
+  link?: ThemeLinkComponent;
+  image?: ThemeImageComponent;
+};