@manta-eu/horns-kit

Reference for @manta-eu/horns-kit 0.2.3, generated from its published types.

pnpm add @manta-eu/horns-kit@0.2.3

Entry points

Type Aliases

ChartPalette

ChartPalette = object

Properties

alert

alert: string

A value on the wrong side of a threshold, and the line it crossed. Not a series slot, so no accent moves it.

baseline

baseline: string

grid

grid: string

ink

ink: string

muted

muted: string

other

other: string

secondary

secondary: string

series

series: readonly string[]

surface

surface: string

tooltipInk

tooltipInk: string

tooltipSurface

tooltipSurface: string

ChartTheme

ChartTheme = "light" | "dark"

Which of the two surfaces a Horn is drawn on.

EntityLink

EntityLink = object

A page to open for the thing an IRI shows, and what the link says.

Properties

href

href: string

label

label: string

HornChrome

HornChrome = object

Properties

gap

gap: number

Between cards.

padding

padding: number

Inside a card.

radius

radius: number

Card and chart-frame corners.

HornSnapshotViewProps

HornSnapshotViewProps = object

Properties

catalogCard?

optional catalogCard?: (content, view, context) => ReactNode

Draws a catalog card. Same bargain as writtenView: the kit knows nothing of @manta-eu/react, so a host that wants cards supplies this and the card fetches its own entity in a browser. Without it a card stays a placeholder, which is what a server render and a capture always see.

Parameters

content

Extract<SnapshotView["content"], { lane: "component"; }>

view

SnapshotView

context

WrittenViewContext

Returns

ReactNode

explain?

optional explain?: (fact) => void

Opens the explanation behind a value a view marked with WhyThis. Drawing one needs the design system, which the kit has not got; without this the marks are left off and the values draw alone, which is what a server render and a capture always see.

Parameters

fact

ExplainedFact

Returns

void

mode?

optional mode?: HornViewMode

onVariableChange?

optional onVariableChange?: (id, value) => void

Narrows the Horn when a view asks. Every binding taking that variable as a parameter is re-run by the host, which is how a tile filters a list it knows nothing about. Without it a view draws no controls.

Parameters

id

string

value

unknown

Returns

void

planActions?

optional planActions?: PlanActions

What the viewer may do with the action plans behind a view. Without it plans are shown, never run.

planStrip?

optional planStrip?: (args) => ReactNode

Draws a plan’s changes and its buttons. Same bargain again; without it the kit’s own strip draws.

Parameters

args

PlanStripArgs

Returns

ReactNode

snapshot

snapshot: HornSnapshot

theme?

optional theme?: ChartTheme

viewControls?

optional viewControls?: (view) => ReactNode

Controls a host hangs on each view’s own card — renaming it, taking it out. The kit only makes room: the markup is the host’s, so a capture, which passes none, draws exactly what it drew before.

Parameters

view

SnapshotView

Returns

ReactNode

writtenView?

optional writtenView?: (content, view, context) => ReactNode

Draws a written view. The kit knows neither @manta-eu/react nor how to run model-written source, so a host that wants written views supplies this — WrittenView from @manta-eu/horns-kit does the work, given the host’s own surface. Without it a written view stays a placeholder, which is also what a server render and a JavaScript-off capture always see.

Parameters

content

Extract<SnapshotView["content"], { lane: "sandbox"; }>

view

SnapshotView

context

WrittenViewContext

Returns

ReactNode

HornViewMode

HornViewMode = "page" | "embed" | "capture"

PlanActions

PlanActions = object

What a host lets a viewer do with a plan. The kit only asks: the host confirms, calls agents as the viewer and reports back through status, so a Horn rendered without actions — a capture, an embed that cannot run anything — shows the same plan with no buttons.

Properties

onPreview

onPreview: (plan) => void

Parameters

plan

SnapshotPlan

Returns

void

onRun

onRun: (plan) => void

Parameters

plan

SnapshotPlan

Returns

void

pending?

optional pending?: ReadonlySet<string>

Plans the host is sending a request for right now.

status?

optional status?: Readonly<Record<string, PlanStatus>>

Newer than the snapshot, by plan: how a run the host started is going.

WrittenViewContext

WrittenViewContext = object

What a written view gets beyond its own rows: the snapshot’s names and where each IRI opens. A view is handed these rather than composing an href, because the path belongs to the host, not to the source.

Properties

datastoreId

datastoreId: string

The datastore the Horn belongs to.

A catalog card fetches its own entity, so it needs somewhere to fetch from — and a server-rendered Horn document mounts no providers of its own. Without this the card spins for ever on a shared link.

labels

labels: Readonly<Record<string, string>>

links

links: Readonly<Record<string, EntityLink>>

Variables

chartPalettes

const chartPalettes: Record<ChartTheme, ChartPalette>

maxShownChanges

const maxShownChanges: 4 = 4

missingValue

const missingValue: "—" = “\u2014”

Functions

accentPalette()

accentPalette(palette, accent): ChartPalette

Parameters

palette

ChartPalette

accent

Returns

ChartPalette

chartPalette()

chartPalette(theme, style?): ChartPalette

The colours a Horn’s views draw with: the theme’s, with the Horn’s own accent leading.

Parameters

theme

ChartTheme

style?

accent?

density?

"compact" | "comfortable"

radius?

"sharp" | "soft" | "round"

theme?

"light" | "dark"

Returns

ChartPalette

entityLinks()

entityLinks(snapshot): Record<string, EntityLink>

Where each of a snapshot’s IRIs opens, ready to hand a view.

The snapshot stores what the link says; the path is composed here, because it belongs to the host rather than to anything a model wrote. Exported for hosts that draw one view on their own — a zoo, an entity page.

Parameters

snapshot

generatedAt

string

horn

{ datastoreId: string; iri: string; realm: "hiremanta-com" | "journey-travel"; revision: number; slug: string; title: string; }

horn.datastoreId

string

horn.iri

string

horn.realm

"hiremanta-com" | "journey-travel"

horn.revision

number

horn.slug

string

horn.title

string

labels

z.ZodRecord<z.ZodString, z.ZodString>

layout

{ columns: 12; items: object[]; kind: "grid"; }

layout.columns

12

layout.items

object[]

layout.kind

"grid"

links

z.ZodRecord<z.ZodString, z.ZodString>

plans

object[]

snapshotVersion

1

style

{ accent?: "blue" | "orange" | "green" | "amber" | "pink" | "forest" | "indigo" | "red"; density?: "compact" | "comfortable"; radius?: "sharp" | "soft" | "round"; theme?: "light" | "dark"; }

style.accent?

style.density?

"compact" | "comfortable"

style.radius?

"sharp" | "soft" | "round"

style.theme?

"light" | "dark"

variables

object[]

views

object[]

Returns

Record<string, EntityLink>

formatMeasure()

formatMeasure(value, measure?): string

Parameters

value

number | null | undefined

measure?

Measure

Returns

string

hornChrome()

hornChrome(style?): HornChrome

How much room a Horn takes, as numbers rather than classes: the capture browser has no stylesheet.

Parameters

style?

accent?

density?

"compact" | "comfortable"

radius?

"sharp" | "soft" | "round"

theme?

"light" | "dark"

Returns

HornChrome

HornSnapshotView()

HornSnapshotView(props): Element

Parameters

props

HornSnapshotViewProps

Returns

Element

planStateText()

planStateText(status, earlier?): object

How the plan’s last run went, in words. A run from before this page was opened says when it was, because a preview from last week says little about the plan as it stands now.

Parameters

status

PlanStatus

earlier?

boolean

Returns

object

text

text: string

tone

tone: "quiet" | "busy" | "good" | "bad"

planSummary()

planSummary(plan, labels): string

“Changes 1 campaign and 3 campaign budgets.”

Parameters

plan

changes

object[]

iri

string

kinds

object[]

lastRun?

{ endedAt?: string; error?: string; preview: boolean; startedAt: string; }

lastRun.endedAt?

string

lastRun.error?

string

lastRun.preview

boolean

lastRun.startedAt

string

name?

string

reasons

object[]

state

"draft" | "running" | "completed" | "failed" | "timed-out"

labels

Readonly<Record<string, string>>

Returns

string

planTitle()

planTitle(plan, labels): string

What the plan is called: its own name when the graph gives one, else what it would change — “Change status”, “Change budget amount and daily budget” — so two plans behind one view read as two different things.

Parameters

plan

changes

object[]

iri

string

kinds

object[]

lastRun?

{ endedAt?: string; error?: string; preview: boolean; startedAt: string; }

lastRun.endedAt?

string

lastRun.error?

string

lastRun.preview

boolean

lastRun.startedAt

string

name?

string

reasons

object[]

state

"draft" | "running" | "completed" | "failed" | "timed-out"

labels

Readonly<Record<string, string>>

Returns

string

planValue()

planValue(value, change, labels): string

Parameters

value

string | number | boolean | null

change

currency?

string

entity

string

from

string | number | boolean | null

property

string

to

string | number | boolean | null

unit?

"currency" | "percent" | "ratio"

labels

Readonly<Record<string, string>>

Returns

string

runnable()

runnable(live): boolean

A real run is offered only once a preview has finished cleanly while the viewer watched: one from before the page was opened checked the plan as it was then.

Parameters

live

PlanStatus | undefined

Returns

boolean

unreadableChanges()

unreadableChanges(plan): number

Said when the plan touches more things than it has readable changes for.

kinds counts what the plan concerns; changes holds the ones whose before and after could both be read. “Changes 3 campaigns” over one listed row reads as a bug unless the gap is named.

Parameters

plan

changes

object[]

iri

string

kinds

object[]

lastRun?

{ endedAt?: string; error?: string; preview: boolean; startedAt: string; }

lastRun.endedAt?

string

lastRun.error?

string

lastRun.preview

boolean

lastRun.startedAt

string

name?

string

reasons

object[]

state

"draft" | "running" | "completed" | "failed" | "timed-out"

Returns

number

References