@roxyapi/ui 0.1.2 → 0.2.0

package/src/manifest.ts

@@ -0,0 +1,340 @@
+/**
+ * Single source of truth for component metadata. Every consumer that needs
+ * the (tag, pascal, slug, description, heading) 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 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;
+	/** Short human-readable heading shown on demo cards. */
+	heading: 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',
+		heading: 'Natal chart',
+		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',
+		heading: 'Daily horoscope',
+		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',
+		heading: 'Synastry',
+		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',
+		heading: 'Compatibility score',
+		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',
+		heading: 'Moon phase',
+		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',
+		heading: 'Vedic kundli',
+		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',
+		heading: 'Panchang',
+		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',
+		heading: 'Vimshottari dasha',
+		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',
+		heading: 'Manglik dosha',
+		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',
+		heading: 'Guna milan',
+		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',
+		heading: 'KP planets',
+		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: 'RoxyTransitsTable',
+		tag: 'roxy-transits-table',
+		slug: 'transits-table',
+		heading: 'Transits',
+		description: 'Live planet positions plus aspects to a natal chart',
+		docsLabel: 'Western',
+		endpointLabel: 'POST /astrology/transits',
+		docsSummary:
+			'Transit planet positions plus optional aspects to a natal chart',
+		topic: 'Astrology',
+	},
+	{
+		pascal: 'RoxyDivisionalChart',
+		tag: 'roxy-divisional-chart',
+		slug: 'divisional-chart',
+		heading: 'Divisional chart',
+		description: 'D2 to D60 varga chart wheel with Vargottama markers',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/divisional-chart',
+		docsSummary:
+			'Generic divisional varga wheel from D2 Hora to D60 Shashtiamsa',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyAshtakavargaGrid',
+		tag: 'roxy-ashtakavarga-grid',
+		slug: 'ashtakavarga-grid',
+		heading: 'Ashtakavarga',
+		description: 'Sarva and Bhinna ashtakavarga heatmap with bindu scores',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/ashtakavarga',
+		docsSummary: 'Sarva, Bhinna, and Shodhya Pinda views in a tabbed heatmap',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyShadbalaTable',
+		tag: 'roxy-shadbala-table',
+		slug: 'shadbala-table',
+		heading: 'Shadbala',
+		description: 'Six-fold planetary strength with adequacy badge per planet',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/shadbala',
+		docsSummary:
+			'Six-fold planetary strength bar plus rupas and adequacy badge',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyYogaList',
+		tag: 'roxy-yoga-list',
+		slug: 'yoga-list',
+		heading: 'Yoga catalog',
+		description:
+			'Yoga reference cards from the catalog with optional detail mode',
+		docsLabel: 'Vedic',
+		endpointLabel: 'GET /vedic-astrology/yoga, /yoga/{id}',
+		docsSummary: 'Filterable yoga cards from the 300 plus yoga catalog',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyChoghadiyaGrid',
+		tag: 'roxy-choghadiya-grid',
+		slug: 'choghadiya-grid',
+		heading: 'Choghadiya',
+		description: 'Day and night Choghadiya muhurta tiles for activity timing',
+		docsLabel: 'Vedic',
+		endpointLabel: 'POST /vedic-astrology/panchang/choghadiya',
+		docsSummary: 'Day and night Choghadiya muhurta tiles colored by effect',
+		topic: 'Vedic',
+	},
+	{
+		pascal: 'RoxyNumerologyCard',
+		tag: 'roxy-numerology-card',
+		slug: 'numerology-card',
+		heading: 'Life path number',
+		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',
+		heading: 'Daily tarot card',
+		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',
+		heading: 'Three-card spread',
+		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',
+		heading: 'Daily biorhythm',
+		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',
+		heading: 'I Ching hexagram',
+		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',
+		heading: 'Schema-driven form',
+		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',
+		heading: 'City search',
+		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',
+		heading: 'Generic renderer',
+		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 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;
@@ -83,6 +89,16 @@
 	/* Motion */
 	--roxy-motion-duration: 200ms;
 	--roxy-motion-easing: cubic-bezier(0.4, 0, 0.2, 1);
+
+	/* Heat scale: 7-step gradient used by ashtakavarga bindu cells.
+	 * Low bindus (1) are cool green; high bindus (7+) are hot red. */
+	--roxy-heat-1: #f0fdf4;
+	--roxy-heat-2: #d1fae5;
+	--roxy-heat-3: #a7f3d0;
+	--roxy-heat-4: #fde68a;
+	--roxy-heat-5: #fdba74;
+	--roxy-heat-6: #fb923c;
+	--roxy-heat-7: #ef4444;
 }
 
 /* Dark theme via system preference */
@@ -94,10 +110,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;
@@ -109,9 +133,45 @@
 		--roxy-shadow-md:
 			0 4px 6px -1px rgba(0, 0, 0, 0.6), 0 2px 4px -2px rgba(0, 0, 0, 0.5);
 		--roxy-shadow-lg: 0 12px 24px -8px rgba(0, 0, 0, 0.7);
+
+		--roxy-heat-1: #052e16;
+		--roxy-heat-2: #14532d;
+		--roxy-heat-3: #166534;
+		--roxy-heat-4: #92400e;
+		--roxy-heat-5: #b45309;
+		--roxy-heat-6: #c2410c;
+		--roxy-heat-7: #b91c1c;
 	}
 }
 
+/* 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 +182,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;
@@ -136,6 +200,14 @@
 	--roxy-shadow-md:
 		0 4px 6px -1px rgba(0, 0, 0, 0.6), 0 2px 4px -2px rgba(0, 0, 0, 0.5);
 	--roxy-shadow-lg: 0 12px 24px -8px rgba(0, 0, 0, 0.7);
+
+	--roxy-heat-1: #052e16;
+	--roxy-heat-2: #14532d;
+	--roxy-heat-3: #166534;
+	--roxy-heat-4: #92400e;
+	--roxy-heat-5: #b45309;
+	--roxy-heat-6: #c2410c;
+	--roxy-heat-7: #b91c1c;
 }
 
 /* Reduced motion override */

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> = {
@@ -86,6 +91,15 @@ export const SIGNS_ORDER = [
 	'Pisces',
 ] as const;
 
+/**
+ * Lowercase rashi keys in canonical zodiac order. Derived from `SIGNS_ORDER`
+ * so the two stay in lockstep. The /vedic-astrology/birth-chart response
+ * carries planet buckets keyed by these names.
+ */
+export const RASHI_KEYS = SIGNS_ORDER.map((s) =>
+	s.toLowerCase(),
+) as readonly Lowercase<(typeof SIGNS_ORDER)[number]>[];
+
 /** Aspect symbols. Used by synastry and natal chart aspect tables. */
 export const ASPECT_SYMBOL: Record<string, string> = {
 	conjunction: '☌',

package/src/types/types.gen.ts

@@ -27907,7 +27907,7 @@ export type ListCountriesData = {
     path?: never;
     query?: {
         /**
-         * Maximum items to return per page. Range: 1-50, default 50.
+         * Maximum items to return per page. Range: 1-250, default 50.
          */
         limit?: number;
         /**
@@ -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: {
         /**
@@ -28075,7 +28075,7 @@ export type GetCitiesByCountryData = {
     };
     query?: {
         /**
-         * Maximum items to return per page. Range: 1-200, default 50.
+         * Maximum items to return per page. Range: 1-100, default 20.
          */
         limit?: number;
         /**

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,75 @@
+/**
+ * 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}%` : '';
+}
+
+/**
+ * CSS class name per aspect type. Used by natal and synastry chart aspect
+ * lines so the same color encoding (harmonious vs challenging) applies in
+ * both wheels. Keys are lowercase canonical names, values are CSS class
+ * suffixes the chart components define in their `:host` styles.
+ */
+export const ASPECT_CLASS: Record<string, string> = {
+	conjunction: 'aspect-conjunction',
+	sextile: 'aspect-sextile',
+	square: 'aspect-square',
+	trine: 'aspect-trine',
+	opposition: 'aspect-opposition',
+};
+
+/**
+ * Normalize an aspect entry's `type` field to a lowercase, hyphen-separated
+ * canonical name (`SEMI_SEXTILE` → `semi-sextile`). Accepts any aspect-shaped
+ * object so both natal and synastry inter-aspect entries can share this.
+ */
+export function normalizeAspect(a: { type?: string }): string {
+	return (a.type ?? '').toLowerCase().replace(/_/g, '-');
+}