Skip to Content
jira-ink

๐ŸŽซ Issue detail

The issue screen in its two shapes, the self-fetching IssueBody and the controlled IssueDetailView, with their props, keys and data shape.

The issue screen shows one ticket: status, assignee and parent as rows, a dim facts line, then the whole ticket as one scrolling Markdown document: the description, the comments under their own heading, and the attachments as an appendix.

It comes in two shapes that draw the same thing:

ExportUse it when
IssueBodyYou have a client and an issue key and want the screen to fetch itself. Read-only.
IssueDetailViewYou already hold an IssueDetail and own the prompts behind the write verbs (move, comment, assign).

IssueBody

Hand it a client and a key; it fetches through issueDetailOf, shows a loading screen, an error message or the issue, and reads its own scroll keys until onExit.

import { createJiraClient, loadConfig } from "@kud/jira"
import { IssueBody } from "@kud/jira-ink"

const loaded = loadConfig()
if ("missing" in loaded) throw new Error(loaded.missing.join(", "))
const client = createJiraClient(loaded.config)

<IssueBody
  client={client}
  baseUrl={loaded.config.baseUrl}
  issueKey="SHOP-1234"
  onExit={() => setScreen("list")}
/>

Props

PropTypeNotes
clientJiraClientFrom @kud/jira.
baseUrlstringInstance URL; used only to build the browser link.
issueKeystringThe issue to fetch, e.g. SHOP-1234.
summarystring (optional)The summary the host already knows, so a frame carries a title before the fetch answers. The fetched one wins once it lands.
onExit() => voidCalled by the host's back key; becomes the view's onBack.
widthnumber (optional)Overrides the terminal width. Defaults to the terminal's columns, tracked on resize.
heightnumber (optional)Overrides the terminal height. Defaults to the terminal's rows.
framesame as IssueDetailView's frameThe host's chrome; see below.
themeMarkdownTheme (optional)Colours for the Markdown body.

IssueBody wires only one verb: o opens the issue in the browser (open on macOS, start on Windows, xdg-open elsewhere). Move, comment and assign are not wired, so the hint row does not offer them.

While loading, a framed IssueBody already calls frame with the key as title, the summary you passed as subtitle, and a single โŒซ back hint, so the panel stays the same through loading, error and ready.

IssueDetailView

The controlled screen. You fetch (with issueDetailOf or by hand) and pass the result in.

import { IssueDetailView, issueDetailOf } from "@kud/jira-ink"

const issue = await issueDetailOf(client, baseUrl, "SHOP-1234")

<IssueDetailView
  issue={issue}
  width={80}
  height={30}
  onBack={back}
  onTransition={transition}
  onComment={comment}
  onAssign={assign}
  onOpenBrowser={open}
/>

Props

PropTypeNotes
issueIssueDetailThe view-ready issue.
widthnumberColumns available to the body.
heightnumberRows available to the body, the host's frame excluded.
onBack() => voidCalled by the host's back key, never bound by the view itself.
onTransition() => void (optional)Bound to t, hinted as move.
onComment() => void (optional)Bound to c, hinted as comment.
onAssign() => void (optional)Bound to a, hinted as assign.
onOpenBrowser() => void (optional)Bound to o, hinted as browser.
framerender prop (optional)Hand the screen to the host's chrome in parts.
themeMarkdownTheme (optional)From @kud/ink-markdown; lets links, code and headings use the host's palette.

A verb whose handler is absent is neither bound nor hinted. A read-only host gets the same screen minus the keys it cannot honour, rather than a hint row promising t and c that do nothing.

Keys

KeyAction
โ†“ or jScroll down
โ†‘ or kScroll up
tonTransition, when given
conComment, when given
aonAssign, when given
oonOpenBrowser, when given

The โŒซ back hint is always shown, but the back key belongs to the host. Esc, โ† and โ†’ are not bound.

The frame

frame?: (parts: {
  title: string
  subtitle: string
  hints: Hint[]
  body: ReactNode
}) => ReactNode

When frame is given, the view draws neither its own title line nor its footer, so nothing appears twice. title is KEY ยท Type (the type moves up beside the key and leaves the rows), subtitle is the summary, and hints is the view's hint row. Without frame, the view draws KEY summary in bold on top and a FooterHints row at the foot.

What the body shows

  • Rows: status as a badge, type (unframed only), assignee (muted when unassigned), and parent with its key and a summary cut to 60 characters.
  • Facts line: the priority glyph and name when it is away from the default rank, then by <reporter>, the labels, the comment count and the attachment count.
  • Document: the description, then ## Comments (N), then ## Attachments (N), each attachment listed with its MIME type, size, where it came from, and the jira attachment read KEY filename command that fetches it.

The IssueDetail shape

issueDetailOf(client, baseUrl, key) returns this, with every field already a string and Atlassian Document Format already converted to Markdown:

type IssueDetail = {
  key: string;
  summary: string;
  status: string;
  type: string;
  assignee: string; // "unassigned" when empty
  reporter: string;
  labels: string[];
  priority?: string; // Jira's name, verbatim; absent when the field is off
  parent?: { key: string; summary: string };
  url: string; // `${baseUrl}/browse/${key}`
  description: string; // Markdown
  comments: { id: string; author: string; created: string; body: string }[];
  attachments: LocatedAttachment[]; // from @kud/jira
};

Missing status, type or reporter come through as โ€”.

Transitions

transitionsOf(client, key) lists the moves available from the issue's current status, for a host building its own move prompt behind onTransition:

type Transition = {
  id: string;
  name: string;
  to: { id?: string; name: string; category?: StatusCategory };
};

to carries the whole target status, id and category included, because status names are per instance and a host deciding which board tab the move lands in should not match on a name. Pair it with the board's row transition helpers.