@stina/extension-api 0.57.0 → 1.0.0

package/src/types.components.ts

@@ -731,6 +731,53 @@ export interface StatTileProps extends ExtensionComponentData {
   trendIsGood?: boolean
 }
 
+/** Whether a progress reading is drawn as a rail or as a ring. */
+export type ProgressShape = 'bar' | 'circle'
+
+/**
+ * The colours a progress reading may take.
+ *
+ * A closed list rather than a colour string: the caller is usually a language
+ * model, and the six names here are the six the themes actually define, so a
+ * reading cannot end up in a hue the current theme has no contrast for.
+ */
+export type ProgressColor = 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'neutral'
+
+/**
+ * The extension API properties for the ProgressBar component.
+ *
+ * One value seen against the range it lives in — how far along something is,
+ * how loaded a day looks, how high a level sits. A StatTile says what the
+ * number *is*; this says where it *sits*, which is the thing a number alone
+ * cannot show.
+ *
+ * `min` and `max` are the range, not decoration: a value is drawn as its
+ * position between them, so "3 of 5" and "60 of 100" fill the same amount.
+ * Values outside the range are clamped rather than refused — a reading that
+ * ran past its ceiling should still draw as full.
+ */
+export interface ProgressBarProps extends ExtensionComponentData {
+  component: 'ProgressBar'
+  /** What is being measured, e.g. "Stressnivå". Shown beside the reading. */
+  label: string
+  value: number
+  /** Bottom of the range. Defaults to 0. */
+  min?: number
+  /** Top of the range. Defaults to 100. */
+  max?: number
+  /** Defaults to `bar`. */
+  shape?: ProgressShape
+  /** Defaults to `accent`. */
+  color?: ProgressColor
+  /** Written after the value, e.g. `%` or ` av 5`. */
+  unit?: string
+  /** The readout in words, when the bare number does not say it. Replaces value and unit. */
+  valueLabel?: string
+  /** One quiet line under the reading. */
+  caption?: string
+  icon?: HugeIconName
+}
+
 /** One row of a KeyValueList. */
 export interface KeyValueRow {
   label: string

package/src/types.contributions.ts

@@ -13,6 +13,8 @@ import type { ExtensionComponentData } from './types.components.js'
 export interface ExtensionContributions {
   /** Tool settings views for UI */
   toolSettings?: ToolSettingsViewDefinition[]
+  /** Cards for the strip above the conversation list */
+  statusCards?: StatusCardDefinition[]
   /** Right panel contributions */
   panels?: PanelDefinition[]
   /** AI providers */
@@ -170,6 +172,39 @@ export interface PanelDefinition {
   view: PanelView
 }
 
+/**
+ * A card for the strip above the conversation list.
+ *
+ * The same declarative machinery as a panel, in a much smaller space and with
+ * one rule that is not a style guide: a card says what is true right now. It
+ * has no controls, because a sidebar is read in passing and anything the user
+ * wants to do about what it says, they say in words.
+ *
+ * The user chooses which cards they want and in what order, so an extension
+ * offering three is offering three, not imposing them.
+ */
+export interface StatusCardDefinition {
+  /** Unique card ID within the extension */
+  id: string
+  /** What it is called where the user picks it */
+  title: string
+  /** Icon name (from huge-icons) */
+  icon?: string
+  /**
+   * How much room it may take.
+   *
+   * Part of the contract rather than a guideline, because the sidebar is a few
+   * hundred pixels wide and the first card written without a limit will be
+   * written against a screen.
+   *
+   * - `line`: one row. A figure, a label, a pill.
+   * - `block`: up to three rows.
+   */
+  size: 'line' | 'block'
+  /** What it draws, and where the data comes from */
+  view: PanelComponentView
+}
+
 /**
  * Panel view schema (declarative)
  */

package/src/types.permissions.ts

@@ -39,6 +39,7 @@ export type CapabilityPermission =
   | 'settings.register'
   | 'commands.register'
   | 'panels.register'
+  | 'statusCards.register'
   | 'events.emit'
   | 'scheduler.register'
   | 'chat.message.write'

package/src/types.tools.ts

@@ -52,8 +52,27 @@ export interface ToolResult {
    * Validate with `validateChatCard` before returning one. A card that fails the
    * profile is dropped by the host rather than half-rendered, so a tool that
    * skips the check finds out from the user, which is the wrong end.
+   *
+   * Most tools should prefer {@link ToolResult.cardSuggestion}: a card drawn here
+   * is shown whatever the user asked, and a timeline of ten mails is the wrong
+   * answer to "did Anna write back?".
    */
   display?: ExtensionComponentData
+
+  /**
+   * The shape this tool thinks its answer has: one component name from the chat
+   * card profile, such as `"Timeline"` or `"WeatherForecast"`.
+   *
+   * A suggestion, not a drawing. It travels to the model with the result, and
+   * Stina decides whether to show a card at all, what goes in it, and how much of
+   * the data belongs there — summing three days into one figure, or answering in
+   * a sentence because the user asked a yes-or-no question. The tool knows the
+   * shape of its data; only she knows the shape of the question.
+   *
+   * A name outside the profile is dropped by the host with a warning, since it
+   * would send her after a component that does not exist.
+   */
+  cardSuggestion?: string
 }
 
 /**

package/src/types.ts

@@ -31,6 +31,7 @@ export type {
   ToolSettingsActionDataSource,
   // Panels
   PanelDefinition,
+  StatusCardDefinition,
   PanelView,
   PanelUnknownView,
   PanelActionDataSource,