rastack 0.0.24 → 0.0.25

package/theme/index.ts

@@ -0,0 +1,9 @@
+/**
+ * `rastack/theme` — the React runtime that applies a design-token set: a
+ * `<ThemeProvider>` that injects the token CSS variables and manages light/dark
+ * (and any custom) modes, plus `useTheme` / `useToken` / `useThemeMode` hooks.
+ *
+ * Tokens are authored with `rastack/tokens` and compiled by `rastack tokens`;
+ * this is where they light up the UI.
+ */
+export * from "./provider";

package/theme/provider.tsx

@@ -0,0 +1,157 @@
+import React, {
+  createContext,
+  ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import {
+  emitCss,
+  formatCssValue,
+  cssVarName,
+  resolveTheme,
+  ThemedTokens,
+} from "../src/tokens";
+
+/**
+ * `rastack/theme` — apply a design-token set to a React app.
+ *
+ * The counterpart to `rastack tokens`: where the CLI emits static CSS, this
+ * provider injects the same CSS custom properties at runtime and manages the
+ * active **mode** (light / dark / …). Because every value is a CSS variable,
+ * flipping mode re-cascades instantly with no re-render of consuming
+ * components — exactly like `RAStackProvider` reconfiguring the API in place.
+ *
+ * ```tsx
+ * import tokens from "../tokens/theme.tokens";        // defineTokens(...)
+ * import { ThemeProvider, useToken, useThemeMode } from "rastack/theme";
+ *
+ * <ThemeProvider tokens={tokens}>
+ *   <App />
+ * </ThemeProvider>
+ *
+ * const accent = useToken("color.accent");            // "var(--color-accent)"
+ * const [mode, setMode] = useThemeMode();             // "light" | "dark" | …
+ * ```
+ */
+
+export interface ThemeContextValue {
+  /** The active mode, or `undefined` for the base (mode-less) theme. */
+  mode: string | undefined;
+  /** Switch mode; unknown modes fall back to the base. */
+  setMode: (mode: string | undefined) => void;
+  /** The modes this theme defines. */
+  modes: string[];
+  /** `token("color.accent")` → `"var(--color-accent)"`. */
+  token: (path: string) => string;
+  /**
+   * The resolved *literal* value of a token in the current mode
+   * (`"#4F6BFF"`), for contexts without CSS variables (React Native, canvas).
+   */
+  value: (path: string) => string | undefined;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export interface ThemeProviderProps {
+  /** A `defineTokens(...)` result, or a bare `{ tokens, modes }` document. */
+  tokens: ThemedTokens;
+  /** Initial mode. Defaults to the token set's `defaultMode`. */
+  mode?: string;
+  /** Prefix every CSS variable (`prefix="rs"` → `--rs-color-accent`). */
+  prefix?: string;
+  /**
+   * The attribute set on `<html>` for the active mode. Default `data-theme`,
+   * matching the emitted CSS's `[data-theme="dark"]` selectors.
+   */
+  modeAttribute?: string;
+  /**
+   * Where to scope the CSS. `document` (default) injects a `<style>` and sets
+   * the mode attribute on `<html>`. Pass an element to scope to a subtree.
+   */
+  target?: HTMLElement | "document";
+  children: ReactNode;
+}
+
+export function ThemeProvider({
+  tokens,
+  mode: initialMode,
+  prefix = "",
+  modeAttribute = "data-theme",
+  target = "document",
+  children,
+}: ThemeProviderProps): JSX.Element {
+  const resolved = useMemo(() => resolveTheme(tokens), [tokens]);
+  const css = useMemo(() => emitCss(tokens, { prefix }), [tokens, prefix]);
+  const [mode, setMode] = useState<string | undefined>(
+    initialMode ?? resolved.defaultMode,
+  );
+
+  // Inject (and keep in sync) the generated CSS as a single <style> element.
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const style = document.createElement("style");
+    style.setAttribute("data-rastack-theme", "");
+    style.textContent = css;
+    document.head.appendChild(style);
+    return () => {
+      style.remove();
+    };
+  }, [css]);
+
+  // Reflect the active mode onto the target element's attribute.
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const el =
+      target === "document" ? document.documentElement : (target as HTMLElement);
+    const prev = el.getAttribute(modeAttribute);
+    if (mode) el.setAttribute(modeAttribute, mode);
+    else el.removeAttribute(modeAttribute);
+    return () => {
+      if (prev != null) el.setAttribute(modeAttribute, prev);
+      else el.removeAttribute(modeAttribute);
+    };
+  }, [mode, modeAttribute, target]);
+
+  const ctx = useMemo<ThemeContextValue>(() => {
+    const active = (mode && resolved.modes[mode]) || resolved.base;
+    const literals = new Map(active.map((t) => [t.path, formatCssValue(t)]));
+    return {
+      mode,
+      setMode,
+      modes: Object.keys(resolved.modes),
+      token: (path) => `var(${cssVarName(path, prefix)})`,
+      value: (path) => literals.get(path),
+    };
+  }, [mode, resolved, prefix]);
+
+  return <ThemeContext.Provider value={ctx}>{children}</ThemeContext.Provider>;
+}
+
+/** The full theme context (mode, setMode, token/value lookups). */
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error("useTheme must be used within a <ThemeProvider>.");
+  return ctx;
+}
+
+/** `[mode, setMode]` — the active mode and a switcher. */
+export function useThemeMode(): [string | undefined, (mode: string | undefined) => void] {
+  const { mode, setMode } = useTheme();
+  return [mode, setMode];
+}
+
+/** A token's CSS-variable reference: `useToken("color.accent")` → `"var(--color-accent)"`. */
+export function useToken(path: string): string {
+  return useTheme().token(path);
+}
+
+/**
+ * A token's resolved *literal* value in the active mode (`"#4F6BFF"`). Use on
+ * platforms without CSS variables (React Native); on the web prefer
+ * {@link useToken} so mode switches don't re-render.
+ */
+export function useTokenValue(path: string): string | undefined {
+  return useTheme().value(path);
+}

package/tokens.ts

@@ -0,0 +1,9 @@
+/**
+ * `rastack/tokens` — the design-system authoring DSL and pure token engine.
+ *
+ * Author your design system in TypeScript with {@link defineTokens} + {@link t},
+ * following the industry-standard W3C Design Tokens (DTCG) format. `rastack
+ * tokens` compiles it to CSS custom properties + a typed theme; `rastack/theme`
+ * applies it at runtime. Filesystem-free, so it also runs in the browser.
+ */
+export * from "./src/tokens";

package/tsconfig.json

@@ -11,6 +11,9 @@
     ],
     "outDir": "dist",
     "rootDir": "src",
+    "paths": {
+      "rastack/tokens": ["./tokens.ts"]
+    },
     "declaration": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,