@roxyapi/ui 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/AGENTS.md +228 -29
  2. package/README.md +291 -19
  3. package/dist/cdn/components/ashtakavarga-grid.js +74 -19
  4. package/dist/cdn/components/ashtakavarga-grid.js.map +2 -2
  5. package/dist/cdn/components/biorhythm-chart.js +18 -4
  6. package/dist/cdn/components/biorhythm-chart.js.map +2 -2
  7. package/dist/cdn/components/choghadiya-grid.js +47 -12
  8. package/dist/cdn/components/choghadiya-grid.js.map +3 -3
  9. package/dist/cdn/components/compatibility-card.js +21 -7
  10. package/dist/cdn/components/compatibility-card.js.map +2 -2
  11. package/dist/cdn/components/dasha-timeline.js +113 -28
  12. package/dist/cdn/components/dasha-timeline.js.map +3 -3
  13. package/dist/cdn/components/data.js +27 -13
  14. package/dist/cdn/components/data.js.map +2 -2
  15. package/dist/cdn/components/divisional-chart.js +225 -118
  16. package/dist/cdn/components/divisional-chart.js.map +4 -4
  17. package/dist/cdn/components/dosha-card.js +18 -4
  18. package/dist/cdn/components/dosha-card.js.map +2 -2
  19. package/dist/cdn/components/endpoint-form.js +25 -11
  20. package/dist/cdn/components/endpoint-form.js.map +2 -2
  21. package/dist/cdn/components/guna-milan.js +20 -6
  22. package/dist/cdn/components/guna-milan.js.map +2 -2
  23. package/dist/cdn/components/hexagram.js +22 -8
  24. package/dist/cdn/components/hexagram.js.map +2 -2
  25. package/dist/cdn/components/horoscope-card.js +20 -6
  26. package/dist/cdn/components/horoscope-card.js.map +2 -2
  27. package/dist/cdn/components/kp-chart.js +19 -5
  28. package/dist/cdn/components/kp-chart.js.map +2 -2
  29. package/dist/cdn/components/kp-planets-table.js +17 -3
  30. package/dist/cdn/components/kp-planets-table.js.map +2 -2
  31. package/dist/cdn/components/kp-ruling-planets.js +17 -3
  32. package/dist/cdn/components/kp-ruling-planets.js.map +2 -2
  33. package/dist/cdn/components/location-search.js +18 -4
  34. package/dist/cdn/components/location-search.js.map +2 -2
  35. package/dist/cdn/components/moon-phase.js +27 -13
  36. package/dist/cdn/components/moon-phase.js.map +2 -2
  37. package/dist/cdn/components/nakshatra-card.js +16 -2
  38. package/dist/cdn/components/nakshatra-card.js.map +2 -2
  39. package/dist/cdn/components/natal-chart.js +79 -40
  40. package/dist/cdn/components/natal-chart.js.map +3 -3
  41. package/dist/cdn/components/numerology-card.js +18 -4
  42. package/dist/cdn/components/numerology-card.js.map +2 -2
  43. package/dist/cdn/components/panchang-table.js +53 -25
  44. package/dist/cdn/components/panchang-table.js.map +3 -3
  45. package/dist/cdn/components/shadbala-table.js +24 -10
  46. package/dist/cdn/components/shadbala-table.js.map +2 -2
  47. package/dist/cdn/components/synastry-chart.js +96 -48
  48. package/dist/cdn/components/synastry-chart.js.map +3 -3
  49. package/dist/cdn/components/tarot-card.js +17 -3
  50. package/dist/cdn/components/tarot-card.js.map +2 -2
  51. package/dist/cdn/components/tarot-spread.js +39 -25
  52. package/dist/cdn/components/tarot-spread.js.map +2 -2
  53. package/dist/cdn/components/transits-table.js +18 -4
  54. package/dist/cdn/components/transits-table.js.map +2 -2
  55. package/dist/cdn/components/vedic-kundli.js +215 -105
  56. package/dist/cdn/components/vedic-kundli.js.map +4 -4
  57. package/dist/cdn/components/vedic-planets-table.js +22 -8
  58. package/dist/cdn/components/vedic-planets-table.js.map +2 -2
  59. package/dist/cdn/components/western-planets-table.js +18 -4
  60. package/dist/cdn/components/western-planets-table.js.map +2 -2
  61. package/dist/cdn/components/yoga-list.js +17 -3
  62. package/dist/cdn/components/yoga-list.js.map +2 -2
  63. package/dist/cdn/roxy-ui.js +1082 -816
  64. package/dist/cdn/roxy-ui.js.map +4 -4
  65. package/dist/components/ashtakavarga-grid.d.ts +13 -1
  66. package/dist/components/ashtakavarga-grid.d.ts.map +1 -1
  67. package/dist/components/ashtakavarga-grid.js +86 -11
  68. package/dist/components/ashtakavarga-grid.js.map +2 -2
  69. package/dist/components/biorhythm-chart.js +14 -0
  70. package/dist/components/biorhythm-chart.js.map +2 -2
  71. package/dist/components/choghadiya-grid.d.ts +6 -0
  72. package/dist/components/choghadiya-grid.d.ts.map +1 -1
  73. package/dist/components/choghadiya-grid.js +50 -2
  74. package/dist/components/choghadiya-grid.js.map +2 -2
  75. package/dist/components/compatibility-card.js +14 -0
  76. package/dist/components/compatibility-card.js.map +2 -2
  77. package/dist/components/dasha-timeline.d.ts +10 -0
  78. package/dist/components/dasha-timeline.d.ts.map +1 -1
  79. package/dist/components/dasha-timeline.js +135 -4
  80. package/dist/components/dasha-timeline.js.map +2 -2
  81. package/dist/components/data.js +14 -0
  82. package/dist/components/data.js.map +2 -2
  83. package/dist/components/divisional-chart.d.ts +9 -6
  84. package/dist/components/divisional-chart.d.ts.map +1 -1
  85. package/dist/components/divisional-chart.js +546 -251
  86. package/dist/components/divisional-chart.js.map +4 -4
  87. package/dist/components/dosha-card.js +14 -0
  88. package/dist/components/dosha-card.js.map +2 -2
  89. package/dist/components/endpoint-form.js +14 -0
  90. package/dist/components/endpoint-form.js.map +2 -2
  91. package/dist/components/guna-milan.js +14 -0
  92. package/dist/components/guna-milan.js.map +2 -2
  93. package/dist/components/hexagram.js +14 -0
  94. package/dist/components/hexagram.js.map +2 -2
  95. package/dist/components/horoscope-card.js +14 -0
  96. package/dist/components/horoscope-card.js.map +2 -2
  97. package/dist/components/kp-chart.js +14 -0
  98. package/dist/components/kp-chart.js.map +2 -2
  99. package/dist/components/kp-planets-table.js +14 -0
  100. package/dist/components/kp-planets-table.js.map +2 -2
  101. package/dist/components/kp-ruling-planets.js +14 -0
  102. package/dist/components/kp-ruling-planets.js.map +2 -2
  103. package/dist/components/location-search.js +14 -0
  104. package/dist/components/location-search.js.map +2 -2
  105. package/dist/components/moon-phase.js +14 -0
  106. package/dist/components/moon-phase.js.map +2 -2
  107. package/dist/components/nakshatra-card.js +14 -0
  108. package/dist/components/nakshatra-card.js.map +2 -2
  109. package/dist/components/natal-chart.d.ts.map +1 -1
  110. package/dist/components/natal-chart.js +76 -6
  111. package/dist/components/natal-chart.js.map +2 -2
  112. package/dist/components/numerology-card.js +14 -0
  113. package/dist/components/numerology-card.js.map +2 -2
  114. package/dist/components/panchang-table.d.ts +1 -0
  115. package/dist/components/panchang-table.d.ts.map +1 -1
  116. package/dist/components/panchang-table.js +37 -1
  117. package/dist/components/panchang-table.js.map +2 -2
  118. package/dist/components/shadbala-table.js +14 -0
  119. package/dist/components/shadbala-table.js.map +2 -2
  120. package/dist/components/synastry-chart.d.ts +6 -0
  121. package/dist/components/synastry-chart.d.ts.map +1 -1
  122. package/dist/components/synastry-chart.js +106 -7
  123. package/dist/components/synastry-chart.js.map +2 -2
  124. package/dist/components/tarot-card.js +14 -0
  125. package/dist/components/tarot-card.js.map +2 -2
  126. package/dist/components/tarot-spread.js +14 -0
  127. package/dist/components/tarot-spread.js.map +2 -2
  128. package/dist/components/transits-table.js +14 -0
  129. package/dist/components/transits-table.js.map +2 -2
  130. package/dist/components/vedic-kundli.d.ts +14 -9
  131. package/dist/components/vedic-kundli.d.ts.map +1 -1
  132. package/dist/components/vedic-kundli.js +537 -245
  133. package/dist/components/vedic-kundli.js.map +4 -4
  134. package/dist/components/vedic-planets-table.js +14 -0
  135. package/dist/components/vedic-planets-table.js.map +2 -2
  136. package/dist/components/western-planets-table.js +14 -0
  137. package/dist/components/western-planets-table.js.map +2 -2
  138. package/dist/components/yoga-list.js +14 -0
  139. package/dist/components/yoga-list.js.map +2 -2
  140. package/dist/index.cjs +1397 -797
  141. package/dist/index.cjs.map +4 -4
  142. package/dist/index.js +1278 -678
  143. package/dist/index.js.map +4 -4
  144. package/dist/styles/tokens.css +8 -23
  145. package/dist/utils/base-styles.d.ts.map +1 -1
  146. package/dist/utils/kundli-render.d.ts +43 -104
  147. package/dist/utils/kundli-render.d.ts.map +1 -1
  148. package/dist/utils/kundli-styles.d.ts +13 -0
  149. package/dist/utils/kundli-styles.d.ts.map +1 -0
  150. package/dist/version.d.ts +1 -1
  151. package/package.json +1 -1
  152. package/src/components/ashtakavarga-grid.ts +73 -11
  153. package/src/components/choghadiya-grid.ts +37 -2
  154. package/src/components/dasha-timeline.ts +135 -4
  155. package/src/components/divisional-chart.ts +40 -97
  156. package/src/components/natal-chart.ts +89 -6
  157. package/src/components/panchang-table.ts +34 -1
  158. package/src/components/synastry-chart.ts +84 -8
  159. package/src/components/vedic-kundli.ts +35 -95
  160. package/src/styles/tokens.css +8 -23
  161. package/src/utils/base-styles.ts +14 -0
  162. package/src/utils/kundli-render.ts +609 -270
  163. package/src/utils/kundli-styles.ts +124 -0
  164. package/src/version.ts +1 -1
package/README.md CHANGED
@@ -76,36 +76,59 @@ Light, dark, your brand. Override one CSS variable and every component updates.
76
76
  }
77
77
  ```
78
78
 
79
- Pick a tone, set the vars, every chart and card follows. Full token reference at [THEMING.md](https://github.com/RoxyAPI/ui/blob/main/packages/ui/THEMING.md). Live tweaker on the [demo site](https://roxyapi.github.io/ui/).
79
+ Pick a tone, set the vars, every chart and card follows. Full token reference at [THEMING.md](https://github.com/RoxyAPI/ui/blob/main/packages/ui/THEMING.md). Live tweaker on the [demo site](https://roxyapi.github.io/ui/). See the [FAQ](#faq) for switching between light and dark at runtime.
80
80
 
81
- ## Gallery (chart-heavy components)
81
+ ## Gallery
82
+
83
+ Every chart, table, and card adapts to light and dark automatically. Hover any image on GitHub to inspect tooltips.
84
+
85
+ ### Western astrology
82
86
 
83
87
  <table>
84
88
  <tr>
89
+ <td width="50%"><strong>Natal chart</strong> · <code>&lt;roxy-natal-chart&gt;</code><br><sub>POST /astrology/natal-chart</sub><br>
90
+ <picture>
91
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/natal-chart-dark.png">
92
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/natal-chart-light.png" alt="Natal chart wheel with 14 planets, real house cusps, IC DC Part of Fortune Vertex, aspect lines">
93
+ </picture>
94
+ </td>
85
95
  <td width="50%"><strong>Synastry</strong> · <code>&lt;roxy-synastry-chart&gt;</code><br><sub>POST /astrology/synastry</sub><br>
86
96
  <picture>
87
97
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/synastry-chart-dark.png">
88
- <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/synastry-chart-light.png" alt="Synastry dual-wheel with inter-aspects">
98
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/synastry-chart-light.png" alt="Synastry dual-wheel with inter-aspects table">
89
99
  </picture>
90
100
  </td>
91
- <td width="50%"><strong>Moon phase</strong> · <code>&lt;roxy-moon-phase&gt;</code><br><sub>GET /astrology/moon-phase/&lbrace;current,upcoming,calendar&rbrace;</sub><br>
101
+ </tr>
102
+ </table>
103
+
104
+ ### Vedic astrology
105
+
106
+ <table>
107
+ <tr>
108
+ <td width="50%"><strong>Vedic kundli</strong> · <code>&lt;roxy-vedic-kundli&gt;</code><br><sub>POST /vedic-astrology/birth-chart</sub><br>
109
+ <picture>
110
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/vedic-kundli-dark.png">
111
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/vedic-kundli-light.png" alt="Vedic kundli D1 rashi chart, South Indian style with Lagna marker">
112
+ </picture>
113
+ </td>
114
+ <td width="50%"><strong>KP chart</strong> · <code>&lt;roxy-kp-chart&gt;</code><br><sub>POST /vedic-astrology/kp/chart</sub><br>
92
115
  <picture>
93
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/moon-phase-dark.png">
94
- <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/moon-phase-light.png" alt="Moon phase card with illumination and age">
116
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/kp-chart-dark.png">
117
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/kp-chart-light.png" alt="KP chart with cusps and sub-lord stellar hierarchy">
95
118
  </picture>
96
119
  </td>
97
120
  </tr>
98
121
  <tr>
99
- <td width="50%"><strong>Biorhythm</strong> · <code>&lt;roxy-biorhythm-chart&gt;</code><br><sub>POST /biorhythm/&lbrace;daily,forecast,critical-days&rbrace;</sub><br>
122
+ <td width="50%"><strong>Divisional chart</strong> · <code>&lt;roxy-divisional-chart&gt;</code><br><sub>POST /vedic-astrology/divisional-chart</sub><br>
100
123
  <picture>
101
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/biorhythm-chart-dark.png">
102
- <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/biorhythm-chart-light.png" alt="Biorhythm physical, emotional, intellectual cycle bars">
124
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/divisional-chart-dark.png">
125
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/divisional-chart-light.png" alt="D2 to D60 varga chart, D9 navamsa shown">
103
126
  </picture>
104
127
  </td>
105
- <td width="50%"><strong>I Ching hexagram</strong> · <code>&lt;roxy-hexagram&gt;</code><br><sub>GET /iching/hexagrams/&lbrace;number&rbrace;, /iching/cast</sub><br>
128
+ <td width="50%"><strong>Ashtakavarga grid</strong> · <code>&lt;roxy-ashtakavarga-grid&gt;</code><br><sub>POST /vedic-astrology/ashtakavarga</sub><br>
106
129
  <picture>
107
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/hexagram-dark.png">
108
- <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/hexagram-light.png" alt="I Ching hexagram with trigrams and judgment">
130
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/ashtakavarga-grid-dark.png">
131
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/ashtakavarga-grid-light.png" alt="Ashtakavarga sarva and bhinna bindu heatmap">
109
132
  </picture>
110
133
  </td>
111
134
  </tr>
@@ -113,13 +136,46 @@ Pick a tone, set the vars, every chart and card follows. Full token reference at
113
136
  <td width="50%"><strong>Dasha timeline</strong> · <code>&lt;roxy-dasha-timeline&gt;</code><br><sub>POST /vedic-astrology/dasha/&lbrace;current,major,sub&rbrace;</sub><br>
114
137
  <picture>
115
138
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/dasha-timeline-dark.png">
116
- <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/dasha-timeline-light.png" alt="Vimshottari dasha mahadasha and antardasha timeline">
139
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/dasha-timeline-light.png" alt="Vimshottari mahadasha and antardasha timeline with progress bars">
117
140
  </picture>
118
141
  </td>
142
+ <td width="50%"><strong>Shadbala table</strong> · <code>&lt;roxy-shadbala-table&gt;</code><br><sub>POST /vedic-astrology/shadbala</sub><br>
143
+ <picture>
144
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/shadbala-table-dark.png">
145
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/shadbala-table-light.png" alt="Six-fold planetary strength bars with rupas and adequacy badges">
146
+ </picture>
147
+ </td>
148
+ </tr>
149
+ </table>
150
+
151
+ ### Other domains
152
+
153
+ <table>
154
+ <tr>
119
155
  <td width="50%"><strong>Tarot spread</strong> · <code>&lt;roxy-tarot-spread&gt;</code><br><sub>POST /tarot/spreads/&lbrace;three-card,celtic-cross,love&rbrace;</sub><br>
120
156
  <picture>
121
157
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/tarot-spread-dark.png">
122
- <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/tarot-spread-light.png" alt="Tarot spread with three-card layout and reading">
158
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/tarot-spread-light.png" alt="Three-card tarot spread with position labels and reading">
159
+ </picture>
160
+ </td>
161
+ <td width="50%"><strong>Biorhythm</strong> · <code>&lt;roxy-biorhythm-chart&gt;</code><br><sub>POST /biorhythm/&lbrace;daily,forecast,critical-days&rbrace;</sub><br>
162
+ <picture>
163
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/biorhythm-chart-dark.png">
164
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/biorhythm-chart-light.png" alt="Physical, emotional, intellectual cycle bars">
165
+ </picture>
166
+ </td>
167
+ </tr>
168
+ <tr>
169
+ <td width="50%"><strong>I Ching hexagram</strong> · <code>&lt;roxy-hexagram&gt;</code><br><sub>GET /iching/hexagrams/&lbrace;number&rbrace;, /iching/cast</sub><br>
170
+ <picture>
171
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/hexagram-dark.png">
172
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/hexagram-light.png" alt="Hexagram with trigrams, judgment, image, changing lines">
173
+ </picture>
174
+ </td>
175
+ <td width="50%"><strong>Numerology</strong> · <code>&lt;roxy-numerology-card&gt;</code><br><sub>POST /numerology/&lbrace;life-path,expression,personal-year,chart&rbrace;</sub><br>
176
+ <picture>
177
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/numerology-card-dark.png">
178
+ <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/numerology-card-light.png" alt="Life path number card with archetype, keywords, and interpretation">
123
179
  </picture>
124
180
  </td>
125
181
  </tr>
@@ -138,7 +194,7 @@ Tables, cards, forms, and helper components in the [live demo](https://roxyapi.g
138
194
 
139
195
  ## Start with one component
140
196
 
141
- Vanilla HTML. Three lines. No build step.
197
+ Vanilla HTML. No build step. Replace `YOUR_API_KEY` with a publishable key from <https://roxyapi.com/account>.
142
198
 
143
199
  ```html
144
200
  <script
@@ -149,7 +205,7 @@ Vanilla HTML. Three lines. No build step.
149
205
  <roxy-natal-chart id="chart"></roxy-natal-chart>
150
206
  <script type="module">
151
207
  import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
152
- const roxy = createRoxy(import.meta.env?.ROXY_API_KEY);
208
+ const roxy = createRoxy('YOUR_API_KEY');
153
209
  const { data } = await roxy.astrology.generateNatalChart({
154
210
  body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
155
211
  });
@@ -157,7 +213,23 @@ Vanilla HTML. Three lines. No build step.
157
213
  </script>
158
214
  ```
159
215
 
160
- Then add the kundli, the panchang, the dasha timeline, the tarot spread.
216
+ > **Unwrap `data` before passing to the component.** The SDK returns `{ data, error, request, response }`. Pass the envelope and the chart renders `[object Object]`. This is the most common integration bug.
217
+
218
+ Want a Vedic kundli instead? Same shape, different SDK method:
219
+
220
+ ```html
221
+ <roxy-vedic-kundli id="kundli" chart-style="south"></roxy-vedic-kundli>
222
+ <script type="module">
223
+ import { createRoxy } from 'https://cdn.jsdelivr.net/npm/@roxyapi/sdk@latest/dist/factory.js';
224
+ const roxy = createRoxy('YOUR_API_KEY');
225
+ const { data } = await roxy.vedicAstrology.generateBirthChart({
226
+ body: { date: '1990-01-15', time: '14:30:00', latitude: 19.07, longitude: 72.88, timezone: 5.5 },
227
+ });
228
+ document.getElementById('kundli').data = data;
229
+ </script>
230
+ ```
231
+
232
+ In production, geocode the user's city with `<roxy-location-search>` (see [Quick start](#quick-start)) instead of hardcoding coordinates.
161
233
 
162
234
  ## Install
163
235
 
@@ -209,14 +281,185 @@ Always call `/location/search` first. Every chart endpoint expects latitude, lon
209
281
 
210
282
  > **Timezone format.** RoxyAPI accepts both forms: a decimal-hour offset (`5.5` for IST, `-5` for EST) or an IANA name (`'Asia/Kolkata'`, `'America/New_York'`). Pick one and stay consistent. The decimal form is shorter and what `/location/search` returns; examples on this page use it. The IANA form is correct over DST boundaries when historical accuracy matters.
211
283
 
284
+ ## Most-used components per domain
285
+
286
+ The highest-demand components by domain, in the order you are most likely to ship them. Each pairing shows the SDK call that returns the response shape the component renders. Spec change in the API translates to typed change at the component boundary; the pairing below is derived from the live OpenAPI spec, not invented. Full catalog in the [Components](#components) table.
287
+
288
+ ### 1. Western astrology (natal chart, daily horoscope, synastry)
289
+
290
+ The global astrology app market is $6.27B and almost entirely Western. Zodiac dating apps, Co-Star-style natal chart products, daily horoscope features, and lunar-cycle wellness apps all ship these first.
291
+
292
+ ```tsx
293
+ import { createRoxy } from '@roxyapi/sdk';
294
+ import { RoxyNatalChart, RoxyHoroscopeCard, RoxySynastryChart } from '@roxyapi/ui-react';
295
+
296
+ const roxy = createRoxy(process.env.ROXY_API_KEY!);
297
+
298
+ // 1. Natal chart. The #1 Western query, called on every onboarding.
299
+ const { data: natal } = await roxy.astrology.generateNatalChart({
300
+ body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
301
+ });
302
+ <RoxyNatalChart data={natal} />
303
+
304
+ // 2. Daily horoscope. Highest per-user call frequency in the catalog, drives DAUs and push.
305
+ const { data: horoscope } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
306
+ <RoxyHoroscopeCard data={horoscope} />
307
+
308
+ // 3. Synastry. The dating-app pro-tier feature, full inter-aspect analysis between two charts.
309
+ const { data: synastry } = await roxy.astrology.calculateSynastry({
310
+ body: {
311
+ person1: { date: '1990-01-15', time: '14:30:00', latitude: 28.61, longitude: 77.20, timezone: 5.5 },
312
+ person2: { date: '1992-07-22', time: '09:00:00', latitude: 19.07, longitude: 72.87, timezone: 5.5 },
313
+ },
314
+ });
315
+ <RoxySynastryChart data={synastry} />
316
+ ```
317
+
318
+ ### 2. Vedic astrology (kundli, panchang, dasha, dosha, KP, ashtakavarga)
319
+
320
+ The depth moat. India astrology market: $163M in 2024, projected $1.8B by 2030 (49% CAGR). Kundli, panchang, dasha, dosha, and KP horary are the five Google-dominant queries for every matrimonial platform, kundli generator, and muhurat app.
321
+
322
+ ```tsx
323
+ import {
324
+ RoxyVedicKundli, RoxyVedicPlanetsTable, RoxyPanchangTable,
325
+ RoxyDashaTimeline, RoxyDoshaCard, RoxyKpChart, RoxyAshtakavargaGrid,
326
+ } from '@roxyapi/ui-react';
327
+
328
+ // Kundli + positions table share a single API call (the same response renders both).
329
+ const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({
330
+ body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
331
+ });
332
+ <RoxyVedicKundli data={kundli} chart-style="south" />
333
+ <RoxyVedicPlanetsTable data={kundli} />
334
+
335
+ // Panchang. Tithi, nakshatra, yoga, karana, rahu kaal, abhijit muhurta in one call.
336
+ const { data: panchang } = await roxy.vedicAstrology.getDetailedPanchang({
337
+ body: { date: '2026-04-22', latitude: 28.6139, longitude: 77.209 },
338
+ });
339
+ <RoxyPanchangTable data={panchang} />
340
+
341
+ // Vimshottari dasha. The 120-year planetary period timeline.
342
+ const { data: dasha } = await roxy.vedicAstrology.getMajorDashas({
343
+ body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
344
+ });
345
+ <RoxyDashaTimeline data={dasha} period="major" />
346
+
347
+ // Mangal Dosha. Most-asked matrimonial question in India.
348
+ const { data: dosha } = await roxy.vedicAstrology.checkManglikDosha({
349
+ body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
350
+ });
351
+ <RoxyDoshaCard data={dosha} />
352
+
353
+ // KP chart. The horary timing tool, sub-lord stellar hierarchy on every cusp.
354
+ const { data: kp } = await roxy.vedicAstrology.generateKpChart({
355
+ body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
356
+ });
357
+ <RoxyKpChart data={kp} />
358
+
359
+ // Ashtakavarga. Bindu strength heatmap with Sarva, Bhinna, Shodhya Pinda views.
360
+ const { data: ashtaka } = await roxy.vedicAstrology.calculateAshtakavarga({
361
+ body: { date: '1990-01-15', time: '14:30:00', latitude: 28.6139, longitude: 77.209, timezone: 5.5 },
362
+ });
363
+ <RoxyAshtakavargaGrid data={ashtaka} />
364
+ ```
365
+
366
+ ### 3. Numerology (life path, full chart, personal year)
367
+
368
+ Commodity content with durable demand. `life path number calculator` is among the highest-volume spiritual searches globally. Works without birth time. Easiest domain to integrate.
369
+
370
+ ```tsx
371
+ import { RoxyNumerologyCard } from '@roxyapi/ui-react';
372
+
373
+ // Life Path. The #1 numerology keyword, every calculator page starts here.
374
+ const { data: lp } = await roxy.numerology.calculateLifePath({
375
+ body: { year: 1990, month: 1, day: 15 },
376
+ });
377
+ <RoxyNumerologyCard data={lp} type="life-path" />
378
+
379
+ // Full numerology chart. Premium one-shot: all six core numbers plus karmic, personal year.
380
+ const { data: chart } = await roxy.numerology.generateNumerologyChart({
381
+ body: { fullName: 'Jane Smith', year: 1990, month: 1, day: 15 },
382
+ });
383
+ <RoxyNumerologyCard data={chart} type="chart" />
384
+
385
+ // Personal Year. Annual forecast, drives January traffic spikes.
386
+ const { data: pyear } = await roxy.numerology.calculatePersonalYear({
387
+ body: { month: 1, day: 15, year: 2026 },
388
+ });
389
+ <RoxyNumerologyCard data={pyear} type="personal-year" />
390
+ ```
391
+
392
+ ### 4. Tarot (daily card, three-card, Celtic Cross)
393
+
394
+ High search volume, evergreen. The tarot card database is the highest per-endpoint call count in the catalog because apps fetch once and cache.
395
+
396
+ ```tsx
397
+ import { RoxyTarotCard, RoxyTarotSpread } from '@roxyapi/ui-react';
398
+
399
+ // Daily card. Stickiest tarot feature. Seed per user for deterministic once-per-day behavior.
400
+ const { data: daily } = await roxy.tarot.getDailyCard({ body: { seed: 'user-42' } });
401
+ <RoxyTarotCard data={daily} />
402
+
403
+ // Three-card past-present-future. Most-drawn spread on every tarot platform.
404
+ const { data: three } = await roxy.tarot.castThreeCard({
405
+ body: { question: 'My next quarter', seed: 'user-42' },
406
+ });
407
+ <RoxyTarotSpread data={three} />
408
+
409
+ // Celtic Cross. Professional-reader spread. Premium-tier, ten positions.
410
+ const { data: cc } = await roxy.tarot.castCelticCross({
411
+ body: { question: 'What should I focus on?', seed: 'user-42' },
412
+ });
413
+ <RoxyTarotSpread data={cc} />
414
+ ```
415
+
416
+ ### 5. Biorhythm (daily, forecast)
417
+
418
+ Zero competition domain. Steady search volume with the top Google result being a static calculator page. Pure land-grab for wellness, productivity, sports, and couples apps.
419
+
420
+ ```tsx
421
+ import { RoxyBiorhythmChart } from '@roxyapi/ui-react';
422
+
423
+ // Daily biorhythm. Physical, emotional, intellectual, intuitive, plus seven extended cycles.
424
+ // Seeded for stable "biorhythm of the day" features; pass a userId for per-user determinism.
425
+ const { data: bio } = await roxy.biorhythm.getDailyBiorhythm({
426
+ body: { seed: 'user-42', date: '2026-04-23' },
427
+ });
428
+ <RoxyBiorhythmChart data={bio} />
429
+
430
+ // Multi-day forecast. Best-day / worst-day planner for calendar and coaching products.
431
+ const { data: forecast } = await roxy.biorhythm.getForecast({
432
+ body: { birthDate: '1990-01-15', startDate: '2026-04-01', endDate: '2026-04-30' },
433
+ });
434
+ <RoxyBiorhythmChart data={forecast} mode="forecast" />
435
+ ```
436
+
437
+ ### 6. I Ching (cast a reading, hexagram lookup)
438
+
439
+ Meditation apps, decision-making tools, and wisdom chatbots. `i ching API` and `hexagram API` are the keywords.
440
+
441
+ ```tsx
442
+ import { RoxyHexagram } from '@roxyapi/ui-react';
443
+
444
+ // Cast a reading. Active divination, primary hexagram plus changing lines and transformed hexagram.
445
+ const { data: reading } = await roxy.iching.castReading({ query: { seed: 'user-42' } });
446
+ <RoxyHexagram data={reading} />
447
+
448
+ // Random hexagram. One-shot daily-hexagram surface for ambient apps.
449
+ const { data: random } = await roxy.iching.getRandomHexagram();
450
+ <RoxyHexagram data={random} />
451
+ ```
452
+
453
+ > **Pairing rule.** The SDK return value already matches the `data` prop on every component. No field renames, no glue code. When a new endpoint ships in the spec, the SDK and the component types regenerate together; the same pattern keeps working.
454
+
212
455
  ## API keys
213
456
 
214
457
  Get keys at <https://roxyapi.com/account>.
215
458
 
216
459
  - **Secret key** (server-side only). Use in Node, Bun, Hono, Next.js route handlers, Workers. Never commit, never ship in client bundles.
217
- - **Publishable key** (`pk_live_*` / `pk_test_*`). Safe in browsers, locked to the origins you register on the key. Use with the widgets auto-mount script for WordPress, Shopify, static HTML, embed scenarios. The API gateway rejects requests from any origin not on the key's allowlist.
460
+ - **Publishable key** (`pk_live_*` / `pk_test_*`). Safe in browsers, locked to the origins you register on the key. Use with the widgets auto-mount script for WordPress, Shopify, static HTML, embed scenarios. The API gateway rejects requests from any origin not on the allowlist.
218
461
 
219
- For the SDK examples on this page, set `ROXY_API_KEY` to a secret key in your server env. For the widgets auto-mount path (`data-publishable-key="pk_live_xxx"`), use a publishable key with your site's domain registered.
462
+ For the SDK examples on this page, set `ROXY_API_KEY` to a secret key in your server env. For the widgets auto-mount path (`data-publishable-key="pk_live_xxx"`), use a publishable key with your domain registered on it.
220
463
 
221
464
  ## Distribution
222
465
 
@@ -329,6 +572,35 @@ Roxy UI runs in any framework that supports the DOM: **React, Next.js, Vue, Svel
329
572
 
330
573
  ## FAQ
331
574
 
575
+ <details>
576
+ <summary><strong>How do I switch between light and dark mode?</strong></summary>
577
+
578
+ No events. No JavaScript bridge. Components read three CSS signals in priority order:
579
+
580
+ 1. **`prefers-color-scheme`**: follows the operating system by default. Ship nothing, get correct behaviour.
581
+ 2. **`data-theme="dark"` or `data-theme="light"`** on any ancestor (typically `<html>` or `<body>`). Wins over system preference.
582
+ 3. **`.dark` class** on any ancestor. Equivalent to `data-theme="dark"`. Useful when the host stack already toggles a `.dark` class (Tailwind, shadcn).
583
+
584
+ ```ts
585
+ // Toggle on click. No imports from this library needed.
586
+ document.documentElement.dataset.theme =
587
+ document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
588
+ ```
589
+
590
+ ```ts
591
+ // React: bind theme to component state.
592
+ useEffect(() => {
593
+ document.documentElement.dataset.theme = theme;
594
+ }, [theme]);
595
+ ```
596
+
597
+ Persist the choice in `localStorage` from your own code; the components do not own user preferences. Per-element overrides also work, so one chart can run in dark on an otherwise light page:
598
+
599
+ ```html
600
+ <roxy-natal-chart data-theme="dark" .data=${chart}></roxy-natal-chart>
601
+ ```
602
+ </details>
603
+
332
604
  <details>
333
605
  <summary><strong>How big is each component? What is the bundle cost?</strong></summary>
334
606