import type { HierarchyLevel, TweakSchema } from '../index'

/** Type-only manifest contract shared by the server (builder) and the shell. */

export interface ManifestCase {
  id: string
  name: string
  /** In-app browse address, e.g. /c/button/default. */
  browseUrl: string
  /** Isolated render address, e.g. /render/button/default. */
  renderUrl: string
  /** Declared tweak schema, or null when the case takes no tweaks. */
  tweaks: TweakSchema | null
  /** Slugified ids of steps this step can transition to (flows only; else []). */
  transitions: string[]
}

export interface ManifestComponent {
  id: string
  name: string
  level: HierarchyLevel | null
  isFlow: boolean
  /** Resolved information-architecture group path (Exhibits mode); `[]` for
   *  building-block components and surfaces in the default group. */
  group: string[]
  /** Repo-relative path to the case file. */
  caseFile: string
  /** Repo-relative path to the authored usage doc, or null. */
  placardDoc: string | null
  /** For a flow these are its ordered, transitionable steps. */
  cases: ManifestCase[]
}

/** One node of the Exhibits-mode information-architecture group tree. */
export interface ManifestGroup {
  /** Display label for this group segment (config override or the segment). */
  label: string
  /** Full resolved path to this group (display segments). */
  path: string[]
  /** Collapsed by default on first load. */
  collapsed: boolean
  /** Nested child groups. */
  children: ManifestGroup[]
}

/** Top-level browse modes, in canonical (switch + landing-fallback) order:
 *  `primer` is the optional long-form reading page; `components` lists the
 *  building-block kit by level; `exhibits` lists page/flow surfaces by their
 *  information-architecture group. */
export const BROWSE_MODES = ['primer', 'components', 'exhibits'] as const
export type BrowseMode = (typeof BROWSE_MODES)[number]

export interface Manifest {
  title: string
  components: ManifestComponent[]
  /** The Exhibits-mode information-architecture group tree, ordered. Surfaces in
   *  the default group contribute no node; `[]` when there are no grouped surfaces. */
  groups: ManifestGroup[]
  /** Browse modes that have content, in canonical order (primer, components,
   *  exhibits). A mode absent here is never offered; the switch shows only when
   *  two or more are present. */
  modes: BrowseMode[]
  /** The mode the chrome lands on at `/` — the configured landing when present,
   *  else the first present mode. Always one of `modes`. A deep-linked case opens
   *  that case regardless. */
  landing: BrowseMode
  /** How flows are distinguished from pages in the Exhibits sidebar: a trailing
   *  `flow` tag (default) or a leading glyph. Resolved from `nav.flowMarker`. */
  flowMarker?: 'glyph' | 'tag'
  /** The active rendering substrate: which one is in play and what it varies
   *  over, so a machine client can enumerate and address every declared variant
   *  of every case without assuming a fixed light/dark + pixel-width set. */
  substrate: ManifestSubstrate
}

/** The active substrate, as the manifest reports it. */
export interface ManifestSubstrate {
  /** Stable substrate id (`'dom'` for the built-in default). Also the segment
   *  visual baselines are keyed under, so switching substrates cannot silently
   *  reuse another's recorded baselines. */
  id: string
  /** The axes this substrate's renderings vary over, in presentation order. */
  variants: ManifestVariantAxis[]
  /** Display labels overriding the fixed hierarchy vocabulary (e.g. presenting
   *  `page` as "Screens"). Absent keys keep Display Case own label; the
   *  taxonomy itself is identical across substrates. */
  levelLabels?: Partial<Record<string, string>>
}

/** One declared variant axis. Mirrors the substrate contract's declaration,
 *  flattened to plain data so the manifest stays a serializable index. */
export interface ManifestVariantAxis {
  id: string
  label: string
  /**
   * `'render'` — encoded in a case's render address and honored by the render
   * itself (the DOM substrate's theme). Enumerate these to address every
   * distinct rendering of a case.
   * `'stage'` — applied around an unchanged rendering (the DOM substrate's
   * viewport width); it changes presentation, not the delivered document.
   */
  kind: 'render' | 'stage'
  values: { value: string; label: string }[]
  /** The value used when an address names none. Always one of `values`. */
  default: string
}