feat(dasha-timeline): antara and sookshma demo cards, date column granularity per period length

Author: ph33nx

apps/docs/components-manifest.js

@@ -403,15 +403,28 @@ window.ROXY_UI_DEMOS = [
     body: ${JSON.stringify({ date: PERSON1.date, time: PERSON1.time, latitude: PERSON1.latitude, longitude: PERSON1.longitude }, null, 2).replace(/\n/g, '\n    ')},
   });`,
 	}),
-	// No dasha-antara / dasha-sookshma cards yet, deliberately. Their samples come
-	// from `scripts/refresh-samples.ts` via @roxyapi/sdk, and the published SDK
-	// regenerates from the live spec on its OWN pipeline, so it does not know a
-	// brand new operation for a while. A card with no sample renders an empty
-	// state, which is worse than no card. @roxyapi/sdk 1.2.50 does expose both
-	// operations, but bunfig.toml sets minimumReleaseAge = 3 days, so it cannot be
-	// installed here until 2026-07-29 and refresh-samples cannot capture them
-	// before that. Do not bypass that guard for a demo card. Full sequence:
-	// CLAUDE.md, "Binding a new endpoint to an EXISTING component", step 8.
+	entry({
+		id: 'dasha-antara',
+		tag: 'roxy-dasha-timeline',
+		heading: 'Pratyantardashas',
+		seoLine: 'Pratyantardashas within an antardasha, the third Vimshottari level',
+		attrs: ' period="antara"',
+		sdkCall: `  const { data } = await roxy.vedicAstrology.getPratyantardashas({
+    path: { mahadasha: 'venus', antardasha: 'saturn' },
+    body: ${JSON.stringify({ date: PERSON1.date, time: PERSON1.time, latitude: PERSON1.latitude, longitude: PERSON1.longitude }, null, 2).replace(/\n/g, '\n    ')},
+  });`,
+	}),
+	entry({
+		id: 'dasha-sookshma',
+		tag: 'roxy-dasha-timeline',
+		heading: 'Sookshma dashas',
+		seoLine: 'Sookshma dashas, day level timing at the fourth Vimshottari level',
+		attrs: ' period="sookshma"',
+		sdkCall: `  const { data } = await roxy.vedicAstrology.getSookshmaDashas({
+    path: { mahadasha: 'venus', antardasha: 'saturn', pratyantardasha: 'mercury' },
+    body: ${JSON.stringify({ date: PERSON1.date, time: PERSON1.time, latitude: PERSON1.latitude, longitude: PERSON1.longitude }, null, 2).replace(/\n/g, '\n    ')},
+  });`,
+	}),
 	entry({
 		id: 'guna',
 		tag: 'roxy-guna-milan',

apps/docs/img/tarot/minor/five-of-pentacles.jpg

@@ -3,4 +3,11 @@ preload = ["./packages/ui/tests/setup.ts"]
 
 [install]
 exact = false
+# Third-party packages must soak for three days before we will install them. This
+# repo ships a CDN bundle that executes in other people's browsers, so a poisoned
+# transitive release here reaches end users, not just our build. Keep this.
 minimumReleaseAge = 259200
+# Our OWN package is exempt: it is published from our CI via npm Trusted Publishing
+# (OIDC) with provenance, so the soak window buys nothing and would otherwise block
+# the demo and samples for three days every time the API gains an endpoint.
+minimumReleaseAgeExcludes = ["@roxyapi/sdk"]

apps/docs/img/tarot/minor/five-of-wands.jpg

@@ -45,7 +45,7 @@
 		"@hey-api/openapi-ts": "0.99.0",
 		"@lit-labs/rollup-plugin-minify-html-literals": "^0.2.0",
 		"@playwright/test": "^1.61.1",
-		"@roxyapi/sdk": "^1.2.45",
+		"@roxyapi/sdk": "^1.2.50",
 		"@types/bun": "^1.3.14",
 		"@types/node": "^26.1.1",
 		"@types/react": "^19.2.17",

apps/docs/sample-data.js

@@ -314,7 +314,7 @@ export class RoxyDashaTimeline extends RoxyDataElement<DashaData> {
 							${
 								periods.length > 0
 									? html`<div class="timeline" role="list">
-										${periods.map((p) => this.renderBar(p, maxYears))}
+										${periods.map((p) => this.renderBar(p, maxYears, grainFor(maxYears)))}
 									</div>`
 									: nothing
 							}`
@@ -562,7 +562,7 @@ export class RoxyDashaTimeline extends RoxyDataElement<DashaData> {
 		return (now - start) / (end - start);
 	}
 
-	private renderBar(p: DashaPeriod, max: number) {
+	private renderBar(p: DashaPeriod, max: number, grain: DateGrain) {
 		const years = p.durationYears;
 		const width = max > 0 ? (years / max) * 100 : 0;
 		const current = this.isCurrent(p);
@@ -589,16 +589,44 @@ export class RoxyDashaTimeline extends RoxyDataElement<DashaData> {
 				}
 			</span>
 			<span class="dates">
-				${p.startDate ? formatYear(p.startDate) : ''}
-				${p.endDate ? html`- ${formatYear(p.endDate)}` : ''}
+				${p.startDate ? formatBoundary(p.startDate, grain) : ''}
+				${p.endDate ? html`- ${formatBoundary(p.endDate, grain)}` : ''}
 			</span>
 		</div>`;
 	}
 }
 
-function formatYear(s: string): string {
-	const m = s.match(/^(\d{4})/);
-	return m ? m[1] : s;
+/**
+ * How precise the bar date column has to be, chosen from the LONGEST period in
+ * the set.
+ *
+ * A Mahadasha spans years, so a bare year reads cleanly and keeps the column
+ * narrow. A Sookshma spans days: printed as a year, every one of the nine rows
+ * reads "1990 - 1990" and the column carries no information at exactly the level
+ * a reader opened the drill-down to see.
+ */
+type DateGrain = 'year' | 'month' | 'day';
+
+const DAYS_PER_YEAR = 365.25;
+
+function grainFor(maxYears: number): DateGrain {
+	if (maxYears >= 2) return 'year';
+	if (maxYears >= 60 / DAYS_PER_YEAR) return 'month';
+	return 'day';
+}
+
+/** One end of a bar, at the chosen granularity. Day grain drops the year: these rows sit under a parent line that already states it, and the column is only 8rem wide. */
+function formatBoundary(s: string, grain: DateGrain): string {
+	if (grain === 'year') {
+		const m = s.match(/^(\d{4})/);
+		return m ? m[1] : s;
+	}
+	const d = new Date(s);
+	if (Number.isNaN(d.getTime())) return s;
+	const month = d.toLocaleString('en', { month: 'short' });
+	return grain === 'month'
+		? `${month} ${d.getFullYear()}`
+		: `${d.getDate()} ${month}`;
 }
 
 declare global {

bun.lock

@@ -2017,3 +2017,80 @@ describe('every tablist governs a real tabpanel', () => {
 		});
 	}
 });
+
+/**
+ * The bar date column has to stay informative at every level. Printed as a bare
+ * year, a sookshma list renders nine identical "1990 - 1990" rows, which is the
+ * column carrying no information at exactly the level the reader drilled to.
+ */
+describe('roxy-dasha-timeline date column adapts to the period length', () => {
+	async function mount(data: unknown, period: string) {
+		const el = document.createElement('roxy-dasha-timeline') as HTMLElement & {
+			data?: unknown;
+			period?: string;
+		};
+		el.period = period;
+		document.body.appendChild(el);
+		el.data = data;
+		await settled(el);
+		return el;
+	}
+	const dateCells = (el: Element) =>
+		[...(el.shadowRoot?.querySelectorAll('.dates') ?? [])].map(
+			(n) => n.textContent?.replace(/\s+/g, ' ').trim() ?? '',
+		);
+
+	test('mahadashas keep bare years', async () => {
+		const el = await mount(
+			{
+				mahadashas: [
+					{
+						planet: 'Ketu',
+						startDate: '1990-01-15T00:00:00',
+						endDate: '1997-01-15T00:00:00',
+						durationYears: 7,
+					},
+					{
+						planet: 'Venus',
+						startDate: '1997-01-15T00:00:00',
+						endDate: '2017-01-15T00:00:00',
+						durationYears: 20,
+					},
+				],
+			},
+			'major',
+		);
+		expect(dateCells(el)[0]).toBe('1990 - 1997');
+		el.remove();
+	});
+
+	test('day-long sookshma periods do not all collapse to one repeated year', async () => {
+		const el = await mount(
+			{
+				pratyantardashaLord: 'Mercury',
+				pratyantardashaPeriod: { planet: 'Mercury', durationYears: 0.45 },
+				sookshmaDashas: [
+					{
+						planet: 'Mercury',
+						startDate: '1990-01-19T00:00:00',
+						endDate: '1990-02-02T00:00:00',
+						durationYears: 0.04,
+					},
+					{
+						planet: 'Ketu',
+						startDate: '1990-02-02T00:00:00',
+						endDate: '1990-02-08T00:00:00',
+						durationYears: 0.017,
+					},
+				],
+			},
+			'sookshma',
+		);
+		const cells = dateCells(el);
+		expect(cells[0]).not.toBe('1990 - 1990');
+		// Distinct rows must read distinctly.
+		expect(cells[0]).not.toBe(cells[1]);
+		expect(cells[0]).toContain('Jan');
+		el.remove();
+	});
+});

bunfig.toml

@@ -198,6 +198,34 @@ async function main() {
 				},
 			}),
 		),
+		// The two deeper levels share the sub layout but carry a different parent
+		// shape and level label, so a shared sample would never exercise them.
+		run('dasha-antara', () =>
+			roxy.vedicAstrology.getPratyantardashas({
+				path: { mahadasha: 'Venus', antardasha: 'Saturn' },
+				body: {
+					date: PERSON1.date,
+					time: PERSON1.time,
+					latitude: PERSON1.latitude,
+					longitude: PERSON1.longitude,
+				},
+			}),
+		),
+		run('dasha-sookshma', () =>
+			roxy.vedicAstrology.getSookshmaDashas({
+				path: {
+					mahadasha: 'Venus',
+					antardasha: 'Saturn',
+					pratyantardasha: 'Mercury',
+				},
+				body: {
+					date: PERSON1.date,
+					time: PERSON1.time,
+					latitude: PERSON1.latitude,
+					longitude: PERSON1.longitude,
+				},
+			}),
+		),
 		run('dosha', () =>
 			roxy.vedicAstrology.checkManglikDosha({
 				body: {