|
| 1 | +# luna-reactlynx |
| 2 | + |
| 3 | +> ⚠️ This package is under active development. APIs may change without notice. |
| 4 | +
|
| 5 | +LUNA theming utilities for ReactLynx — theme context, provider, color consumption hooks, and an optional runtime shell component. |
| 6 | + |
| 7 | +Two integration styles are supported: |
| 8 | + |
| 9 | +- **JS Tokens** — use `createLunaTheme()` + `LunaThemeProvider` + `useLunaColor(s)` to consume theme values from JS. Hooks can return either raw values or `var(...)` references, but returning `var(...)` does not create CSS variables by itself. |
| 10 | +- **CSS Variables** — use theme classes from `@dugyu/luna-styles` (e.g. `lunaris-light`) with `LunaTheme` (or your own root `className`) to scope real CSS variables. Components consume via `var(--xxx)` or Tailwind semantic utilities. |
| 11 | + |
| 12 | +## Installation |
| 13 | + |
| 14 | +**JS Tokens style:** |
| 15 | + |
| 16 | +```bash |
| 17 | +pnpm add @dugyu/luna-reactlynx @dugyu/luna-tokens |
| 18 | +``` |
| 19 | + |
| 20 | +**CSS Variables style:** |
| 21 | + |
| 22 | +```bash |
| 23 | +pnpm add @dugyu/luna-reactlynx @dugyu/luna-styles |
| 24 | +``` |
| 25 | + |
| 26 | +## Entry points |
| 27 | + |
| 28 | +| Entry | Contents | |
| 29 | +| -------------------------------------------- | ------------------------------------------------------- | |
| 30 | +| `@dugyu/luna-reactlynx` | Provider, hooks, `createLunaTheme`, type re-exports | |
| 31 | +| `@dugyu/luna-reactlynx/theming` | Theming-only subpath | |
| 32 | +| `@dugyu/luna-reactlynx/runtime` | Runtime shell (`LunaTheme`) | |
| 33 | +| `@dugyu/luna-reactlynx/runtime/global-props` | TS type augmentation for `lynx.__globalProps.lunaTheme` | |
| 34 | + |
| 35 | +## Usage: JS Tokens |
| 36 | + |
| 37 | +`createLunaTheme(tokens)` converts a token input into a `LunaRuntimeTheme`. Pass one or more themes to `LunaThemeProvider` and consume colors with hooks. Use this style when you need theme values accessible in JS — for animation, computation, or non-CSS color usage. |
| 38 | + |
| 39 | +If you want to switch theme by toggling a class, use the CSS Variables style section. If you want a theme object in JS (animation, computations, non-CSS color usage), use JS Tokens. |
| 40 | + |
| 41 | +```tsx |
| 42 | +import { |
| 43 | + LunaThemeProvider, |
| 44 | + createLunaTheme, |
| 45 | + useLunaColors, |
| 46 | +} from '@dugyu/luna-reactlynx'; |
| 47 | +import { lunarisDarkTokens, lunarisLightTokens } from '@dugyu/luna-tokens'; |
| 48 | + |
| 49 | +const themes = [ |
| 50 | + createLunaTheme(lunarisLightTokens), |
| 51 | + createLunaTheme(lunarisDarkTokens), |
| 52 | +]; |
| 53 | + |
| 54 | +export function App() { |
| 55 | + return ( |
| 56 | + <LunaThemeProvider |
| 57 | + themes={themes} |
| 58 | + themeKey={lynx.__globalProps.lunaTheme ?? 'lunaris-light'} |
| 59 | + > |
| 60 | + <Demo /> |
| 61 | + </LunaThemeProvider> |
| 62 | + ); |
| 63 | +} |
| 64 | + |
| 65 | +function Demo() { |
| 66 | + const colors = useLunaColors(); |
| 67 | + return <view style={{ backgroundColor: colors.canvas }} />; |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +**Single theme:** pass `theme` instead of `themes`. |
| 72 | + |
| 73 | +```tsx |
| 74 | +<LunaThemeProvider theme={createLunaTheme(lunarisLightTokens)}> |
| 75 | + {children} |
| 76 | +</LunaThemeProvider>; |
| 77 | +``` |
| 78 | + |
| 79 | +### Color consumption format |
| 80 | + |
| 81 | +`theme.colors` always stores canonical raw values (e.g. `#ff1a6e`, `rgba(...)`). The `consumptionFormat` on the runtime theme controls what hooks return by default, and hooks can also override it per call. |
| 82 | + |
| 83 | +| What you want | Hook options | Example output | |
| 84 | +| ----------------- | ----------------------- | ---------------- | |
| 85 | +| Raw value | `{ format: 'value' }` | `#ff1a6e` | |
| 86 | +| CSS var reference | `{ format: 'var-ref' }` | `var(--primary)` | |
| 87 | +| CSS var name | `{ as: 'var-name' }` | `--primary` | |
| 88 | + |
| 89 | +Supported output shapes: |
| 90 | + |
| 91 | +- `format` chooses the _consumption result_ (`'value'` vs `'var-ref'`) when `as: 'result'` (default). |
| 92 | +- `as: 'var-name'` is a separate mode that returns the CSS custom property name (`--xxx`). In this mode `format` is ignored, because there is no “value vs var-ref” decision to make. |
| 93 | + |
| 94 | +`as: 'var-name'` is a separate mode that returns the bare property name (`--xxx`) rather than a complete CSS value. Useful when building expressions like `var(--xxx, fallback)`, `calc(...)`, or when you need the property name as a key. |
| 95 | + |
| 96 | +Example: |
| 97 | + |
| 98 | +```tsx |
| 99 | +import { useLunaColor } from '@dugyu/luna-reactlynx'; |
| 100 | + |
| 101 | +const getValue = useLunaColor({ format: 'value' }); |
| 102 | +const getVarRef = useLunaColor({ format: 'var-ref' }); |
| 103 | +const getVarName = useLunaColor({ as: 'var-name' }); |
| 104 | + |
| 105 | +getValue('primary'); // '#ff1a6e' (values-backed theme only) |
| 106 | +getVarRef('primary'); // 'var(--primary)' |
| 107 | +getVarName('primary'); // '--primary' |
| 108 | +``` |
| 109 | + |
| 110 | +#### CSS var prefix |
| 111 | + |
| 112 | +If your CSS variables are emitted with a prefix (e.g. `--luna-primary`), set `cssVarPrefix` either when creating the runtime theme (default for all hooks) or when consuming: |
| 113 | + |
| 114 | +```tsx |
| 115 | +import { |
| 116 | + LunaThemeProvider, |
| 117 | + createLunaTheme, |
| 118 | + useLunaColor, |
| 119 | +} from '@dugyu/luna-reactlynx'; |
| 120 | +import { lunarisLightTokens } from '@dugyu/luna-tokens'; |
| 121 | + |
| 122 | +const theme = createLunaTheme(lunarisLightTokens, { |
| 123 | + consumptionFormat: 'var-ref', |
| 124 | + cssVarPrefix: 'luna', |
| 125 | +}); |
| 126 | + |
| 127 | +<LunaThemeProvider theme={theme}> |
| 128 | + <Demo /> |
| 129 | +</LunaThemeProvider>; |
| 130 | + |
| 131 | +function Demo() { |
| 132 | + const getColor = useLunaColor(); |
| 133 | + getColor('primary'); // 'var(--luna-primary)' |
| 134 | + |
| 135 | + const getUnprefixed = useLunaColor({ cssVarPrefix: '' }); |
| 136 | + getUnprefixed('primary'); // 'var(--primary)' |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +> If you pass a meta-only theme input (no concrete values), only `consumptionFormat: 'var-ref'` is valid — `createLunaTheme()` will throw otherwise. |
| 141 | +
|
| 142 | +## Usage: CSS Variables |
| 143 | + |
| 144 | +Import the LUNA stylesheet globally, then apply a theme class (e.g. `lunaris-light`) to scope variables under your app root. `LunaTheme` is an optional helper that reads the active theme key and attaches the resolved theme class to the root node. |
| 145 | + |
| 146 | +If you prefer to manage the class yourself, you can skip `LunaTheme` entirely: |
| 147 | + |
| 148 | +```tsx |
| 149 | +import '@dugyu/luna-styles/index.css'; |
| 150 | +import './app.css'; |
| 151 | + |
| 152 | +export function App() { |
| 153 | + return ( |
| 154 | + <page className='lunaris-light'> |
| 155 | + <view className='app' /> |
| 156 | + </page> |
| 157 | + ); |
| 158 | +} |
| 159 | +``` |
| 160 | + |
| 161 | +> Note: Using `var(--xxx)` inside inline `style={{ ... }}` requires Lynx 3.6+. For Lynx < 3.6, consume CSS variables via Tailwind utilities or a stylesheet (Vanilla CSS), and apply classes on the element instead of inline `style`. |
| 162 | +
|
| 163 | +### Inline style (Lynx 3.6+) |
| 164 | + |
| 165 | +```tsx |
| 166 | +import { LunaTheme } from '@dugyu/luna-reactlynx/runtime'; |
| 167 | +import '@dugyu/luna-styles/index.css'; |
| 168 | + |
| 169 | +export function App() { |
| 170 | + return ( |
| 171 | + <LunaTheme> |
| 172 | + <view style={{ backgroundColor: 'var(--canvas)' }} /> |
| 173 | + </LunaTheme> |
| 174 | + ); |
| 175 | +} |
| 176 | +``` |
| 177 | + |
| 178 | +`LunaTheme` resolves the active theme key in this order: |
| 179 | + |
| 180 | +1. The explicit `themeKey` prop |
| 181 | +2. `lynx.__globalProps.lunaTheme` |
| 182 | +3. The built-in default |
| 183 | + |
| 184 | +**Optional:** for typed `lynx.__globalProps.lunaTheme`, import the augmentation once at your app entry: |
| 185 | + |
| 186 | +```ts |
| 187 | +import '@dugyu/luna-reactlynx/runtime/global-props'; |
| 188 | +``` |
| 189 | + |
| 190 | +### Tailwind (Lynx 3.6- friendly) |
| 191 | + |
| 192 | +If you use Tailwind, pair `@dugyu/luna-styles` (variables) with `@dugyu/luna-tailwind` (utilities). Then you can consume colors via semantic utilities like `bg-canvas` / `text-content` without relying on inline `var(...)`. |
| 193 | + |
| 194 | +```tsx |
| 195 | +import { LunaTheme } from '@dugyu/luna-reactlynx/runtime'; |
| 196 | +import '@dugyu/luna-styles/index.css'; |
| 197 | + |
| 198 | +export function App() { |
| 199 | + return ( |
| 200 | + <LunaTheme> |
| 201 | + <view className='bg-canvas'> |
| 202 | + <text className='text-content'>Hello</text> |
| 203 | + </view> |
| 204 | + </LunaTheme> |
| 205 | + ); |
| 206 | +} |
| 207 | +``` |
| 208 | + |
| 209 | +### Vanilla CSS class (Lynx 3.6- friendly) |
| 210 | + |
| 211 | +Consume `var(--xxx)` in a stylesheet, then reference it by `className`: |
| 212 | + |
| 213 | +```css |
| 214 | +.app { |
| 215 | + background-color: var(--canvas); |
| 216 | + color: var(--content); |
| 217 | +} |
| 218 | +``` |
| 219 | + |
| 220 | +```tsx |
| 221 | +import { LunaTheme } from '@dugyu/luna-reactlynx/runtime'; |
| 222 | +import '@dugyu/luna-styles/index.css'; |
| 223 | +import './app.css'; |
| 224 | + |
| 225 | +export function App() { |
| 226 | + return ( |
| 227 | + <LunaTheme> |
| 228 | + <view className='app' /> |
| 229 | + </LunaTheme> |
| 230 | + ); |
| 231 | +} |
| 232 | +``` |
| 233 | + |
| 234 | +## How to understand `LunaThemeProvider` vs `LunaTheme` |
| 235 | + |
| 236 | +They are orthogonal and can be used independently: |
| 237 | + |
| 238 | +- `LunaTheme` (runtime shell): only toggles the theme class name on your root node, so the CSS variables from `@dugyu/luna-styles` become active in that subtree. |
| 239 | +- `LunaThemeProvider` (theming context): provides a resolved theme object to hooks like `useLunaColor(s)`. It does not inject any CSS variables into the runtime. |
| 240 | + |
| 241 | +In other words, `LunaTheme` is a convenience for applying the theme class; if you already manage the root class yourself, you do not need it. |
| 242 | + |
| 243 | +## Which style to use |
| 244 | + |
| 245 | +| | JS Tokens | CSS Variables | |
| 246 | +| ------------------------------------------------------ | ---------------- | --------------------------------- | |
| 247 | +| Color consumption | Raw values in JS | `var(--xxx)` / Tailwind utilities | |
| 248 | +| Already using `@dugyu/luna-styles` | — | ✓ | |
| 249 | +| Need theme object in JS (e.g. animation, inline style) | ✓ | — | |
| 250 | + |
| 251 | +## LUNA Packages |
| 252 | + |
| 253 | +- `@dugyu/luna-tokens` — source of truth for token values |
| 254 | +- `@dugyu/luna-core` — token and theme type definitions |
| 255 | +- `@dugyu/luna-styles` — CSS variables output |
| 256 | +- `@dugyu/luna-tailwind` — Tailwind utilities output |
| 257 | +- `@dugyu/luna-reactlynx` — ReactLynx runtime integration (this package) |
0 commit comments