Data

9 components · 5 formatters

The components that put machine facts on screen: meters, trend lines, stat tiles, code, two tables, their pager, and the formatters that turn a raw byte count or timestamp into something readable. Every specimen carries the states a real control plane hits — a table with no rows, a series that is flat, a bar over its critical threshold.

Regression watch

One shipped bug is pinned here: a colour variant that silently lost its halo because the CSS behind it was invalid.

NkUsageBar

color="primary" glow
color · height=lg · value=72same size, same value — only the colour differs
primary
emerald
blue
amber
red

Where to look: the track sets overflow-hidden, so the halo is clipped to the track box and only shows where it falls inside it — the soft bleed just right of the fill edge, into the empty 28% of the bar.

Correct
All five bars below are height="lg" at value=72, so only the colour differs. Every one paints an 8px halo around its fill, primary included — the class is now shadow-[0_0_8px_hsl(var(--primary)/0.3)], which is valid CSS. Measured in this app, the primary halo is the wrong colour. The playground defines --primary as an OKLCH triplet (0.65 0.18 200 in dark), so hsl() reads it as hue 0.65, saturation 0.18%, lightness 200% clamped to 100% — getComputedStyle returns rgba(255, 255, 255, 0.3). The fill is teal, the halo is white. It matches the fill only where --primary is an HSL triplet: Hub, admin, account, auth, status.
Regressed
The glow used to be written rgba(oklch(var(--primary))/0.3), which nests one colour function inside another and is not valid CSS, so the whole declaration was dropped. primary was the only one of the five with a flat, halo-free edge while emerald, blue, amber and red all had one.

Meters and trends

Two ways to read a number over time: a single bounded value, or a series compressed into a line.

NkUsageBar

5 colours · 4 heights

A 0–100 meter. value is clamped into range, so a telemetry spike over 100 never overflows the track.

color="auto" + thresholdsthresholds={{ warning: 60, critical: 85 }}
under warning → green42%
warning < v ≤ critical → amber72%
over critical → red93%
heightxs · sm (default) · md · lg
xs
sm
md
lg
color as a classan unmapped string is used verbatim as the fill class
edge values0 and 100

NkSparkline

3 sizes + custom

An inline SVG trend line with an area fill. Hovering a point shows its value when interactive is on (the default). It reads its scale from the same chart-geometry module as the six NkChart* components, so a hole breaks the line, a flat line is centred whatever it is flat at, and one reading is a dot.
color is opt-in. Omit it and the mark themes from tone through NK_CHART_MARK with no <defs> at all; give it and the literal goes verbatim into stroke under a useId-derived gradient id, for a series whose colour carries a threshold rather than a theme. The specimens here pass a literal so the sizes can be told apart; everywhere else, leave it off.

sizesm 80×24 · md 120×40 · lg 200×60
sm · cpu %
md · rss
lg · 5xx
size="custom" + width/heightthe only way to set an explicit box
interactive={false}no hover readout, no pointer handlers
flat seriesmin === max is handled, not divided by zero
one readinga centred dot, not an empty box
A lone reading is a dot at the middle of the viewBox — a zero-length subpath painted by stroke-linecap="round". It used to return null below two points and the stage was genuinely empty, which is the state every chart is in on the first frame after a bridge reconnect.

Stat tiles

NkStatsGrid is the responsive frame; NkStatsCard is one reading inside it. The card takes children, which is how a sparkline gets under a number without a second wrapper.

NkStatsGrid · NkStatsCard

tiles

columns is the desktop count; the grid always collapses to one column on mobile. trend renders a delta with its own label, and isPositive decides the direction — not the sign of the number.

columns1 · 2 · 3 · 4
icon · subtitle · trend · childrenthe last two tiles nest a sparkline and a usage bar

Services up

9/9

production · fra1

Deploys today

14

+27%

2 rolled back

CPU pressure

71%

-9%

svc-events is the hot one

Volume usage

612 GB

of 1 TB provisioned

colorprimary · blue · amber · emerald · rose

primary

—

icon tint only

blue

—

icon tint only

amber

—

icon tint only

emerald

—

icon tint only

rose

—

icon tint only

Code

One block for config and command output. It scrolls horizontally inside its own border, so a long line never widens the page.

NkCodeBlock

title · line numbers

The header shows title, falling back to language. The copy button writes to the clipboard and flips to a tick for 2s; where the clipboard is unavailable (no HTTPS, permission denied) it fails quietly rather than throwing.

title + showLineNumbers
nanokit.yml
1services:
2 gateway:
3 image: caddy:2
4 ports:
5 - "80:8080"
6 - "443:8443"
7 depends_on: [auth]
8 auth:
9 path: ./apps/api-auth
10 buildProject: api-auth
11 env:
12 DATABASE_URL: db://kama-pg
language onlyno title — the language is the header
bash
nkapp deploy -e production
Scope: 2/9 services (gateway, auth) — changed: gateway (source)
✔ gateway reconciled 1.9s
✔ auth reconciled 2.4s
Deployed in 11.7s

NkCodeBlock

overflow

A single line longer than the container: the block scrolls on its own x axis and the page does not.

one long line
resolved command
nkapp deploy -e production --ssh root@187.124.188.112 -p 22 --service api-gateway --no-dns --env-file .env.production --override-env -y
single tokena connection string with no spaces
text
postgres://app:9f2c41e8b3a7d05c1f6e2a94b8c3d71f@db.production.internal:5432/kama?sslmode=require

Tables

Two tables ship, and they are not a replacement pair. NkTable is the react-aria grid: it sorts, selects, virtualizes and is operable from the keyboard. NkDataTable is a plain table element with column behaviour bolted on; it keeps ~19 consumers and the one capability NkTable does not have.

NkTable · NkDataTable

which one

Reach for NkTable on anything new. Stay on NkDataTable only for a view that needs pointer drag-to-reorder columns — react-aria's drag primitives reorder collection items, not columns, so NkTable ships the accessible half (Ctrl/Cmd + ←/→ on a focused header) and nothing else. This matrix is itself an NkTable.

CapabilityNkTableNkDataTable
Sorts the rowsYes, uncontrolledNo — emits a descriptor
Controlled sort (server-side)YesYes
Row selectionYesNo
Keyboard grid navigationYesNo
aria-sort on the headerYesNo
Row virtualizationYesNo
Loading / error statesYesEmpty only
Column resizeYes, keyboard-operableYes, pointer only
Column reorder, keyboardYes — Ctrl/Cmd + ←/→No
Column reorder, pointer dragNoYes
Production call sites0~19

NkTable

sorting · the contract

The difference the two tables below make visible: with defaultSortDescriptor the table sorts the rows; with sortDescriptor it deliberately never reorders and only reports the next descriptor, which is what a server-sorted view needs. Click Node on both and watch only the left one move.

defaultSortDescriptoruncontrolled — the table owns the state AND reorders
NodeOwnerRegionStatusLast seen
node-1Erinsfo3
Deploying
2026-09-24 08:20
node-2Carolunassigned
Degraded
2026-09-23 22:41
node-3Gracesgp1
Degraded
2026-09-24 06:05
node-7heidifra1
Failed
2026-07-04 03:17
node-9aliceams3
Failed
2026-09-24 07:58
node-10Bobfra1
Healthy
2026-09-22 09:14
node-11davenyc3
Healthy
2026-08-30 11:02
node-20frankunassigned
Healthy
2026-09-19 16:30
descriptornode ascending
row orderfollows the descriptor
sortDescriptor + onSortChangecontrolled — the parent's array is authoritative
NodeOwnerRegionStatusLast seen
node-10Bobfra1
Healthy
2026-09-22 09:14
node-9aliceams3
Failed
2026-09-24 07:58
node-2Carolunassigned
Degraded
2026-09-23 22:41
node-11davenyc3
Healthy
2026-08-30 11:02
node-1Erinsfo3
Deploying
2026-09-24 08:20
node-20frankunassigned
Healthy
2026-09-19 16:30
node-3Gracesgp1
Degraded
2026-09-24 06:05
node-7heidifra1
Failed
2026-07-04 03:17
descriptornode ascending
row ordernever moves

The fixture is built to expose the comparator. Sorting Node ascending puts node-9 before node-10 (the collator runs numeric: true), Owner interleaves alice and Bob rather than sorting every capital first (sensitivity: 'base'), the two unassigned regions sink to the bottom in both directions, and Status orders by severity because the column declares a sortKey — a badge is a React node and cannot be compared.

NkTable

the workbench

Selection is real here, not a declared-and-ignored prop. node-7 is in disabledKeys, so it takes no checkbox and no row action. Focus a header and press Ctrl/Cmd + ←/→ to move a column; drag a header's right edge, or focus the handle and use the arrows, to resize.

density
Columns are reorderable. Focus a column header and press Control or Command plus Left or Right arrow to move it.
NodeOwnerRegionStatusLast seen
node-10Bobfra1
Healthy
2026-09-22 09:14
node-9aliceams3
Failed
2026-09-24 07:58
node-2Carolunassigned
Degraded
2026-09-23 22:41
node-11davenyc3
Healthy
2026-08-30 11:02
node-1Erinsfo3
Deploying
2026-09-24 08:20
node-20frankunassigned
Healthy
2026-09-19 16:30
node-3Gracesgp1
Degraded
2026-09-24 06:05
node-7heidifra1
Failed
2026-07-04 03:17
selectedKeys2 of 8
disabledKeysn8 — node-7, not selectable
columnOrdernode · owner · region · status · lastSeen
onColumnResizeEnddrag a header edge
onRowActionpress Enter on a row

NkTable

virtualized · 2,000 rows

virtualized renders only the visible rows and needs a bounded height — here fillHeight inside a 420px box. react-aria positions each row from the density's declared rowHeight (40 / 56 / 68px), which is not the height the cell padding produces. The readout below measures both, live, so the difference is a number rather than a claim.

density
2,000 rows · scroll to the end, then re-measure
Node
node-0001
the same columns, same density, not virtualizedthe control sample — this is what the CSS alone produces
NodeRegionOwnerImageLayer sizeCPU
node-0001fra1a.rossiregistry.nk/app:400004 KiB0%
node-0002ams3k.chenregistry.nk/app:4000d11 MiB17%
node-0003nyc3m.duboisregistry.nk/app:4001a22 MiB34%
node-0004sfo3p.novakregistry.nk/app:4002733 MiB51%
node-0005sgp1s.haddadregistry.nk/app:4003444 MiB68%
node-0006fra1a.rossiregistry.nk/app:4004155 MiB85%
declared rowHeight—
positioned box—
row-to-row pitch—
gap between rows—
accumulated over 2,000 rows—
inner role="row"—
in-flow row (control)—
declared − in-flow—
content height—
declared × rows + header—
row separator · virtualized—
row separator · in flow—
column rule · virtualized—
column rule · in flow—
rows rendered—

The declared height wins, and nothing accumulates. react-aria wraps every row in a positioned div carrying contain: size layout style, so the row cannot size itself: the box is exactly 40 / 56 / 68px, the pitch equals the box, and the content height comes out at declared × 2,000 + header to the pixel. The drift against the in-flow control (38 / 54 / 62px, so +2 / +2 / +6) lands as slack under the text inside each row, never as a gap between rows. Compare the two tables above at comfortable — the virtualized rows are visibly taller and sit higher in their band.

The separators are the real casualty. NkTableRow ends in last:border-b-0 and NkTableCell in last:border-r-0. Under a virtualizer each row and each cell is the only child of its own wrapper, so every one of them matches :last-child and drops its border. The readout measures it: the virtualized table paints no row separators and no column rules, while the control sample paints both. It is a library issue, recorded here rather than worked around on this page.

Cells here are text only and the control sample uses the same columns, so the two measurements are comparable — a badge carries its own line box and would move the number being measured.

If this table shows a single row, you are on the dev server. Under next dev the virtualizer settles on a zero-area visible rectangle and renders exactly one row and one column; the numbers above then read —. The same build served by next start renders and measures correctly, which is where every figure quoted here was taken.

NkTable

loading · empty · error

Three states the old table had no answer for. isLoading draws skeleton rows and marks the grid aria-busy instead of swapping the whole table for a spinner, so the header and the column widths hold still across a fetch.

state
NodeOwnerRegionStatusLast seen
grid aria-busytrue
headerstays mounted in every state — no layout jump

NkDataTable

controlled sort

Sorting is controlled: the header only becomes clickable when a column sets allowsSorting and the table gets an onSortChange. The table never sorts the rows itself — the parent owns the comparator, which is why the readout below tracks the descriptor.

Click a header to sort, drag a header to reorder, drag its right edge to resize. Both axes scroll inside the box.

Sort: unsorted

Columns are reorderable. Drag a column header to move it, or focus a header and press Control or Command plus Left or Right arrow.
ID
Service
Image
Status
Region
Replicas
CPU
Memory
Last Deployed
Owner
1001svc-gatewayregistry.nk/app:9a20
Healthy
fra11/1
12%
128 MB3m agoa.rossi
1002svc-authregistry.nk/app:9a27
Healthy
ams32/2
34%
412 MB18m agok.chen
1003svc-billingregistry.nk/app:9a2e
Healthy
nyc33/3
8%
96 MB47m agom.dubois
1004svc-eventsregistry.nk/app:9a35
Degraded
sfo33/4
71%
780 MB2h agop.novak
1005svc-runtimeregistry.nk/app:9a3c
Deploying
sgp11/1
55%
512 MB6m agos.haddad
1006svc-orchestratorregistry.nk/app:9a43
Failed
fra10/2
22%
220 MB4h agoa.rossi
1007svc-logsregistry.nk/app:9a4a
Healthy
ams33/3
91%
1024 MB15m agok.chen
1008svc-hubregistry.nk/app:9a51
Healthy
nyc34/4
47%
356 MB1h agom.dubois
1009svc-gatewayregistry.nk/app:9a58
Healthy
sfo31/1
19%
180 MB9m agop.novak
1010svc-authregistry.nk/app:9a5f
Degraded
sgp11/2
63%
640 MB5h agos.haddad
1011svc-billingregistry.nk/app:9a66
Deploying
fra13/3
5%
72 MB2m agoa.rossi
1012svc-eventsregistry.nk/app:9a6d
Failed
ams30/4
38%
300 MB1h agok.chen
1013svc-runtimeregistry.nk/app:9a74
Healthy
nyc31/1
82%
890 MB27m agom.dubois
1014svc-orchestratorregistry.nk/app:9a7b
Healthy
sfo32/2
27%
240 MB8h agop.novak
1015svc-logsregistry.nk/app:9a82
Healthy
sgp13/3
14%
150 MB12m agos.haddad
1016svc-hubregistry.nk/app:9a89
Degraded
fra13/4
49%
480 MB3h agoa.rossi

Row selection is a documented gap, not an oversight. selectionMode, selectedKeys and onSelectionChange were declared but never read, so passing them silently did nothing; they have been removed from the props so a consumer now gets a compile error instead of a checkbox column that never appears. Selection has since shipped on NkTable — it is the specimen four slots above this one.

NkDataTable

height · empty

Two ways to bound the height. maxHeight caps the box and scrolls the body under a sticky header; fillHeight(used above) takes the parent's height instead, forces the sticky header on, and ignores maxHeight.

stickyHeader + maxHeight="240px"scroll the rows — the header stays
Service
Region
Status
Memory
svc-gatewayfra1
Healthy
128 MB
svc-authams3
Healthy
412 MB
svc-billingnyc3
Healthy
96 MB
svc-eventssfo3
Degraded
780 MB
svc-runtimesgp1
Deploying
512 MB
svc-orchestratorfra1
Failed
220 MB
svc-logsams3
Healthy
1024 MB
svc-hubnyc3
Healthy
356 MB
svc-gatewaysfo3
Healthy
180 MB
svc-authsgp1
Degraded
640 MB
svc-billingfra1
Deploying
72 MB
svc-eventsams3
Failed
300 MB
svc-runtimenyc3
Healthy
890 MB
svc-orchestratorsfo3
Healthy
240 MB
svc-logssgp1
Healthy
150 MB
svc-hubfra1
Degraded
480 MB
emptyMessagedata={[]}
Service
Region
Owner
No deploys recorded for this environment yet. Run nkapp deploy -e stage.
onRowClickrows get a pointer cursor and a hover fill

Last row clicked: (none)

Service
Image
Last Deployed
svc-gatewayregistry.nk/app:9a203m ago
svc-authregistry.nk/app:9a2718m ago
svc-billingregistry.nk/app:9a2e47m ago
svc-eventsregistry.nk/app:9a352h ago

Formatters

Four Intl-backed functions and one component, replacing the hand-rolled copies scattered across the Hub, account, admin and the services. They are plain functions on purpose, so the CLI and the NestJS services can call the same code as the browser.

formatBytes

iec · si · jedec

The unit ladder is an explicit argument because the repo gets it wrong in six places: every hand-rolled copy divides by 1024 and then labels the result KB. 1024 bytes is a KiB; kB is 1000. jedec exists only so adopting the function is a byte-identical drop-in for those six — migrate the maths first, fix the label when you choose to.

Inputiec · 1024 · KiB (default)si · 1000 · kBjedec · 1024 · KB
00 B0 B0 B
10001,000 B1 kB1,000 B
10241 KiB1 kB1 KB
1_048_5761 MiB1 MB1 MB
1_503_238_5531.4 GiB1.5 GB1.4 GB
-2048-2 KiB-2 kB-2 KB
2 ** 601 EiB1.2 EB1 EB
null———
NaN———

Read the 1024 row across: the default says 1 KiB, si says 1 kB — which is a 2.4% lie — and jedec reproduces the existing bug verbatim. The last four rows are the cases that break the hand-rolled versions: a negative delta, an exabyte past the end of their ladder, and two invalid inputs that used to render NaN undefined.

formatNumber

and formatPercent

formatPercent takes 0–100, the opposite of Intl's own convention, because every percentage in this codebase is already scaled that way — a ratio would render every CPU gauge as 0%.

formatNumbergrouping is locale-correct
184203184,203
12341,234
00
-42-42
compactnotation: 'compact'
12341.2K
184203184.2K
98000009.8M
12500000001.3B
formatPercentfractionDigits · clamp
12.3412%
12.34 · digits 112.3%
100.4 · clamp100%
null—

formatDuration

clock · compact · long

Input is milliseconds. The APIs here that report seconds multiply at the call site. clock lets hours run past 24 because that is what a stopwatch does; use compact when you want days.

stylethe same five inputs, three shapes
msclockcompactlong
000:00:000s0 seconds
87000:00:000s0 seconds
137_00000:02:172m 17s2 minutes, 17 seconds
8_100_00002:15:002h 15m2 hours, 15 minutes
3_456_000_000960:00:0040d40 days

formatRelativeTime

and NkRelativeTime

The function is a pure function of (value, now) — it does not tick, which is what makes it testable and usable server-side. NkRelativeTime is the half that owns the interval, and it widens its own cadence as the value ages (1s under a minute, 30s under an hour, 5min beyond) so twenty of them on a dashboard do not cost twenty wake-ups a second.

Measuring against the clock — rendered after mount.

Two things the hand-rolled copies get wrong are visible above: the future case renders in 2h rather than collapsing to “just now” — which matters for the one screen that most needs it, a cron job's next run — and the long form pluralises, so an hour old reads 1 hour ago, not 1 hours ago. Hover a live label for the exact instant; the component renders a real <time dateTime>.

The table above is rendered once and then left alone, which is the point: the function is not live. Only the four labels below it tick. Note also that the amount is truncated, never rounded — 1 h 59 m reads 1h, because it has not been two hours.

Pagination

One pager in two shapes: a full-width control bar under a list, or a floating pill the caller positions over a full-height table.

NkPagination

bar · floating · page size

Fully controlled: page, pageCount, totalItems and pageSize in, a clamped 1-based page out of onPageChange. The “showing X–Y of N” readout is derived, never passed.

floating={false}the default full-width control bar

Page 3 of 20

pageSizeOptions + onPageSizeChangethe rows-per-page selector only renders when both are passed

57 items / 10 per page = 6 pages

floatinga self-sizing pill the caller positions over a table
ID
Service
Image
Status
1svc-01registry.nk/app:1000
Failed
2svc-02registry.nk/app:1001
Healthy
3svc-03registry.nk/app:1002
Healthy
4svc-04registry.nk/app:1003
Healthy
5svc-05registry.nk/app:1004
Healthy
6svc-06registry.nk/app:1005
Healthy
7svc-07registry.nk/app:1006
Healthy
8svc-08registry.nk/app:1007
Failed