@hex-core/tokens 1.3.8 → 1.5.0

package/README.md

@@ -21,6 +21,15 @@ Or, more commonly, copy the CSS block from the [Theming guide](https://hex-core.
 - Radii (`--radius-sm/md/lg`)
 - Shadows (`--shadow-glow`)
 - Container widths
+- React Native output: `generateGlobalsCssNative(theme)` and `themeToNativeTheme(theme)`
+
+## React Native
+
+`generateGlobalsCssNative(theme)` emits the NativeWind stylesheet (`@tailwind` directives plus a `:root` / `.dark:root` pair), and `themeToNativeTheme(theme)` returns the resolved light and dark palettes.
+
+Both resolve palette references to literal `H S% L%` triplets rather than emitting `var()` chains. React Native has no cascade for a `var()` to resolve through, so a stylesheet carrying them yields no colour at all — silently, which is worse than failing. `hex doctor` fails a native project whose `global.css` contains one.
+
+NativeWind 4 is built on Tailwind **3.4.x**, so the emitted config is the v3 shape.
 
 ## CSS variable namespaces
 

package/dist/index.d.ts

@@ -99,8 +99,29 @@ interface GenerateGlobalsCssOptions {
      *   that maps the raw `--<key>` CSS variables to color/radius utilities.
      * - `"v4"`: emits `@import "tailwindcss"` + `@theme { --color-<key>: hsl(...) }` so
      *   utilities like `bg-background` resolve directly. No `tailwind.config.ts` needed.
+     * - `"native"`: the NativeWind shape — `@tailwind` directives plus `:root` /
+     *   `.dark:root` blocks with every palette reference resolved to its literal
+     *   triplet, and no `*` / `body` rules (React Native has neither). Pair with
+     *   `themeToTailwindConfig()` in a Tailwind v3 `tailwind.config.js` using the
+     *   NativeWind preset. See {@link generateGlobalsCssNative}.
      */
-    target?: "v3" | "v4";
+    target?: "v3" | "v4" | "native";
+    /**
+     * Explicit content globs for Tailwind v4 to scan, relative to the CSS file.
+     *
+     * When set, the import becomes `@import "tailwindcss" source(none)` followed
+     * by one `@source` rule per glob — automatic detection is turned off.
+     *
+     * Pass this for an app generated *inside* an existing repository. Tailwind's
+     * automatic scan walks up past the app to the enclosing git root and reads
+     * whatever it finds — including binary files, whose bytes become class
+     * candidates and emit unparseable utilities. Scoping the scan to the app's
+     * own directories is the fix. Omit it for an app at the root of its own
+     * repository, where automatic detection is correct.
+     *
+     * Ignored when `target` is `"v3"`, which has no `@source` rule.
+     */
+    sources?: readonly string[];
 }
 /**
  * Generates a complete globals.css content with theme tokens and Tailwind directives.
@@ -110,6 +131,68 @@ interface GenerateGlobalsCssOptions {
  * @returns A full globals.css string ready to drop into `app/globals.css`.
  */
 declare function generateGlobalsCss(theme: Theme, options?: GenerateGlobalsCssOptions): string;
+/**
+ * A theme flattened for React Native: one resolved-literal map per colour
+ * mode, keyed by CSS custom-property name.
+ *
+ * This is the shape NativeWind's runtime `vars()` helper takes, so a
+ * consumer can switch themes without regenerating `global.css`:
+ *
+ * ```tsx
+ * import { vars } from "nativewind";
+ * const { light, dark } = themeToNativeTheme(theme);
+ * <View style={vars(scheme === "dark" ? dark : light)}>…</View>
+ * ```
+ */
+interface NativeTheme {
+    /** Light-mode tokens, e.g. `{ "--background": "0 0% 100%" }`. */
+    light: Record<string, string>;
+    /** Dark-mode tokens in the same shape. */
+    dark: Record<string, string>;
+}
+/**
+ * Transform a theme into the two flat token maps a React Native app needs.
+ *
+ * Same values as {@link themeToFlatJson} for each mode, returned together
+ * because a native theme provider always holds both and flips between them
+ * on `useColorScheme()`.
+ * @param theme - The theme to flatten
+ * @returns Light and dark maps keyed by `--<token>`
+ */
+declare function themeToNativeTheme(theme: Theme): NativeTheme;
+/**
+ * Generate the `global.css` a NativeWind (v4 line, Tailwind v3) project imports.
+ *
+ * Differences from the web v3 output, each forced by the renderer:
+ *
+ * - Palette references are resolved to literal `H S% L%` triplets and the
+ *   ramp tier is omitted. NativeWind supports CSS variables but the
+ *   `var(--slate-900)` indirection is not worth the runtime cost on a
+ *   platform with no cascade to exploit.
+ * - Dark mode is `.dark:root`, the selector NativeWind's `darkMode: "class"`
+ *   toggles through `colorScheme.set()`.
+ * - No `* { border-color }` or `body { … }` rules: React Native has no
+ *   universal selector and no body. Components read `border-border` and
+ *   `bg-background` themselves.
+ * @param theme - The theme to emit
+ * @returns The full `global.css` contents
+ */
+declare function generateGlobalsCssNative(theme: Theme): string;
+/**
+ * Emit only the token layer — the raw ramp, the semantic tokens, and the
+ * Tailwind `--color-*` bridge.
+ *
+ * Split out of {@link generateGlobalsCss} so a consumer that already owns
+ * its `@import`s, custom variants and non-colour `@theme` block can
+ * generate just the colours. The docs site does exactly that: its
+ * `globals.css` used to hand-copy this output four times over and carried
+ * a "KEEP IN SYNC" comment to prove it.
+ *
+ * @param theme - The theme to emit
+ * @returns The `:root` / `.dark` / `@theme inline` blocks, plus the base
+ *   `body` and border rules
+ */
+declare function generateThemeCssV4(theme: Theme): string;
 
 declare const defaultTheme: Theme;
 
@@ -419,4 +502,4 @@ declare function listThemes(): Array<{
     description: string;
 }>;
 
-export { COLOR_MODE_BANDS, type ColorMode, type DeriveDarkOptions, type DeriveForegroundOptions, type DeriveSecondaryOptions, RADIUS_PRESETS, type RadiusPreset, type ScopedRuntimeCssOptions, type TokenSetSeeds, buildTokenSet, colorInputToTokenValue, contrastRatio, defaultSemanticTokens, defaultTheme, deriveDarkFromLight, deriveForegroundFor, deriveSecondaryFromPrimary, emberTheme, generateGlobalsCss, getTheme, listThemes, midnightTheme, resolveSemanticToken, sharedTokens, themeToCss, themeToFlatJson, themeToScopedRuntimeCss, themeToTailwindConfig, themes, tokenLuminance };
+export { COLOR_MODE_BANDS, type ColorMode, type DeriveDarkOptions, type DeriveForegroundOptions, type DeriveSecondaryOptions, type NativeTheme, RADIUS_PRESETS, type RadiusPreset, type ScopedRuntimeCssOptions, type TokenSetSeeds, buildTokenSet, colorInputToTokenValue, contrastRatio, defaultSemanticTokens, defaultTheme, deriveDarkFromLight, deriveForegroundFor, deriveSecondaryFromPrimary, emberTheme, generateGlobalsCss, generateGlobalsCssNative, generateThemeCssV4, getTheme, listThemes, midnightTheme, resolveSemanticToken, sharedTokens, themeToCss, themeToFlatJson, themeToNativeTheme, themeToScopedRuntimeCss, themeToTailwindConfig, themes, tokenLuminance };