@roxyapi/ui 0.1.1 → 0.1.3

package/src/manifest.ts

@@ -0,0 +1,366 @@
+/**
+ * Single source of truth for component metadata. Every consumer that needs
+ * the (tag, pascal, slug, domain, description, heading, endpoints) tuple
+ * reads from here: scripts/build-react.ts, scripts/build-registry.ts,
+ * scripts/sync-docs.ts, scripts/build-widgets.ts, and the browser-side
+ * apps/docs/manifest.js (mirrored at build time).
+ *
+ * Hand-maintained. Add a component → add one entry here. The OpenAPI spec
+ * does not yet carry component metadata, so this stays manual.
+ */
+
+export type RoxyDomain =
+	| 'astrology'
+	| 'vedic'
+	| 'numerology'
+	| 'tarot'
+	| 'biorhythm'
+	| 'iching'
+	| 'utility';
+
+export interface RoxyComponent {
+	/** Pascal-case React export name, e.g. RoxyNatalChart */
+	pascal: string;
+	/** Custom-element tag, e.g. roxy-natal-chart */
+	tag: string;
+	/** Slug used in registry filenames and shadcn paths, e.g. natal-chart */
+	slug: string;
+	/** Domain bucket for filtering. */
+	domain: RoxyDomain;
+	/** Short human-readable heading shown on demo cards. */
+	heading: string;
+	/** SDK methods this component is designed to render. */
+	endpoints: string[];
+	/** One-line description for registry / docs / SEO meta. */
+	description: string;
+	/** Domain column label in the synced README/AGENTS table. */
+	docsLabel: string;
+	/** Endpoint(s) column body in the synced README/AGENTS table. */
+	endpointLabel: string;
+	/** What-it-renders column body in the synced README/AGENTS table. */
+	docsSummary: string;
+	/** Filter category in the browser demo grid. */
+	topic: string;
+	/**
+	 * True when the component does not consume a typed RoxyAPI response from a
+	 * customer server route. Three cases today:
+	 *   - <roxy-data>: pure renderer, accepts any shape, no fetch.
+	 *   - <roxy-location-search>: calls /location/search itself via publishable key.
+	 *   - <roxy-endpoint-form>: introspects the OpenAPI spec, emits roxy-submit.
+	 * The shadcn registry codegen emits a different doc body for these so we
+	 * never document a server route example with an undefined `data` reference.
+	 */
+	selfFetching?: boolean;
+}
+
+export const ROXY_COMPONENTS: readonly RoxyComponent[] = [
+	{
+		pascal: 'RoxyNatalChart',
+		tag: 'roxy-natal-chart',
+		slug: 'natal-chart',
+		domain: 'astrology',
+		heading: 'Natal chart',
+		endpoints: ['astrology.generateNatalChart'],
+		description:
+			'Western natal chart wheel for /astrology/natal-chart responses',
+		docsLabel: 'Western',
+		endpointLabel: 'POST /astrology/natal-chart',
+		docsSummary: 'Natal chart wheel with planet glyphs and aspect lines',
+		topic: 'Astrology',
+	},
+	{
+		pascal: 'RoxyHoroscopeCard',
+		tag: 'roxy-horoscope-card',
+		slug: 'horoscope-card',
+		domain: 'astrology',
+		heading: 'Daily horoscope',
+		endpoints: [
+			'astrology.getDailyHoroscope',
+			'astrology.getWeeklyHoroscope',
+			'astrology.getMonthlyHoroscope',
+		],
+		description:
+			'Daily, weekly, or monthly horoscope card for /astrology/horoscope/...',
+		docsLabel: 'Western',
+		endpointLabel: 'GET /astrology/horoscope/{sign}/{daily,weekly,monthly}',
+		docsSummary: 'Daily, weekly, or monthly horoscope card',
+		topic: 'Astrology',
+	},
+	{
+		pascal: 'RoxySynastryChart',
+		tag: 'roxy-synastry-chart',
+		slug: 'synastry-chart',
+		domain: 'astrology',
+		heading: 'Synastry',
+		endpoints: ['astrology.calculateSynastry'],
+		description: 'Dual-wheel synastry chart with inter-aspects table',
+		docsLabel: 'Western',
+		endpointLabel: 'POST /astrology/synastry',
+		docsSummary: 'Dual-wheel synastry with inter-aspects table',
+		topic: 'Astrology',
+	},
+	{
+		pascal: 'RoxyCompatibilityCard',
+		tag: 'roxy-compatibility-card',
+		slug: 'compatibility-card',
+		domain: 'astrology',
+		heading: 'Compatibility score',
+		endpoints: [
+			'astrology.calculateCompatibility',
+			'numerology.calculateNumCompatibility',
+			'biorhythm.calculateBioCompatibility',
+		],
+		description: 'Cross-domain compatibility score card',
+		docsLabel: 'Cross',
+		endpointLabel:
+			'POST /astrology/compatibility-score, /numerology/compatibility, /biorhythm/compatibility',
+		docsSummary: 'Score card with category breakdown',
+		topic: 'Astrology',
+	},
+	{
+		pascal: 'RoxyMoonPhase',
+		tag: 'roxy-moon-phase',
+		slug: 'moon-phase',
+		domain: 'astrology',
+		heading: 'Moon phase',
+		endpoints: [
+			'astrology.getCurrentMoonPhase',
+			'astrology.getUpcomingMoonPhases',
+			'astrology.getMoonCalendar',
+		],
+		description: 'Moon phase card and calendar',
+		docsLabel: 'Western',
+		endpointLabel: 'GET /astrology/moon-phase/{current,upcoming,calendar/...}',
+		docsSummary: 'Moon phase card and calendar',
+		topic: 'Astrology',
+	},
+	{
+		pascal: 'RoxyVedicKundli',
+		tag: 'roxy-vedic-kundli',
+		slug: 'vedic-kundli',
+		domain: 'vedic',
+		heading: 'Vedic kundli',
+		endpoints: ['vedicAstrology.generateBirthChart'],
+		description:
+			'South or North Indian Vedic kundli for /vedic-astrology/birth-chart',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/birth-chart',
+		docsSummary: 'South or North Indian kundli',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyPanchangTable',
+		tag: 'roxy-panchang-table',
+		slug: 'panchang-table',
+		domain: 'vedic',
+		heading: 'Panchang',
+		endpoints: [
+			'vedicAstrology.getBasicPanchang',
+			'vedicAstrology.getDetailedPanchang',
+		],
+		description:
+			'Panchang muhurta table with auspicious and inauspicious periods',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/panchang/{basic,detailed}',
+		docsSummary: '15+ muhurtas in detailed mode',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyDashaTimeline',
+		tag: 'roxy-dasha-timeline',
+		slug: 'dasha-timeline',
+		domain: 'vedic',
+		heading: 'Vimshottari dasha',
+		endpoints: [
+			'vedicAstrology.getCurrentDasha',
+			'vedicAstrology.getMajorDashas',
+			'vedicAstrology.getSubDashas',
+		],
+		description: 'Vimshottari dasha timeline with active mahadasha highlighted',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/dasha/{current,major,sub/...}',
+		docsSummary: 'Vimshottari mahadasha + antardasha + pratyantardasha',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyDoshaCard',
+		tag: 'roxy-dosha-card',
+		slug: 'dosha-card',
+		domain: 'vedic',
+		heading: 'Manglik dosha',
+		endpoints: [
+			'vedicAstrology.checkManglikDosha',
+			'vedicAstrology.checkKalsarpaDosha',
+			'vedicAstrology.checkSadhesati',
+		],
+		description: 'Manglik, Kaal Sarp, or Sade Sati presence card',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/dosha/{manglik,kalsarpa,sadhesati}',
+		docsSummary: 'Presence, severity, remedies, scoped effects',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyGunaMilan',
+		tag: 'roxy-guna-milan',
+		slug: 'guna-milan',
+		domain: 'vedic',
+		heading: 'Guna milan',
+		endpoints: ['vedicAstrology.calculateGunMilan'],
+		description: '36-point Ashtakoota matrimonial compatibility breakdown',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/compatibility',
+		docsSummary: '36-point Ashtakoota with eight sub-scores',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyKpPlanetsTable',
+		tag: 'roxy-kp-planets-table',
+		slug: 'kp-planets-table',
+		domain: 'vedic',
+		heading: 'KP planets',
+		endpoints: ['vedicAstrology.getKpPlanets'],
+		description: 'KP planets table with sub-lord and sub-sub-lord columns',
+		docsLabel: 'Vedic (KP)',
+		endpointLabel: 'POST /vedic-astrology/kp/planets',
+		docsSummary: 'Sub-lord and sub-sub-lord columns',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyNumerologyCard',
+		tag: 'roxy-numerology-card',
+		slug: 'numerology-card',
+		domain: 'numerology',
+		heading: 'Life path number',
+		endpoints: [
+			'numerology.calculateLifePath',
+			'numerology.calculateExpression',
+			'numerology.calculatePersonalYear',
+			'numerology.generateNumerologyChart',
+		],
+		description:
+			'Numerology card for life path, expression, personal year, or full chart',
+		docsLabel: 'Numerology',
+		endpointLabel:
+			'POST /numerology/{life-path,expression,personal-year,chart}',
+		docsSummary: 'Life path, expression, personal year, full chart',
+		topic: 'Numerology',
+	},
+	{
+		pascal: 'RoxyTarotCard',
+		tag: 'roxy-tarot-card',
+		slug: 'tarot-card',
+		domain: 'tarot',
+		heading: 'Daily tarot card',
+		endpoints: ['tarot.getCard', 'tarot.getDailyCard'],
+		description: 'Single tarot card with upright/reversed flip animation',
+		docsLabel: 'Tarot',
+		endpointLabel: 'GET /tarot/cards/{id}, POST /tarot/daily',
+		docsSummary: 'Single card with upright and reversed flip',
+		topic: 'Tarot',
+	},
+	{
+		pascal: 'RoxyTarotSpread',
+		tag: 'roxy-tarot-spread',
+		slug: 'tarot-spread',
+		domain: 'tarot',
+		heading: 'Three-card spread',
+		endpoints: [
+			'tarot.castThreeCard',
+			'tarot.castCelticCross',
+			'tarot.castLoveSpread',
+			'tarot.castYesNo',
+			'tarot.drawCards',
+		],
+		description:
+			'Tarot spread renderer for three-card, Celtic Cross, love, or yes/no',
+		docsLabel: 'Tarot',
+		endpointLabel:
+			'POST /tarot/spreads/{three-card,celtic-cross,love}, /tarot/yes-no, /tarot/draw',
+		docsSummary: 'Spreads with positions and reading',
+		topic: 'Tarot',
+	},
+	{
+		pascal: 'RoxyBiorhythmChart',
+		tag: 'roxy-biorhythm-chart',
+		slug: 'biorhythm-chart',
+		domain: 'biorhythm',
+		heading: 'Daily biorhythm',
+		endpoints: [
+			'biorhythm.getDailyBiorhythm',
+			'biorhythm.getForecast',
+			'biorhythm.getCriticalDays',
+		],
+		description: 'Daily biorhythm bars or multi-day forecast cycle lines',
+		docsLabel: 'Biorhythm',
+		endpointLabel: 'POST /biorhythm/{daily,forecast,critical-days}',
+		docsSummary: 'Daily bars, forecast cycle lines, critical days',
+		topic: 'Biorhythm',
+	},
+	{
+		pascal: 'RoxyHexagram',
+		tag: 'roxy-hexagram',
+		slug: 'hexagram',
+		domain: 'iching',
+		heading: 'I Ching hexagram',
+		endpoints: [
+			'iching.getHexagram',
+			'iching.castReading',
+			'iching.getDailyHexagram',
+			'iching.castDailyReading',
+			'iching.getRandomHexagram',
+		],
+		description:
+			'I Ching hexagram with trigram glyphs, judgment, image, and changing lines',
+		docsLabel: 'I Ching',
+		endpointLabel:
+			'GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast',
+		docsSummary: 'Hexagram with trigrams, judgment, image, changing lines',
+		topic: 'I Ching',
+	},
+	{
+		pascal: 'RoxyEndpointForm',
+		tag: 'roxy-endpoint-form',
+		slug: 'endpoint-form',
+		domain: 'utility',
+		heading: 'Schema-driven form',
+		endpoints: [],
+		description:
+			'Schema-driven form that emits roxy-submit with a validated payload',
+		docsLabel: 'Helper',
+		endpointLabel: 'Any endpoint via x-roxy-ui hints',
+		docsSummary: 'Schema-driven form, emits roxy-submit',
+		topic: 'Helpers',
+		selfFetching: true,
+	},
+	{
+		pascal: 'RoxyLocationSearch',
+		tag: 'roxy-location-search',
+		slug: 'location-search',
+		domain: 'utility',
+		heading: 'City search',
+		endpoints: ['location.searchCities'],
+		description: 'City search input with debounced /location/search calls',
+		docsLabel: 'Helper',
+		endpointLabel: 'GET /location/search',
+		docsSummary: 'Debounced city search input, emits roxy-location-select',
+		topic: 'Helpers',
+		selfFetching: true,
+	},
+	{
+		pascal: 'RoxyData',
+		tag: 'roxy-data',
+		slug: 'data',
+		domain: 'utility',
+		heading: 'Generic renderer',
+		endpoints: [],
+		description: 'Generic fallback renderer for any OpenAPI response shape',
+		docsLabel: 'Helper',
+		endpointLabel: 'Any response shape',
+		docsSummary: 'Generic fallback renderer for unknown shapes',
+		topic: 'Helpers',
+		selfFetching: true,
+	},
+];
+
+export type RoxyComponentTag = (typeof ROXY_COMPONENTS)[number]['tag'];
+export type RoxyComponentSlug = (typeof ROXY_COMPONENTS)[number]['slug'];

package/src/styles/tokens.css

@@ -25,11 +25,17 @@
 	 * with non-text use) keep --roxy-accent. */
 	--roxy-accent-fg: #b45309;
 
-	/* Color: status */
+	/* Color: status. The base value (success, warning, danger, info) is for
+	 * fills and tints. The -fg variant is darker so text on a light tint passes
+	 * WCAG AA (>= 4.5:1 on white). Use -fg whenever status color hits text. */
 	--roxy-success: #16a34a;
+	--roxy-success-fg: #166534;
 	--roxy-warning: #ea580c;
+	--roxy-warning-fg: #9a3412;
 	--roxy-danger: #dc2626;
+	--roxy-danger-fg: #991b1b;
 	--roxy-info: #0284c7;
+	--roxy-info-fg: #075985;
 
 	/* Color: surface */
 	--roxy-bg: #ffffff;
@@ -94,10 +100,18 @@
 		--roxy-accent: #fbbf24;
 		--roxy-accent-fg: #fbbf24;
 
+		/* Status -fg overrides must mirror the explicit [data-theme="dark"] block
+		 * below. Without these, a user on system dark with no data-theme attribute
+		 * inherits the light-mode -fg values (e.g. #166534 success) which renders
+		 * as near-invisible dark green on a near-black surface and fails WCAG AA. */
 		--roxy-success: #22c55e;
+		--roxy-success-fg: #86efac;
 		--roxy-warning: #fb923c;
+		--roxy-warning-fg: #fdba74;
 		--roxy-danger: #ef4444;
+		--roxy-danger-fg: #fca5a5;
 		--roxy-info: #38bdf8;
+		--roxy-info-fg: #7dd3fc;
 
 		--roxy-bg: #0a0a0a;
 		--roxy-fg: #fafafa;
@@ -112,6 +126,34 @@
 	}
 }
 
+/* Light theme override. Beats the @media (prefers-color-scheme: dark) block
+ * when the host explicitly opts back into light. Without this, a dark-mode OS
+ * pins the tokens to dark even after data-theme="light" is set. */
+:root[data-theme="light"],
+:host([data-theme="light"]),
+.light :host {
+	--roxy-primary: #0f172a;
+	--roxy-secondary: #475569;
+	--roxy-accent: #f59e0b;
+	--roxy-accent-fg: #b45309;
+
+	--roxy-success: #16a34a;
+	--roxy-warning: #ea580c;
+	--roxy-danger: #dc2626;
+	--roxy-info: #0284c7;
+
+	--roxy-bg: #ffffff;
+	--roxy-fg: #0a0a0a;
+	--roxy-muted: #71717a;
+	--roxy-border: #e4e4e7;
+	--roxy-ring: rgba(245, 158, 11, 0.4);
+
+	--roxy-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06);
+	--roxy-shadow-md:
+		0 4px 6px -1px rgba(0, 0, 0, 0.08), 0 2px 4px -2px rgba(0, 0, 0, 0.06);
+	--roxy-shadow-lg: 0 12px 24px -8px rgba(0, 0, 0, 0.14);
+}
+
 /* Dark theme via host opt-in */
 :root[data-theme="dark"],
 :host([data-theme="dark"]),
@@ -122,9 +164,13 @@
 	--roxy-accent-fg: #fbbf24;
 
 	--roxy-success: #22c55e;
+	--roxy-success-fg: #86efac;
 	--roxy-warning: #fb923c;
+	--roxy-warning-fg: #fdba74;
 	--roxy-danger: #ef4444;
+	--roxy-danger-fg: #fca5a5;
 	--roxy-info: #38bdf8;
+	--roxy-info-fg: #7dd3fc;
 
 	--roxy-bg: #0a0a0a;
 	--roxy-fg: #fafafa;

package/src/tokens/index.ts

@@ -22,6 +22,11 @@ export const PLANET_GLYPH: Record<string, string> = {
 	Lagna: 'La',
 	NorthNode: '☊',
 	SouthNode: '☋',
+	'North node': '☊',
+	'South node': '☋',
+	Chiron: '⚷',
+	Lilith: '⚸',
+	'Black moon lilith': '⚸',
 };
 
 export const PLANET_ABBR: Record<string, string> = {

package/src/types/types.gen.ts

@@ -28024,7 +28024,7 @@ export type ListCountriesError = ListCountriesErrors[keyof ListCountriesErrors];
 
 export type ListCountriesResponses = {
     /**
-     * Alphabetically sorted list of all 227 countries with ISO codes and city counts
+     * Alphabetically sorted list of all countries with ISO codes and city counts
      */
     200: {
         /**

package/src/utils/debounce.ts

@@ -1,13 +1,32 @@
 /**
  * Lightweight debounce for input handlers. Used by location search.
+ *
+ * The returned function exposes a `.cancel()` method so callers can clear a
+ * pending invocation when the host element disconnects, preventing the timer
+ * from firing on a detached node and mutating reactive state after teardown.
  */
+export interface Debounced<F extends (...args: never[]) => unknown> {
+	(...args: Parameters<F>): void;
+	cancel: () => void;
+}
+
 export function debounce<F extends (...args: never[]) => unknown>(
 	fn: F,
 	wait: number,
-): F {
+): Debounced<F> {
 	let timer: ReturnType<typeof setTimeout> | undefined;
-	return ((...args: Parameters<F>) => {
+	const debounced = ((...args: Parameters<F>) => {
 		if (timer) clearTimeout(timer);
-		timer = setTimeout(() => fn(...args), wait);
-	}) as F;
+		timer = setTimeout(() => {
+			timer = undefined;
+			fn(...args);
+		}, wait);
+	}) as Debounced<F>;
+	debounced.cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = undefined;
+		}
+	};
+	return debounced;
 }

package/src/utils/format.ts

@@ -0,0 +1,57 @@
+/**
+ * Display formatters for ISO timestamps and floats coming back from the API.
+ * Every helper returns "" for nullish or unparseable input so it falls out of
+ * template literals cleanly.
+ */
+
+export function formatTime(input: unknown): string {
+	if (typeof input !== 'string' || input.length === 0) return '';
+	if (/^\d{4}-\d{2}-\d{2}$/.test(input)) return '';
+	const bareTime = /^\d{2}:\d{2}(:\d{2})?$/.test(input);
+	const iso = bareTime ? `1970-01-01T${input}` : input;
+	const d = new Date(iso);
+	if (Number.isNaN(d.getTime())) return input;
+	return d.toLocaleTimeString(undefined, {
+		hour: 'numeric',
+		minute: '2-digit',
+		hour12: true,
+	});
+}
+
+export function formatDate(input: unknown): string {
+	if (typeof input !== 'string' || input.length === 0) return '';
+	const d = new Date(
+		/^\d{4}-\d{2}-\d{2}$/.test(input) ? `${input}T00:00:00` : input,
+	);
+	if (Number.isNaN(d.getTime())) return input;
+	return d.toLocaleDateString(undefined, {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+}
+
+export function formatTimeRange(
+	t: { start?: string; end?: string } | undefined,
+): string {
+	if (!t) return '';
+	const start = formatTime(t.start);
+	const end = formatTime(t.end);
+	if (start && end) return `${start} - ${end}`;
+	return start || end || '';
+}
+
+export function formatNumber(value: unknown, dp = 1): string {
+	if (typeof value !== 'number' || !Number.isFinite(value)) return '';
+	return value.toFixed(dp).replace(/\.?0+$/, '');
+}
+
+export function formatPercent(value: unknown, dp = 1): string {
+	const n = formatNumber(value, dp);
+	return n ? `${n}%` : '';
+}
+
+export function formatLongitude(value: unknown): string {
+	if (typeof value !== 'number' || !Number.isFinite(value)) return '';
+	return `${formatNumber(value, 2)}°`;
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/sync-version.ts. Do not edit.
+export const ROXY_UI_VERSION = '0.1.3';