@kud/gh-ink 0.57.1 → 0.59.0

package/dist/index.d.ts

@@ -136,32 +136,112 @@ declare const counts: (row: SidebarRow, liveLabel?: LiveLabel) => string;
  */
 declare const railCapacity: (height: number, rows: number) => number;
 /**
- * A right-hand rail of initiatives, standing beside the list.
- *
- * Label first, facts beneath, because a roadmap is read by name: nobody thinks
- * "ACC-11312", they think "the OpenSearch migration". So the label is the
- * bright line and the key drops to the facts line as what it is — a reference
- * you follow, in the secondary tier. Two lines rather than one because both are
- * load-bearing and neither survives the other being cut: words with no key
- * cannot be opened, and a key with no words cannot be read at a glance.
+ * One rail, or several stacked in one column. A host with one thing to rail —
+ * initiatives — passes the one; a host with two kinds of container passes both,
+ * and the panel draws them in order under one rule, each with its own heading.
+ * A stack rather than a second prop because the second rail needs everything
+ * the first has — a heading, a window, a cursor — and nothing more.
+ */
+type Rails = Sidebar | Sidebar[];
+/** The stack as an array, whichever shape the host chose. */
+declare const railsOf: (rails: Rails | undefined) => Sidebar[];
+/** Every row of every section in order — the space the rail's cursor moves in. */
+declare const railRowsOf: (rails: Rails | undefined) => SidebarRow[];
+/**
+ * How the rail's height is shared out down a stack. Each section takes what it
+ * needs while that fits inside an even share of what is left, so a short
+ * section hands its surplus down rather than sitting beside a stripe of blank
+ * lines while the section under it says `+4 more`. Even shares rather than
+ * first-come, because the FIRST section is the one most likely to be long, and
+ * letting it fill the column would leave the second with a heading and nothing
+ * under it — a section that is visibly there and unreadable.
+ */
+declare const railHeights: (height: number, rowCounts: number[]) => number[];
+/**
+ * A right-hand rail standing beside the list: one section, or a stack of them.
  *
  * Presentational, like every other row renderer here: it DRAWS a cursor but does
  * not own one, and it never calls `useInput`. Where the cursor is, and whether
  * the arrows are pointed at this rail at all, are the host's state — which is
- * what lets a screen with two focus regions have exactly one of them lit.
+ * what lets a screen with two focus regions have exactly one of them lit. The
+ * cursor counts across the whole stack, in `railRowsOf` order, so the host
+ * moves one number and never learns where a section boundary falls.
  */
 declare const SidePanel: ({ sidebar, liveLabel, width, height, focused, cursor, }: {
-    sidebar: Sidebar;
+    sidebar: Rails;
     liveLabel?: LiveLabel;
     /** From `railWidth`, so the list beside it can subtract the same number. */
     width?: number;
     height?: number;
     /** The arrows are pointed here, so this rail draws the cursor. */
     focused?: boolean;
-    /** Which row the cursor is on. Only drawn while `focused`. */
+    /** Which row the cursor is on, counted across every section. Only drawn while `focused`. */
     cursor?: number;
 }) => React.JSX.Element;
 
+/**
+ * One state per thing, from a closed set the strip knows how to draw. The host
+ * decides what "warn" means — an error-rate edge, a stale feed, a flaky build —
+ * and the strip only ever says it with a shape.
+ *
+ * `unknown` is a state and not the absence of one: "nothing heard from it" is
+ * a fact about the feed that a green tick would paper over, and a strip that
+ * draws an unmeasured thing as fine is the one failure it cannot afford.
+ */
+type StripState = "ok" | "warn" | "fail" | "unknown";
+type StripItem = {
+    /** The name on screen. Short — it is drawn once per item across one line. */
+    key: string;
+    state: StripState;
+    /**
+     * A second, independent alarm beside the state — a build on fire next to a
+     * service that is serving fine, say. Drawn as its own mark rather than folded
+     * into `state`, because the two answer different questions and a reader
+     * needs to see when they disagree.
+     */
+    alarm?: boolean;
+    /** Where `o` goes when this item is opened from a rail row. Unused here. */
+    url?: string;
+};
+type StatusStrip = {
+    /** What the row is a strip OF, in the host's words: `services`, say. */
+    title: string;
+    items: StripItem[];
+    /** When this snapshot was taken (ms). Drawn as an age at the end of the row. */
+    at?: number;
+};
+declare const stripGlyph: (state: StripState) => [string, string];
+declare const ageLabel: (at: number | undefined, now?: number) => string;
+/**
+ * The strip as plain text, at the width it has to fit. Exported so a test — or a
+ * host laying out its own row — can ask the same question the renderer asks.
+ *
+ * Wide: every item named with its mark, so the row reads as a roll call. Narrow:
+ * counts for what is fine, and names ONLY for what is not — the reader of a
+ * narrow terminal loses the roll call, never the failures. When even the
+ * failures do not fit, the worst few are named and the rest counted, so the
+ * row still says "and N more" rather than silently dropping the fourth fire.
+ */
+declare const stripLayout: (strip: StatusStrip, width: number, now?: number) => {
+    parts: StripItem[] | null;
+    summary: string;
+    age: string;
+};
+/**
+ * A standing single-line row, the same height across loading / absent / ready
+ * so the content below it never jumps — the same contract `CiStatusLine` keeps,
+ * and drawn in the same place, because a reader learns one row of glances.
+ */
+declare const StatusStripLine: ({ strip, label, width, now, }: {
+    /** `undefined` while the first poll is out; `null` when the host has nothing. */
+    strip: StatusStrip | null | undefined;
+    /** What to call the row before the data arrives with its own title. */
+    label?: string;
+    /** Columns the row may use. */
+    width: number;
+    now?: number;
+}) => React.JSX.Element;
+
 declare const renderMarkdown: (raw: string, width: number, fileLink?: (path: string, line?: number) => string) => StyledLine[];
 
 declare const healthDisplay: Record<Health, {
@@ -178,6 +258,14 @@ type ExtensionTarget = {
     login: string;
     onRemove?: (item: AnyItem) => void;
     showFlash?: (msg: string) => void;
+    query?: string;
+    ticketKey?: string;
+};
+type Command = {
+    id: string;
+    title: string;
+    group?: string;
+    run: () => void | Promise<void>;
 };
 interface InboxExtension {
     id: string;
@@ -187,6 +275,7 @@ interface InboxExtension {
     scope?: "item" | "global";
     drills?: AnyItem["kind"][];
     body: (onExit: () => void, target?: ExtensionTarget) => ReactNode;
+    commands?: (target: ExtensionTarget) => Command[];
 }
 
 /**
@@ -225,14 +314,14 @@ type CachedCockpit = {
      * rail left out of the file is a rail that does not exist until the next
      * refresh — `i` did nothing and the footer did not even offer it.
      */
-    sidebar?: Sidebar;
+    sidebar?: Rails;
 };
 declare const readCache: (key: string) => CachedCockpit | null;
 declare const writeCache: (key: string, data: {
     sections: Section[];
     login: string;
     budget?: InboxBudget;
-    sidebar?: Sidebar;
+    sidebar?: Rails;
 }) => void;
 
 type DetailContext = {
@@ -413,6 +502,14 @@ type CiStatusState = {
     kind: "ready";
     status: CiStatus;
 };
+type StripStatusState = {
+    kind: "loading";
+} | {
+    kind: "ready";
+    strip: StatusStrip | null;
+};
+/** What the strip SAYS, ignoring when it said it. */
+declare const stripSignature: (strip: StatusStrip | null) => string;
 declare const toCiStatusState: (status: CiStatus | null) => CiStatusState;
 declare const sameCiStatusState: (a: CiStatusState, b: CiStatusState) => boolean;
 declare const CiStatusLine: ({ state, job, }: {
@@ -437,7 +534,7 @@ declare const ActionMenu: ({ item, actions, cursor, }: {
     cursor: number;
 }) => React.JSX.Element;
 declare const signatureOf: (sections: Section[]) => string;
-declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jiraKeyRe, jiraTransitions, hasCiStatus, ciJob, ciFetcher, ciPollMs, watchPath, watchDebounceMs, watchJitterMs, extensions, tabHelp, emptyHint, liveLabel, }: {
+declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jiraKeyRe, jiraSetupHint, jiraTransitions, hasCiStatus, ciJob, ciFetcher, ciPollMs, stripFetcher, stripLabel, stripPollMs, watchPath, watchDebounceMs, watchJitterMs, extensions, tabHelp, emptyHint, liveLabel, }: {
     fetcher: () => Promise<{
         sections: Section[];
         login: string;
@@ -457,7 +554,7 @@ declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jir
          * Part of the fetch result rather than a static prop because it is data, and
          * data that goes stale the same way the rows do.
          */
-        sidebar?: Sidebar;
+        sidebar?: Rails;
     }>;
     cacheKey?: string;
     /**
@@ -475,11 +572,24 @@ declare const App: ({ fetcher, cacheKey, title, detailFor, origin, jiraBase, jir
     emptyHint?: string;
     jiraBase?: string;
     jiraKeyRe?: RegExp;
+    jiraSetupHint?: string;
     jiraTransitions?: JiraTransition[];
     hasCiStatus?: boolean;
     ciJob?: string;
     ciFetcher?: () => Promise<CiStatus | null>;
     ciPollMs?: number;
+    /**
+     * A standing status strip under the CI line — one row of things and the
+     * state each is in, polled on its own timer like the CI line and for the
+     * same reason: it is a glance at something that moves on its own schedule.
+     * Wiring a fetcher reserves the row; leaving it out draws nothing. `null`
+     * from the fetcher means "nothing configured" and is drawn as such, while a
+     * rejected poll keeps the last strip up.
+     */
+    stripFetcher?: () => Promise<StatusStrip | null>;
+    /** What to call the row before its first answer arrives with a title. */
+    stripLabel?: string;
+    stripPollMs?: number;
     /**
      * A file something else touches when it has changed GitHub on your behalf —
      * a Claude session closing an issue, a script merging a PR. Touching it makes
@@ -519,4 +629,4 @@ declare const matchesFilter: (repo: string, filter: RepoFilter) => boolean;
  */
 declare const parsePatterns: (value: string) => string[];
 
-export { type Action, ActionMenu, App, COLS, CiStatusLine, type CiStatusState, CommentsPanel, type CommentsPanelProps, type DetailContext, type ExplainSection, type ExtensionTarget, HealthPanel, type HealthPanelProps, type InboxBudget, type InboxExtension, type JiraTransition, type LiveLabel, MIN_SIDEBAR_COLS, type RepoFilter, SIDEBAR_COLS, SidePanel, type Sidebar, type SidebarRow, budgetNotice, buildActions, buildCheckoutCmd, clipboard, counts, drillCmd, explainGhAction, explainItem, fitCount, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, itermRun, jumpToRepo, jumpToRepoPane, matchesFilter, maxViewStart, moveCursor, openInTab, parsePatterns, railCapacity, railWidth, readCache, renderMarkdown, reposInSections, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, signatureOf, toCiStatusState, truncate, useActionMenu, windowCount, withHeaders, withoutItem, workCount, writeCache };
+export { type Action, ActionMenu, App, COLS, CiStatusLine, type CiStatusState, type Command, CommentsPanel, type CommentsPanelProps, type DetailContext, type ExplainSection, type ExtensionTarget, HealthPanel, type HealthPanelProps, type InboxBudget, type InboxExtension, type JiraTransition, type LiveLabel, MIN_SIDEBAR_COLS, type Rails, type RepoFilter, SIDEBAR_COLS, SidePanel, type Sidebar, type SidebarRow, type StatusStrip, StatusStripLine, type StripItem, type StripState, type StripStatusState, ageLabel, budgetNotice, buildActions, buildCheckoutCmd, clipboard, counts, drillCmd, explainGhAction, explainItem, fitCount, gapsAbove, healthColor, healthDisplay, healthGlyph, healthLegend, itermRun, jumpToRepo, jumpToRepoPane, matchesFilter, maxViewStart, moveCursor, openInTab, parsePatterns, railCapacity, railHeights, railRowsOf, railWidth, railsOf, readCache, renderMarkdown, reposInSections, resolveRepoPath, runHere, runInPane, runInPaneHorizontal, sameCiStatusState, signatureOf, stripGlyph, stripLayout, stripSignature, toCiStatusState, truncate, useActionMenu, windowCount, withHeaders, withoutItem, workCount, writeCache };