Skip to content

The agent that grows with you

feat(desktop): pass the board's tenant list to Kanban badge decorators

Tekniume04614af7bb4
diff --git a/apps/desktop/src/contrib/kanban-card-badges.test.ts b/apps/desktop/src/contrib/kanban-card-badges.test.ts
index 3154e94f216..984638cf8f4 100644
--- a/apps/desktop/src/contrib/kanban-card-badges.test.ts
+++ b/apps/desktop/src/contrib/kanban-card-badges.test.ts
@@ -9,7 +9,8 @@ import {
KANBAN_CARD_BADGE_HUES,
KANBAN_CARD_BADGE_LIMITS,
type KanbanCard,
- type KanbanCardBadgeContribution
+ type KanbanCardBadgeContribution,
+ type KanbanCardBoard
} from '@hermes/plugin-sdk'
import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -37,8 +38,8 @@ function loadPlugin(id: string, contributions: Record<string, KanbanCardBadgeCon
return unload
}
-const badgesFor = (target: KanbanCard = card) =>
- resolveKanbanCardBadges(registry.getArea(KANBAN_CARD_AREAS.badges), target)
+const badgesFor = (target: KanbanCard = card, board: KanbanCardBoard = { tenants: [] }) =>
+ resolveKanbanCardBadges(registry.getArea(KANBAN_CARD_AREAS.badges), target, board)
afterEach(() => {
loaded.splice(0).forEach(unload => unload())
@@ -84,20 +85,23 @@ describe('kanban card badges: ordering and arbitration', () => {
expect(badgesFor().map(b => b.label)).toEqual(['ok'])
})
- it('passes each decorator a frozen, minimal view of the card the host renders', () => {
- let seen: unknown
+ it('passes each decorator a frozen, minimal view of the card and its board', () => {
+ const seen: unknown[] = []
loadPlugin('peek', {
- tag: c => {
- seen = c
+ tag: (c, board) => {
+ seen.push(c, board)
return null
}
})
- badgesFor({ ...card, title: 'secret prose', body: 'more prose' } as unknown as KanbanCard)
+ badgesFor({ ...card, body: 'more prose', title: 'secret prose' } as unknown as KanbanCard, {
+ tenants: ['acme', 'globex']
+ })
- expect(seen).toEqual(card)
- expect(Object.isFrozen(seen)).toBe(true)
+ expect(seen).toEqual([card, { tenants: ['acme', 'globex'] }])
+ expect(seen.every(view => Object.isFrozen(view))).toBe(true)
+ expect(Object.isFrozen((seen[1] as { tenants: string[] }).tenants)).toBe(true)
})
})
diff --git a/apps/desktop/src/contrib/kanban-card-badges.tsx b/apps/desktop/src/contrib/kanban-card-badges.tsx
index b5c40b4cd53..051725c1c12 100644
--- a/apps/desktop/src/contrib/kanban-card-badges.tsx
+++ b/apps/desktop/src/contrib/kanban-card-badges.tsx
@@ -58,6 +58,13 @@ export interface KanbanCard {
readonly tenant: null | string
}
+/** Board-level facts every card on the board shares. Frozen. */
+export interface KanbanCardBoard {
+ /** Every tenant on the board (the list its filter menu offers), so a plugin
+ * can give each one a distinct color instead of hashing blind. */
+ readonly tenants: readonly string[]
+}
+
export interface KanbanCardBadge {
/** Plain text, shown as-is (no markup). Trimmed; control and bidi
* characters removed; shortened past `labelChars`. */
@@ -73,7 +80,10 @@ export interface KanbanCardBadge {
* badges, or `null` for cards you have nothing to say about. Keep it a pure
* lookup: it runs while the board renders. */
export interface KanbanCardBadgeContribution {
- decorate: (card: KanbanCard) => KanbanCardBadge | null | readonly KanbanCardBadge[] | undefined
+ decorate: (
+ card: KanbanCard,
+ board: KanbanCardBoard
+ ) => KanbanCardBadge | null | readonly KanbanCardBadge[] | undefined
}
export interface ResolvedKanbanCardBadge {
@@ -146,7 +156,8 @@ const warned = new Set<string>()
* and a decorator that throws or answers garbage simply contributes nothing. */
export function resolveKanbanCardBadges(
contributions: readonly Contribution[],
- card: KanbanCard
+ card: KanbanCard,
+ board: KanbanCardBoard
): ResolvedKanbanCardBadge[] {
const view: KanbanCard = Object.freeze({
assignee: card.assignee ?? null,
@@ -155,6 +166,8 @@ export function resolveKanbanCardBadges(
tenant: card.tenant ?? null
})
+ const boardView: KanbanCardBoard = Object.freeze({ tenants: Object.freeze([...board.tenants]) })
+
const used = new Map<string, number>()
const badges: ResolvedKanbanCardBadge[] = []
@@ -167,7 +180,11 @@ export function resolveKanbanCardBadges(
}
try {
- const answer = (contribution.data as Partial<KanbanCardBadgeContribution> | undefined)?.decorate?.(view)
+ const answer = (contribution.data as Partial<KanbanCardBadgeContribution> | undefined)?.decorate?.(
+ view,
+ boardView
+ )
+
const list: readonly unknown[] = Array.isArray(answer) ? answer : answer ? [answer] : []
for (let index = 0; index < list.length && count < KANBAN_CARD_BADGE_LIMITS.perPlugin; index += 1) {
@@ -191,9 +208,10 @@ export function resolveKanbanCardBadges(
return badges
}
-/** The fields of a board task the badge row reads. */
+/** The fields of a board task the badge row reads, and the board's tenants. */
export interface KanbanCardBadgesProps {
card: { assignee?: null | string; id: string; status: string; tenant?: null | string }
+ tenants: readonly string[]
}
const HUE_STYLE =
@@ -214,14 +232,14 @@ const pluginName = (source: string, records: ReturnType<typeof $pluginRecords.ge
/** The badge row a Kanban card renders above its title. Renders nothing when
* no plugin has a badge for this card, so an unused area costs no space. */
-export function KanbanCardBadges({ card }: KanbanCardBadgesProps): null | ReactElement {
+export function KanbanCardBadges({ card, tenants }: KanbanCardBadgesProps): null | ReactElement {
const contributions = useContributions(KANBAN_CARD_AREAS.badges)
const records = useStore($pluginRecords)
const { assignee = null, id, status, tenant = null } = card
const badges = useMemo(
- () => resolveKanbanCardBadges(contributions, { assignee, id, status, tenant }),
- [assignee, contributions, id, status, tenant]
+ () => resolveKanbanCardBadges(contributions, { assignee, id, status, tenant }, { tenants }),
+ [assignee, contributions, id, status, tenant, tenants]
)
if (badges.length === 0) {
diff --git a/apps/desktop/src/plugins/kanban/board.tsx b/apps/desktop/src/plugins/kanban/board.tsx
index c02153fdf24..be4c98ff4a8 100644
--- a/apps/desktop/src/plugins/kanban/board.tsx
+++ b/apps/desktop/src/plugins/kanban/board.tsx
@@ -255,7 +255,8 @@ function Card({
onOpen,
onToggleSelect,
selected,
- task
+ task,
+ tenants
}: {
columns: string[]
onDelete: (id: string) => void
@@ -264,6 +265,7 @@ function Card({
onToggleSelect: (id: string) => void
selected: boolean
task: KanbanTask
+ tenants: readonly string[]
}) {
const k = useKanban()
const [dragging, setDragging] = useState(false)
@@ -305,7 +307,7 @@ function Card({
{(arc === 'running' || arc === 'stale') && !dragging && !selected && (
<span aria-hidden className={cn('kanban-arc', arc === 'stale' && 'kanban-arc--stale')} />
)}
- <KanbanCardBadges card={task} />
+ <KanbanCardBadges card={task} tenants={tenants} />
<span className="line-clamp-2 text-[0.8125rem] font-medium leading-snug text-foreground">
{task.title || task.id}
</span>
@@ -356,7 +358,8 @@ function Column({
onOpen,
onToggle,
onToggleSelect,
- selected
+ selected,
+ tenants
}: {
collapsed: boolean
column: { name: string; tasks: KanbanTask[] }
@@ -369,6 +372,7 @@ function Column({
onToggle: () => void
onToggleSelect: (id: string) => void
selected: ReadonlySet<string>
+ tenants: readonly string[]
}) {
const k = useKanban()
const [over, setOver] = useState(false)
@@ -492,6 +496,7 @@ function Column({
onToggleSelect={onToggleSelect}
selected={selected.has(task.id)}
task={task}
+ tenants={tenants}
/>
))}
</div>
@@ -506,6 +511,7 @@ function Column({
onToggleSelect={onToggleSelect}
selected={selected.has(task.id)}
task={task}
+ tenants={tenants}
/>
))}
{/* Jira-style lane add — dashed, faded in on lane hover. Opacity (not
@@ -1424,6 +1430,7 @@ export function KanbanBoardPage() {
onToggle={() => toggleLane(col.name, auto)}
onToggleSelect={toggleSelect}
selected={selected}
+ tenants={filtered.tenants}
/>
)
})}
diff --git a/apps/desktop/src/plugins/kanban/card-badges.test.tsx b/apps/desktop/src/plugins/kanban/card-badges.test.tsx
index 43b9768e768..4d68a5b9cad 100644
--- a/apps/desktop/src/plugins/kanban/card-badges.test.tsx
+++ b/apps/desktop/src/plugins/kanban/card-badges.test.tsx
@@ -39,7 +39,7 @@ vi.mock('./api', async importOriginal => ({
],
latest_event_id: 0,
now: 0,
- tenants: ['acme']
+ tenants: ['acme', 'globex']
})),
fetchOrchestration: vi.fn(async () => ({ default_assignee: '' })),
fetchProfiles: vi.fn(async () => ({ profiles: [] }))
@@ -47,6 +47,7 @@ vi.mock('./api', async importOriginal => ({
let disposeLocales: () => void = () => undefined
let unloadPlugin: () => void = () => undefined
+let seenTenants: string[] = []
beforeEach(() => {
disposeLocales = registerPluginLocales('kanban', KANBAN_LOCALES)
@@ -57,8 +58,16 @@ beforeEach(() => {
ctx.register({
area: KANBAN_CARD_AREAS.badges,
data: {
- decorate: ({ tenant }) =>
- tenant ? [{ label: tenant, tone: 'blue', tooltip: `Tenant ${tenant}` }, { label: '<b>bold</b>' }] : null
+ decorate: ({ tenant }, { tenants }) => {
+ seenTenants = [...tenants]
+
+ return tenant
+ ? [
+ { label: tenant, tone: 'blue', tooltip: `Tenant ${tenant} of ${tenants.length}` },
+ { label: '<b>bold</b>' }
+ ]
+ : null
+ }
} satisfies KanbanCardBadgeContribution,
id: 'tenant'
})
@@ -90,6 +99,8 @@ describe('kanban board: plugin card badges', () => {
const badge = acme.getByText('acme')
expect(badge.closest('[data-slot="kanban-card-badge"]')?.getAttribute('data-tone')).toBe('blue')
+ // The board's tenant list reaches the decorator (collision-free colors need it).
+ expect(seenTenants).toEqual(['acme', 'globex'])
// Markup-looking text stays text: no element is created from a label.
expect(acme.getByText('<b>bold</b>').querySelector('b')).toBeNull()
expect(tileOf('Untenanted chore').querySelector('[data-slot="kanban-card-badges"]')).toBeNull()
diff --git a/apps/desktop/src/sdk/areas.ts b/apps/desktop/src/sdk/areas.ts
index 21a3307c8ec..be025ae186f 100644
--- a/apps/desktop/src/sdk/areas.ts
+++ b/apps/desktop/src/sdk/areas.ts
@@ -10,8 +10,8 @@ export const STATUSBAR_AREAS = { left: 'statusBar.left', right: 'statusBar.right
* should exist only while a page is up go to `WORKSPACE_PAGE_HEADER_AREA`. */
export const TITLEBAR_AREAS = { center: 'titleBar.center', left: 'titleBar.left', right: 'titleBar.right' } as const
/** Per-card labels on Kanban tiles: register a `KANBAN_CARD_AREAS.badges`
- * data contribution whose `decorate({ id, status, tenant, assignee })`
- * returns `{ label, tone?, tooltip? }` (or a few, or `null`). Core paints
+ * data contribution whose `decorate({ id, status, tenant, assignee },
+ * { tenants })` returns `{ label, tone?, tooltip? }` (or a few, or `null`). Core paints
* them as text chips in the card's badge row, ordered by plugin id, capped
* per plugin, removed with the plugin. Never touch the board's markup.
* `KanbanCardBadges` is the row the board itself renders. */
@@ -24,5 +24,6 @@ export {
type KanbanCardBadgeContribution,
type KanbanCardBadgeHue,
KanbanCardBadges,
- type KanbanCardBadgeTone
+ type KanbanCardBadgeTone,
+ type KanbanCardBoard
} from '@/contrib/kanban-card-badges'
diff --git a/website/docs/developer-guide/desktop-plugin-sdk.md b/website/docs/developer-guide/desktop-plugin-sdk.md
index ef5db00471e..28c84ca79e6 100644
--- a/website/docs/developer-guide/desktop-plugin-sdk.md
+++ b/website/docs/developer-guide/desktop-plugin-sdk.md
@@ -781,6 +781,9 @@ interface KanbanCard { // frozen; identity and routing fields only
tenant: string | null
assignee: string | null
}
+interface KanbanCardBoard { // frozen; shared by every card on the board
+ tenants: readonly string[] // every tenant on the board (its filter menu's list)
+}
interface KanbanCardBadge {
label: string // plain text
tone?: KanbanCardBadgeTone // 'neutral' (default) or one of KANBAN_CARD_BADGE_HUES
@@ -791,16 +794,20 @@ ctx.register({
area: KANBAN_CARD_AREAS.badges,
id: 'tenant',
data: {
- decorate: ({ tenant }) =>
- tenant ? { label: tenant, tone: KANBAN_CARD_BADGE_HUES[hash(tenant) % 12], tooltip: `Tenant: ${tenant}` } : null
+ // `tenants` lets you give each tenant on the board its own hue instead of
+ // hashing blind (two tenants can hash to the same one).
+ decorate: ({ tenant }, { tenants }) =>
+ tenant
+ ? { label: tenant, tone: KANBAN_CARD_BADGE_HUES[distinctIndex(tenant, tenants) % 12], tooltip: `Tenant: ${tenant}` }
+ : null
} satisfies KanbanCardBadgeContribution
})
```
-`decorate` may return one badge, an array, or `null` for cards it has nothing
-to say about. The card view carries no prose (title, body, summaries,
+`decorate(card, board)` may return one badge, an array, or `null` for cards it
+has nothing to say about. The card view carries no prose (title, body, summaries,
comments, run output); look up anything else you need by `id` in your own data
-(`ctx.rest` to your backend, `ctx.storage`).
+(`ctx.rest` to your backend, `ctx.storage`). Both views are frozen.
**What the board accepts** (`KANBAN_CARD_BADGE_LIMITS`):
@@ -826,9 +833,9 @@ contribution id, then the order `decorate` returned them. A contribution's
A decorator that **throws** contributes nothing (logged once) and the rest of
the row still paints.
-**Updates and teardown.** `decorate()` re-runs when the registry changes or
-when the card's id, status, tenant or assignee changes, so keep it a pure
-lookup. When your own data changes (a user pins a new color in your settings
+**Updates and teardown.** `decorate()` re-runs when the registry changes,
+when the card's id, status, tenant or assignee changes, or when the board's
+tenant list changes, so keep it a pure lookup. When your own data changes (a user pins a new color in your settings
page), call `ctx.register` again with the same `id`: the new registration
replaces the old one and the board repaints. Keep the latest disposer; the
first one would remove the replacement. On disable, reload or unload, the
@@ -838,7 +845,8 @@ nothing to undo in `ctx.onDispose`.
**Migrating a DOM-decorating plugin** (kanban-tenant-labels): delete the route
poll, the `MutationObserver`, the tile matching, the inserted `<span>` and the
reads of the Kanban plugin's query cache. The whole decoration becomes the
-`ctx.register` call above, with the plugin's color pins mapped to
+`ctx.register` call above. Its collision-free assignment runs on
+`board.tenants` instead of the query-cache snapshot, and its color pins map to
`KANBAN_CARD_BADGE_HUES` (its twelve hues are the same `hsl(n×30 68% 58%)`
set, in the same order).
@@ -2117,7 +2125,7 @@ pipeline as a trust boundary.
| Host | `host` (`.state.*`, `.settings`, `.notify`, `.notifyError`, `.navigate`, `.onEvent`, `.logs`, `.status`, `.restartGateway`, `.request`, `.composer`, `.sessions`, `.skills`, `.toolsets`, `.profiles`, `.pluginDecisions`) |
| Plugin contract | `HermesPlugin`, `PluginContext`, `PluginContribution`, `PluginStorage`, `PluginOs`, `PluginPet`, `PetSayOptions`, `PetMessageTone`, `PluginAppActionId`, `PluginAppActionInfo`, `PluginRunActionResult`, `PLUGIN_APP_ACTIONS`, `PluginRestOptions`, `PluginNativeNotificationInput`, `PluginNotificationAction`, `HermesOpenTarget`, `Contribution` |
| Area constants | `PANES_AREA`, `ROUTES_AREA`, `SIDEBAR_NAV_AREA`, `STATUSBAR_AREAS`, `TITLEBAR_AREAS`, `WORKSPACE_PAGE_HEADER_AREA`, `PALETTE_AREA`, `KEYBINDS_AREA`, `THEMES_AREA`, `COMPOSER_AREAS`, `MODEL_MENU_ROW_AREA`, `KANBAN_CARD_AREAS`, `SESSION_ROW_AREAS`, `SIDEBAR_NAV_PREFS_AREA`, `APPEARANCE_AREAS`, `SETTINGS_PLUGINS_AREA` |
-| Area payloads | `PluginSettingsPage`, `PluginSettingsSubpage` (+ `pluginSettingsHref`), `RouteContribution`, `SidebarNavContribution`, `StatusbarItem`, `TitlebarTool`, `PaletteContribution`, `KeybindContribution`, `ComposerMiddleware`, `ComposerAttachmentProvider`, `SessionRowSlotContribution`, `KanbanCardBadgeContribution` (+ `KanbanCard`, `KanbanCardBadge`, `KanbanCardBadgeTone`, `KANBAN_CARD_BADGE_HUES`, `KANBAN_CARD_BADGE_LIMITS`), `SidebarNavPrefsContribution` |
+| Area payloads | `PluginSettingsPage`, `PluginSettingsSubpage` (+ `pluginSettingsHref`), `RouteContribution`, `SidebarNavContribution`, `StatusbarItem`, `TitlebarTool`, `PaletteContribution`, `KeybindContribution`, `ComposerMiddleware`, `ComposerAttachmentProvider`, `SessionRowSlotContribution`, `KanbanCardBadgeContribution` (+ `KanbanCard`, `KanbanCardBoard`, `KanbanCardBadge`, `KanbanCardBadgeTone`, `KANBAN_CARD_BADGE_HUES`, `KANBAN_CARD_BADGE_LIMITS`), `SidebarNavPrefsContribution` |
| React / state | `useValue`, `atom`, `computed`, `useQuery`, `useMutation`, `useQueryClient`, `queryClient`, `Contribute`, `WorkspacePageHeaderControl` |
| Theming | `useTheme`, `requestTheme`, `setAccentOverride`, `$accentOverride`, `retintTheme`, `themeHue`, `DesktopTheme`, `DesktopThemeColors`, plus OKLCH math (`hexToOklch`, `oklchToHex`, `oklchToSrgb255`, `mixOklab`, `maxChroma`, `hueDelta`, `normalizeHex`) and sRGB measures (`contrastRatio` — `number | null`, null for unparseable input — `readableOn`) |
| UI kit | `Button`, `Input`, `Textarea`, `Select*`, `Switch`, `Checkbox`, `SegmentedControl`, `Tabs*`, `Dialog*`, `ConfirmDialog`, `DropdownMenu*`, `ContextMenu*`, `Popover*`, `Tip`/`Tooltip*`, `Badge`, `Kbd`/`KbdGroup`, `SearchField`, `ScrollArea`, `Separator`, `Skeleton`, `GlyphSpinner`, `Loader`, `EmptyState`, `ErrorState`, `CopyButton`, `StatusDot`, `LogView`, `Codicon`, `DecodeText`, `SandboxedFrame` |