@shiftbloom-studio/circadian-ui 0.2.0 → 0.2.1

package/README.md

@@ -4,13 +4,17 @@
 [![CI](https://github.com/shiftbloom-studio/circadian-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/shiftbloom-studio/circadian-ui/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/@shiftbloom-studio/circadian-ui)](LICENSE)
 
-Automatic, accessible, Tailwind-friendly time-of-day theming for React and Next.js. Circadian UI adapts your design tokens based on local time, optional sunrise/sunset data, system preferences, and user overrides — all while keeping contrast WCAG-conscious.
+**Circadian UI** is a production‑ready, time‑aware theming engine for React and Tailwind. It adapts your design tokens across dawn/day/dusk/night based on local time, optional sunrise/sunset data, system preferences, and user overrides — while enforcing accessible contrast.
 
-## Why this matters
+## What makes it special
 
-- **Readable at any hour**: avoid low-contrast screens at night or overly-bright palettes at dawn.
-- **Reduced eye strain**: thoughtful shifts in luminance and contrast help users stay comfortable.
-- **Consistent branding**: keep your token system intact while letting Circadian UI handle timing and accessibility.
+- **Zero‑config start** — install, wrap your app, and you’re done.
+- **Circadian magic** — automatic phase shifts based on time or sun data.
+- **Accessible by default** — WCAG‑conscious contrast adjustments.
+- **Framework‑friendly** — Next.js (App/Pages), Vite, SSR or CSR.
+- **Tailwind‑native** — tokens exposed as CSS variables + preset/plugin.
+
+---
 
 ## Install
 
@@ -18,7 +22,9 @@ Automatic, accessible, Tailwind-friendly time-of-day theming for React and Next.
 npm install @shiftbloom-studio/circadian-ui
 ```
 
-## Quickstart (React)
+---
+
+## 30‑second quickstart (React)
 
 ```tsx
 import { CircadianProvider, CircadianScript } from "@shiftbloom-studio/circadian-ui";
@@ -33,7 +39,13 @@ export function App({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## Next.js (App Router)
+> `CircadianScript` prevents theme flash by setting the initial phase before hydration.
+
+---
+
+## Next.js
+
+### App Router
 
 ```tsx
 // app/layout.tsx
@@ -52,7 +64,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-## Next.js (Pages Router)
+### Pages Router
 
 ```tsx
 // pages/_document.tsx
@@ -76,9 +88,30 @@ export default class MyDocument extends Document {
 }
 ```
 
-## Tailwind setup
+---
+
+## Vite / CSR apps
+
+```tsx
+import { createRoot } from "react-dom/client";
+import { CircadianProvider, CircadianScript } from "@shiftbloom-studio/circadian-ui";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <>
+    <CircadianScript />
+    <CircadianProvider>
+      <App />
+    </CircadianProvider>
+  </>
+);
+```
+
+---
 
-### CSS variables only (recommended)
+## Tailwind integration
+
+### Option A — CSS variables (recommended)
 
 ```ts
 // tailwind.config.ts
@@ -109,7 +142,7 @@ const config: Config = {
 export default config;
 ```
 
-### Tailwind preset + plugin
+### Option B — Preset + Plugin
 
 ```ts
 // tailwind.config.ts
@@ -125,9 +158,11 @@ const config: Config = {
 export default config;
 ```
 
+---
+
 ## Configuration examples
 
-### Custom time windows
+### 1) Custom schedule windows
 
 ```tsx
 <CircadianProvider
@@ -144,46 +179,60 @@ export default config;
 </CircadianProvider>
 ```
 
-### Manual override UI
+### 2) Sun‑aware schedule
+
+```ts
+import type { SunTimesProvider } from "@shiftbloom-studio/circadian-ui";
+
+const provider: SunTimesProvider = (date) => {
+  return {
+    sunrise: new Date(date.getFullYear(), date.getMonth(), date.getDate(), 6, 12),
+    sunset: new Date(date.getFullYear(), date.getMonth(), date.getDate(), 19, 48)
+  };
+};
+
+<CircadianProvider config={{ mode: "sun", sunTimesProvider: provider }} />;
+```
+
+### 3) Auto mode (recommended)
+
+```tsx
+<CircadianProvider config={{ mode: "auto", sunTimesProvider: provider }} />
+```
+
+If sun data is available, it uses `sun`; otherwise it falls back to `time`.
+
+### 4) Manual override UI
 
 ```tsx
 import { useCircadian } from "@shiftbloom-studio/circadian-ui";
 
 const ModeToggle = () => {
-  const { mode, setMode, setPhaseOverride } = useCircadian();
+  const { mode, resolvedMode, setMode, setPhaseOverride } = useCircadian();
   return (
     <div>
-      <button onClick={() => setMode("time")}>Auto</button>
+      <button onClick={() => setMode("auto")}>Auto</button>
       <button onClick={() => setPhaseOverride("night")}>Night</button>
-      <span>Current mode: {mode}</span>
+      <p>Requested: {mode}</p>
+      <p>Resolved: {resolvedMode}</p>
     </div>
   );
 };
 ```
 
-### Sun-times provider
-
-```ts
-import type { SunTimesProvider } from "@shiftbloom-studio/circadian-ui";
-
-const provider: SunTimesProvider = (date) => {
-  // Plug in your own sunrise/sunset provider
-  return {
-    sunrise: new Date(date.getFullYear(), date.getMonth(), date.getDate(), 6, 12),
-    sunset: new Date(date.getFullYear(), date.getMonth(), date.getDate(), 19, 48)
-  };
-};
+### 5) Initial phase hint (SSR)
 
-<CircadianProvider config={{ mode: "sun", sunTimesProvider: provider }} />;
+```tsx
+<CircadianScript config={{ initialPhase: "night" }} />
 ```
 
-### Disable persistence
+### 6) Disable persistence
 
 ```tsx
 <CircadianProvider config={{ persist: false }} />
 ```
 
-### Strict contrast mode
+### 7) Strict contrast tuning
 
 ```tsx
 <CircadianProvider
@@ -196,9 +245,7 @@ const provider: SunTimesProvider = (date) => {
 />
 ```
 
-## Accessibility notes
-
-Circadian UI enforces WCAG-conscious contrast by default. Foreground tokens are nudged in lightness until they meet the configured ratio. You can tune ratios for normal and large text via `accessibility.minimumRatio` and `accessibility.largeTextRatio`.
+---
 
 ## Design tokens
 
@@ -217,15 +264,17 @@ Circadian UI enforces WCAG-conscious contrast by default. Foreground tokens are
 | Destructive            | `--cui-destructive`    |
 | Destructive Foreground | `--cui-destructive-fg` |
 
+---
+
 ## API reference
 
 ### React
 
 - `CircadianProvider`
   - Props: `{ config?: CircadianConfig; children: React.ReactNode }`
-  - Sets `data-cui-phase` and CSS vars on the document root.
+  - Applies phase + tokens to the document root (or body).
 - `useCircadian()`
-  - Returns `{ phase, mode, setMode, setPhaseOverride, clearOverride, tokens, isAuto, nextChangeAt }`.
+  - Returns `{ phase, mode, resolvedMode, setMode, setPhaseOverride, clearOverride, tokens, isAuto, nextChangeAt }`.
 - `useCircadianTokens()`
   - Returns `{ tokens, cssVars, applyToStyle }` for inline usage.
 - `CircadianScript`
@@ -245,15 +294,18 @@ Circadian UI enforces WCAG-conscious contrast by default. Foreground tokens are
 - `circadianTailwindPreset()`
 - `circadianPlugin()` (wrap with `tailwindcss/plugin`)
 
+---
+
 ## Configuration schema
 
 ```ts
 interface CircadianConfig {
   schedule?: Partial<CircadianSchedule>;
   tokens?: Partial<Record<Phase, Partial<CircadianTokens>>>;
-  mode?: "time" | "sun" | "manual";
+  mode?: "time" | "sun" | "manual" | "auto";
   sunTimesProvider?: SunTimesProvider;
   sunSchedule?: Partial<SunScheduleOptions>;
+  initialPhase?: Phase;
   persist?: boolean;
   storageKey?: string;
   accessibility?: Partial<AccessibilityOptions>;
@@ -264,6 +316,14 @@ interface CircadianConfig {
 }
 ```
 
+---
+
+## Accessibility notes
+
+Circadian UI nudges foreground tokens until they meet your configured contrast ratio. You can tune ratios for normal and large text via `accessibility.minimumRatio` and `accessibility.largeTextRatio`.
+
+---
+
 ## Development
 
 ```bash

package/dist/index.cjs

@@ -56,21 +56,24 @@ var isWithinRange = (minutes, start, end) => {
   }
   return minutes >= start || minutes < end;
 };
-var getPhaseFromTime = (date, schedule) => {
-  const minutes = getMinutesFromDate(date);
-  const normalized = normalizeSchedule(schedule);
+var getPhaseFromMinutes = (minutes, schedule) => {
   const phases = ["dawn", "day", "dusk", "night"];
   for (const phase of phases) {
-    const window2 = normalized[phase];
+    const window2 = schedule[phase];
     if (isWithinRange(minutes, window2.start, window2.end)) {
       return phase;
     }
   }
   return "night";
 };
+var getPhaseFromTime = (date, schedule) => {
+  const minutes = getMinutesFromDate(date);
+  const normalized = normalizeSchedule(schedule);
+  return getPhaseFromMinutes(minutes, normalized);
+};
 var computeNextTransition = (date, schedule) => {
   const normalized = normalizeSchedule(schedule);
-  const currentPhase = getPhaseFromTime(date, schedule);
+  const currentPhase = getPhaseFromMinutes(getMinutesFromDate(date), normalized);
   const minutes = getMinutesFromDate(date);
   const endMinutes = normalized[currentPhase].end;
   let delta = endMinutes - minutes;
@@ -79,6 +82,16 @@ var computeNextTransition = (date, schedule) => {
   }
   return new Date(date.getTime() + delta * 60 * 1e3);
 };
+var computeNextTransitionFromMinutes = (date, schedule) => {
+  const currentPhase = getPhaseFromMinutes(getMinutesFromDate(date), schedule);
+  const minutes = getMinutesFromDate(date);
+  const endMinutes = schedule[currentPhase].end;
+  let delta = endMinutes - minutes;
+  if (delta <= 0) {
+    delta += minutesInDay;
+  }
+  return new Date(date.getTime() + delta * 60 * 1e3);
+};
 
 // src/core/sun.ts
 var minutesInDay2 = 24 * 60;
@@ -124,6 +137,10 @@ var getPhaseFromSunTimes = (date, sunTimes, options) => {
   }
   return "night";
 };
+var computeNextSunTransition = (date, sunTimes, options) => {
+  const schedule = deriveSunSchedule(date, sunTimes, options);
+  return computeNextTransitionFromMinutes(date, schedule);
+};
 var getScheduleFromProvider = (date, provider, options) => {
   if (!provider) {
     return null;
@@ -471,7 +488,7 @@ var defaultTransition = {
   durationMs: 200
 };
 var resolveMode = (userMode, system, config) => {
-  return userMode ?? config?.mode ?? "time";
+  return userMode ?? config?.mode ?? "auto";
 };
 var resolveAccessibility = (system, config) => {
   const base = { ...defaultAccessibility, ...config?.accessibility };
@@ -496,11 +513,13 @@ var getMergedSchedule = (schedule) => ({
   dusk: { ...defaultSchedule.dusk, ...schedule?.dusk },
   night: { ...defaultSchedule.night, ...schedule?.night }
 });
-var getMode = (mode) => mode ?? "time";
+var getMode = (mode) => mode ?? "auto";
 var createInlineScript = (config) => {
   const schedule = getMergedSchedule(config?.schedule);
   const storageKey = config?.storageKey ?? defaultStorageKey;
   const persist = config?.persist !== false;
+  const initialPhase = config?.initialPhase ?? null;
+  const setAttributeOn = config?.setAttributeOn ?? "html";
   const tokens = {
     dawn: tokensToCssVars({
       ...defaultTokens.dawn,
@@ -526,6 +545,8 @@ var createInlineScript = (config) => {
     const storageKey = ${serialize(storageKey)};
     const persist = ${serialize(persist)};
     const fallbackMode = ${serialize(getMode(config?.mode))};
+    const initialPhase = ${serialize(initialPhase)};
+    const setAttributeOn = ${serialize(setAttributeOn)};
     const now = new Date();
     const minutes = now.getHours() * 60 + now.getMinutes();
 
@@ -548,12 +569,14 @@ var createInlineScript = (config) => {
     };
 
     const order = ["dawn", "day", "dusk", "night"];
-    let phase = "night";
-    for (const key of order) {
-      const window = normalized[key];
-      if (isWithin(minutes, window.start, window.end)) {
-        phase = key;
-        break;
+    let phase = initialPhase || "night";
+    if (!initialPhase) {
+      for (const key of order) {
+        const window = normalized[key];
+        if (isWithin(minutes, window.start, window.end)) {
+          phase = key;
+          break;
+        }
       }
     }
 
@@ -569,7 +592,8 @@ var createInlineScript = (config) => {
       }
     }
 
-    const root = document.documentElement;
+    const root =
+      setAttributeOn === "body" && document.body ? document.body : document.documentElement;
     root.setAttribute("data-cui-phase", phase);
     const vars = tokens[phase] || tokens.night;
     for (const key in vars) {
@@ -618,27 +642,21 @@ var getInitialSystemPreferences = () => {
   }
   return getSystemPreferences();
 };
-var computePhase = (date, mode, config, phaseOverride) => {
+var computePhase = (date, mode, config, phaseOverride, sunTimes) => {
   if (mode === "manual" && phaseOverride) {
     return phaseOverride;
   }
-  if (mode === "sun") {
-    const sunTimes = config.sunTimesProvider?.(date);
-    if (sunTimes) {
-      return getPhaseFromSunTimes(date, sunTimes, config.sunSchedule);
-    }
+  if (mode === "sun" && sunTimes) {
+    return getPhaseFromSunTimes(date, sunTimes, config.sunSchedule);
   }
   return getPhaseFromTime(date, config.schedule);
 };
-var computeNextChange = (date, mode, config) => {
+var computeNextChange = (date, mode, config, sunTimes) => {
   if (mode === "manual") {
     return null;
   }
-  if (mode === "sun") {
-    const schedule = getScheduleFromProvider(date, config.sunTimesProvider, config.sunSchedule);
-    if (schedule) {
-      return computeNextTransition(date, schedule);
-    }
+  if (mode === "sun" && sunTimes) {
+    return computeNextSunTransition(date, sunTimes, config.sunSchedule);
   }
   return computeNextTransition(date, config.schedule);
 };
@@ -648,17 +666,18 @@ var CircadianProvider = ({ config = {}, children }) => {
   const [systemPrefs, setSystemPrefs] = react.useState(getInitialSystemPreferences);
   const initialPersisted = typeof window !== "undefined" && shouldPersist ? loadPersistedState(storageKey) : null;
   const [mode, setModeState] = react.useState(
-    initialPersisted?.mode ?? config.mode ?? "time"
+    initialPersisted?.mode ?? config.mode ?? "auto"
   );
   const [phaseOverride, setPhaseOverrideState] = react.useState(
     initialPersisted?.phase ?? null
   );
   const [phase, setPhase] = react.useState(
-    () => computePhase(/* @__PURE__ */ new Date(), mode, config, phaseOverride)
+    () => config.initialPhase ?? computePhase(/* @__PURE__ */ new Date(), mode, config, phaseOverride, null)
   );
   const [nextChangeAt, setNextChangeAt] = react.useState(
-    () => computeNextChange(/* @__PURE__ */ new Date(), mode, config)
+    () => computeNextChange(/* @__PURE__ */ new Date(), mode, config, null)
   );
+  const [resolvedMode, setResolvedMode] = react.useState(mode);
   const timerRef = react.useRef(null);
   const accessibility = react.useMemo(
     () => resolveAccessibility(systemPrefs, config),
@@ -684,18 +703,42 @@ var CircadianProvider = ({ config = {}, children }) => {
     systemOptions.respectColorScheme,
     colorBias
   ]);
+  const resolveModeWithSun = react.useCallback(
+    (date) => {
+      const desiredMode = resolveMode(mode, systemPrefs, config);
+      if (desiredMode === "auto") {
+        if (config.sunTimesProvider) {
+          const sunTimes = config.sunTimesProvider(date);
+          if (sunTimes) {
+            return { resolvedMode: "sun", sunTimes };
+          }
+        }
+        return { resolvedMode: "time", sunTimes: null };
+      }
+      if (desiredMode === "sun") {
+        const sunTimes = config.sunTimesProvider?.(date) ?? null;
+        if (!sunTimes) {
+          return { resolvedMode: "time", sunTimes: null };
+        }
+        return { resolvedMode: "sun", sunTimes };
+      }
+      return { resolvedMode: desiredMode, sunTimes: null };
+    },
+    [mode, systemPrefs, config]
+  );
   const updatePhase = react.useCallback(() => {
     const now = /* @__PURE__ */ new Date();
-    const resolvedMode = resolveMode(mode, systemPrefs, config);
-    const nextPhase = computePhase(now, resolvedMode, config, phaseOverride);
+    const { resolvedMode: resolvedMode2, sunTimes } = resolveModeWithSun(now);
+    const nextPhase = computePhase(now, resolvedMode2, config, phaseOverride, sunTimes);
+    setResolvedMode(resolvedMode2);
     setPhase(nextPhase);
-    setNextChangeAt(computeNextChange(now, resolvedMode, config));
-  }, [mode, systemPrefs, config, phaseOverride]);
+    setNextChangeAt(computeNextChange(now, resolvedMode2, config, sunTimes));
+  }, [config, phaseOverride, resolveModeWithSun]);
   react.useEffect(() => {
     updatePhase();
   }, [updatePhase]);
   react.useEffect(() => {
-    if (mode === "manual") {
+    if (resolvedMode === "manual") {
       return;
     }
     if (timerRef.current) {
@@ -713,7 +756,7 @@ var CircadianProvider = ({ config = {}, children }) => {
         window.clearTimeout(timerRef.current);
       }
     };
-  }, [mode, nextChangeAt, updatePhase]);
+  }, [resolvedMode, nextChangeAt, updatePhase]);
   react.useEffect(() => {
     const root = getRootElement(config.setAttributeOn);
     if (!root || !root.style) {
@@ -768,8 +811,8 @@ var CircadianProvider = ({ config = {}, children }) => {
   }, []);
   const clearOverride = react.useCallback(() => {
     setPhaseOverrideState(null);
-    setModeState("time");
-  }, []);
+    setModeState(config.mode ?? "auto");
+  }, [config.mode]);
   const contextValue = react.useMemo(
     () => ({
       phase,
@@ -779,9 +822,10 @@ var CircadianProvider = ({ config = {}, children }) => {
       setMode,
       setPhaseOverride,
       clearOverride,
-      isAuto: mode !== "manual"
+      isAuto: mode !== "manual",
+      resolvedMode
     }),
-    [phase, mode, tokens, nextChangeAt, setMode, setPhaseOverride, clearOverride]
+    [phase, mode, tokens, nextChangeAt, setMode, setPhaseOverride, clearOverride, resolvedMode]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(CircadianContext.Provider, { value: contextValue, children });
 };
@@ -854,7 +898,9 @@ exports.applyTokensToElement = applyTokensToElement;
 exports.circadianPlugin = circadianPlugin;
 exports.circadianTailwindPreset = circadianTailwindPreset;
 exports.clearPersistedState = clearPersistedState;
+exports.computeNextSunTransition = computeNextSunTransition;
 exports.computeNextTransition = computeNextTransition;
+exports.computeNextTransitionFromMinutes = computeNextTransitionFromMinutes;
 exports.contrastRatio = contrastRatio;
 exports.createInlineScript = createInlineScript;
 exports.cssVarMap = cssVarMap;
@@ -869,6 +915,7 @@ exports.defaultTransition = defaultTransition;
 exports.deriveSunSchedule = deriveSunSchedule;
 exports.ensureContrast = ensureContrast;
 exports.getMinutesFromDate = getMinutesFromDate;
+exports.getPhaseFromMinutes = getPhaseFromMinutes;
 exports.getPhaseFromSunTimes = getPhaseFromSunTimes;
 exports.getPhaseFromTime = getPhaseFromTime;
 exports.getScheduleFromProvider = getScheduleFromProvider;