hindu-devotional-texts/src/vaar/types.ts

Hand-curated, typed, authoritative Hindu devotional content — aartis, chalisas, kathas, stotras, mantras, ashtottaras & sahasranamas, Vedic suktas, daily prayers, puja vidhi, Navratri, tirthas, the festival/ekadashi calendar, and full scriptures (Bhagavad

import type { Bilingual, Deity } from '../types.js'
import type { MantraSlug } from '../mantras/index.js'

// Vaar Devata — weekday (vaara) deity worship.
//
// Each weekday is named for a graha and carries a small bundle of traditional
// practice: a ruling colour, top offerings, the weekday mantra, a fasting/vrat
// summary — and one or more deities.
//
// **No deity is "the" deity of a day, and none is secondary.** A day's
// `deities` list is unordered in standing — list order is just a listing
// order. Some entries carry a neutral `context` chip ("North India",
// "South India / Tamil Nadu", "Maharashtra", "Shakta tradition", …) that says
// *where / in which tradition* an association holds — never *how important* it
// is. Consumers should render every deity at equal visual weight.
//
// Content-accuracy posture (verified across multiple authoritative Saptavara
// Vrat references):
//  - A day's deity that isn't in the `Deity` roster (Shani Dev, Murugan /
//    Kartikeya, Brihaspati) is named here as text only (`rosterId: null`): no
//    cross-link to per-deity content. It still appears in `deities` and is
//    weighted equally.
//  - The per-day `mantra` is the *weekday* mantra by tradition (the one
//    almanacs give for that vaara), surfaced under a "mantra for the day"
//    label — it does not designate any listed deity as primary. Four of the
//    seven match `mantras/` presets verbatim; all carry `reviewPending: true`
//    until a qualified-reviewer pass lands.
//  - No per-day Vrat Katha text in v1.

/** Graha that names the weekday. */
export type GrahaKey =
  | 'surya' // Sun · Ravivar
  | 'chandra' // Moon · Somvar
  | 'mangal' // Mars · Mangalvar
  | 'budh' // Mercury · Budhvar
  | 'guru' // Jupiter · Guruvar (Brihaspati)
  | 'shukra' // Venus · Shukravar
  | 'shani' // Saturn · Shanivar

/** Stable slug for the weekday (also a natural detail-route key). */
export type DayKey =
  | 'sunday'
  | 'monday'
  | 'tuesday'
  | 'wednesday'
  | 'thursday'
  | 'friday'
  | 'saturday'

export interface VaarDeity {
  /**
   * Roster slug — cross-references per-deity content (aarti/chalisa/etc.).
   * `null` for a figure referenced by name only (Shani Dev, Murugan /
   * Kartikeya, Brihaspati): no library entry, no cross-link.
   */
  rosterId: Deity | null
  name: Bilingual
  /**
   * A neutral "where / which tradition" qualifier — "North India", "South
   * India / Tamil Nadu", "Maharashtra", "Shakta tradition", … — *not* a
   * ranking. Omit when the association is pan-regional.
   */
  context?: Bilingual
  /** A short contextual line shown beneath the name. */
  note: Bilingual
}

export interface VaarMantra {
  /**
   * `mantras/` preset slug, when one matches verbatim. `null` → the consumer
   * should fall back to the `devanagari` text (no matching preset).
   */
  jaapSlug: MantraSlug | null
  devanagari: string
  iast: string
  meaning: Bilingual
  /**
   * Always `true` in v1 — these have not yet had a qualified-reviewer pass.
   * Do not flip without a scholar sign-off.
   */
  reviewPending: true
  /**
   * One-line label explaining what category of mantra this is — the seven
   * weekday mantras don't share a single form (some are deity-praṇāma, some
   * graha-bīja + deity dative, some deity-bīja + deity dative). Each line is
   * the canonical, most-recited form for that day in its tradition rather than
   * being forced into one shape; this note discloses the choice so a reader
   * can compare across days.
   */
  variantNote: Bilingual
}

export interface VaarVariantNote {
  /** Short label — "Solah Somvar", "Shakta tradition", "Peepal worship", … */
  label: Bilingual
  text: Bilingual
}

export interface VaarOffering {
  label: Bilingual
}

export interface VaarDevata {
  /** `Date.getDay()` — 0 = Sunday … 6 = Saturday. Also the `VAAR_DEVATA` index. */
  day: 0 | 1 | 2 | 3 | 4 | 5 | 6
  dayKey: DayKey
  /** Localised weekday name ("Sunday" / "रविवार"). */
  dayName: Bilingual
  /** Three-letter chip label for a day-picker. */
  dayShort: Bilingual
  /** The graha the day is named for. */
  grahaKey: GrahaKey
  /** Display name of the ruling graha ("Surya (Sun)" / "सूर्य"). */
  grahaName: Bilingual
  /** The day's deities — all of equal standing; list order is not a ranking. */
  deities: VaarDeity[]
  /** The ruling colour — content data (render only as a labelled swatch). */
  color: { hex: string; name: Bilingual }
  /** Top offerings (three for v1). */
  offerings: VaarOffering[]
  /** The weekday mantra (by tradition), under a "mantra for the day" label. */
  mantra: VaarMantra
  /** One-paragraph fasting / vrat-rule summary. No per-day Vrat Katha in v1. */
  fasting: Bilingual
  /** Labelled regional / sectarian / practice footnotes. */
  variantNotes: VaarVariantNote[]
}