Skip to Content
jenkins-ink

🧩 Components

The controlled presentation components, their props, and the helpers they share.

Every component here is controlled. None of them fetches data or calls useInput; you hold the selection index and the key handling in your own shell and pass the result down. All of them are exported from the package root.

import {
  BuildList,
  JobList,
  BuildInfo,
  LogView,
  StageTree,
  StatusBar,
  Overlay,
  Panel,
} from "@kud/jenkins-ink";

BuildList

A windowed, selectable list of builds. Each row reads #num STATE dur age, coloured by the build's status token from @kud/jenkins.

PropTypeDefaultNotes
buildsJenkinsBuild[]requiredThe full list; windowing happens inside
selectednumberrequiredIndex of the highlighted row
rowsnumberrequiredHow many rows are visible at once
emptyTextstring"No builds"Shown, muted, when builds is empty
<BuildList builds={builds} selected={selected} rows={20} />

JobList

A windowed, selectable list of jobs, each prefixed with a status dot. The row shows the job's fullName, falling back to name; a job carrying an error is shown in red with β€” ERROR after it.

PropTypeDefaultNotes
jobsJenkinsJob[]requiredThe full list
selectednumberrequiredIndex of the highlighted row
rowsnumberrequiredVisible rows
emptyTextstring"No jobs"Shown, muted, when jobs is empty

The dot comes from jobDot, which is exported on its own (see Helpers).

BuildInfo

One line of build metadata: #num STATE duration started-at, with the start time from the build's timestamp formatted by toLocaleString().

PropTypeNotes
buildJenkinsBuild | nullnull renders a muted Select a build line

Because it accepts null, you can pass the current selection straight through: <BuildInfo build={builds[selected] ?? null} />.

LogView

A deliberately plain log viewport. It lays out exactly the lines it is given; windowing, scrolling, search and colouring are yours. Lines may contain ANSI escapes, and long lines are truncated rather than wrapped into their neighbours.

PropTypeNotes
linesstring[]Already-windowed lines; may contain ANSI
widthnumberOptional fixed width for the viewport

StageTree

A pipeline drill-down across three levels: stages, then a stage's steps, then a step's log. You own the current level, the selection index and every fetch; the component renders only the level it is told to.

PropTypeNotes
level"stages" | "steps" | "log"Which level to render
stagesStageNode[]Shown at the stages level
stepsStageNode[]Shown at the steps level
stepLogstring[]Rendered through LogView at log level
selectednumberHighlighted row at the list levels
rowsnumberVisible rows at the list levels

StageNode is exported as a type: { id?: string; name?: string; status?: string; durationMillis?: number }. Its status is a Jenkins workflow status string, coloured as follows:

StatusColour token
SUCCESSsuccess
FAILED, FAILUREerror
UNSTABLEaccent
IN_PROGRESS, RUNNINGwarning
ABORTEDinfo
anything elsemuted

Empty lists read No stages (not a pipeline build?) and No steps; a node without a name reads (unnamed).

Chrome

Two layout pieces used by the assembled grid, exported for hosts that want the same look.

StatusBar is a full-width, round-bordered bar three rows high, with context on the left and state on the right. Props: left: string, right: string (omitted when empty), width: number.

Overlay replaces the body with a centred, round-bordered box and a bold title, used for help and artefact lists. Props: title: string, color: string, width: number, height: number, children. The inner box is capped at 100 columns.

Panel is re-exported unchanged from @kud/ink-ui, so a host can frame these components without a second import.

Helpers

windowSlice(items, selected, rows) returns { items, offset }: the visible slice of a list that keeps selected in view, centred when it can be, plus the index of the first visible item. Every list component above scrolls through it, so a custom list built on it will scroll identically. It holds no state.

statusColor maps each BuildStatusToken from @kud/jenkins to an @kud/ink-ui colour:

TokenColour
runningwarning
successsuccess
failureerror
unstableaccent
abortedinfo
unknownmuted

jobDot(color?) turns a job's Jenkins color field into { glyph, color }:

Jenkins colourGlyphColour
none (a folder)β–Έmuted
contains anime (running)◐info
starts with blue●success
starts with red●error
starts with yellow●warning
starts with aborted●muted
anything elseβ—‹muted

Putting them together

The selection lives in your shell, so the lists drop beside any other pane:

import { useState } from "react";
import { Box, useInput } from "ink";
import { BuildList, BuildInfo } from "@kud/jenkins-ink";

const Builds = ({ builds }) => {
  const [selected, setSelected] = useState(0);

  useInput((_input, key) => {
    if (key.upArrow) setSelected((s) => Math.max(0, s - 1));
    if (key.downArrow) setSelected((s) => Math.min(builds.length - 1, s + 1));
  });

  return (
    <Box flexDirection="column">
      <BuildInfo build={builds[selected] ?? null} />
      <BuildList builds={builds} selected={selected} rows={20} />
    </Box>
  );
};

If you would rather have the whole navigable grid than assemble it yourself, see JenkinsBody.