@stina/extension-api 1.16.0 → 1.18.0

package/src/types.components.ts

@@ -1,3 +1,5 @@
+import type { LocalizedString } from './types.localization.js'
+
 // =============================================================================
 // Icon Names
 // =============================================================================
@@ -240,15 +242,15 @@ export interface ExtensionPanelDefinition {
 export interface HeaderProps extends ExtensionComponentData {
   component: 'Header'
   level: number
-  title: string
-  description?: string | string[]
+  title: LocalizedString
+  description?: LocalizedString | LocalizedString[]
   icon?: HugeIconName
 }
 
 /** The extension API properties for the Label component. */
 export interface LabelProps extends ExtensionComponentData {
   component: 'Label'
-  text: string
+  text: LocalizedString
 }
 
 /**
@@ -267,17 +269,17 @@ export interface ClockProps extends ExtensionComponentData {
 /** The extension API properties for the paragraph component. */
 export interface ParagraphProps extends ExtensionComponentData {
   component: 'Paragraph'
-  text: string
+  text: LocalizedString
 }
 
 /** The extension API properties for the Button component. */
 export interface ButtonProps extends ExtensionComponentData {
   component: 'Button'
-  text: string
+  text: LocalizedString
   /** Visual style. Defaults to "normal". */
   type?: 'normal' | 'primary' | 'danger' | 'accent'
   /** Optional tooltip shown on hover. */
-  title?: string
+  title?: LocalizedString
   disabled?: boolean
   onClickAction: ExtensionActionRef
 }
@@ -285,8 +287,8 @@ export interface ButtonProps extends ExtensionComponentData {
 /** The extension API properties for the TextInput component. */
 export interface TextInputProps extends ExtensionComponentData {
   component: 'TextInput'
-  label: string
-  placeholder?: string
+  label: LocalizedString
+  placeholder?: LocalizedString
   value?: string
   onChangeAction?: ExtensionActionRef
 }
@@ -294,8 +296,8 @@ export interface TextInputProps extends ExtensionComponentData {
 /** The extension API properties for the PasswordInput component. */
 export interface PasswordInputProps extends ExtensionComponentData {
   component: 'PasswordInput'
-  label: string
-  placeholder?: string
+  label: LocalizedString
+  placeholder?: LocalizedString
   value?: string
   onChangeAction?: ExtensionActionRef
 }
@@ -303,8 +305,8 @@ export interface PasswordInputProps extends ExtensionComponentData {
 /** The extension API properties for the NumberInput component. */
 export interface NumberInputProps extends ExtensionComponentData {
   component: 'NumberInput'
-  label: string
-  placeholder?: string
+  label: LocalizedString
+  placeholder?: LocalizedString
   value?: string | number
   /** Optional minimum value. */
   min?: number
@@ -318,8 +320,8 @@ export interface NumberInputProps extends ExtensionComponentData {
 /** The extension API properties for the TextArea component. */
 export interface TextAreaProps extends ExtensionComponentData {
   component: 'TextArea'
-  label: string
-  placeholder?: string
+  label: LocalizedString
+  placeholder?: LocalizedString
   value?: string
   /** Number of visible text rows. Defaults to 4. */
   rows?: number
@@ -329,7 +331,7 @@ export interface TextAreaProps extends ExtensionComponentData {
 /** The extension API properties for the DateTimeInput component. */
 export interface DateTimeInputProps extends ExtensionComponentData {
   component: 'DateTimeInput'
-  label: string
+  label: LocalizedString
   value?: string
   onChangeAction?: ExtensionActionRef
 }
@@ -337,8 +339,8 @@ export interface DateTimeInputProps extends ExtensionComponentData {
 /** The extension API properties for the Select component. */
 export interface SelectProps extends ExtensionComponentData {
   component: 'Select'
-  label: string
-  options: Array<{ label: string; value: string }>
+  label: LocalizedString
+  options: Array<{ label: LocalizedString; value: string }>
   selectedValue?: string
   onChangeAction?: ExtensionActionRef
 }
@@ -346,7 +348,7 @@ export interface SelectProps extends ExtensionComponentData {
 /** The extension API properties for the IconPicker component. */
 export interface IconPickerProps extends ExtensionComponentData {
   component: 'IconPicker'
-  label?: string
+  label?: LocalizedString
   value?: string
   onChangeAction?: ExtensionActionRef
 }
@@ -382,7 +384,7 @@ export interface DividerProps extends ExtensionComponentData {
 export interface IconProps extends ExtensionComponentData {
   component: 'Icon'
   name: HugeIconName
-  title?: string
+  title?: LocalizedString
 }
 
 /** Button type for IconButton. */
@@ -392,7 +394,7 @@ export type IconButtonType = 'normal' | 'primary' | 'danger' | 'accent'
 export interface IconButtonProps extends ExtensionComponentData {
   component: 'IconButton'
   icon: HugeIconName
-  tooltip: string
+  tooltip: LocalizedString
   active?: boolean
   disabled?: boolean
   type?: IconButtonType
@@ -402,7 +404,7 @@ export interface IconButtonProps extends ExtensionComponentData {
 /** Action button definition for Panel component. */
 export interface PanelAction {
   icon: HugeIconName
-  tooltip: string
+  tooltip: LocalizedString
   action: ExtensionActionRef
   type?: IconButtonType
 }
@@ -410,8 +412,8 @@ export interface PanelAction {
 /** The extension API properties for the Panel component. */
 export interface PanelProps extends ExtensionComponentData {
   component: 'Panel'
-  title: string
-  description?: string | string[]
+  title: LocalizedString
+  description?: LocalizedString | LocalizedString[]
   icon?: HugeIconName
   actions?: PanelAction[]
   content?: ExtensionComponentData
@@ -420,8 +422,8 @@ export interface PanelProps extends ExtensionComponentData {
 /** The extension API properties for the Toggle component. */
 export interface ToggleProps extends ExtensionComponentData {
   component: 'Toggle'
-  label?: string
-  description?: string
+  label?: LocalizedString
+  description?: LocalizedString
   checked?: boolean
   disabled?: boolean
   onChangeAction?: ExtensionActionRef
@@ -431,9 +433,9 @@ export interface ToggleProps extends ExtensionComponentData {
 export interface CollapsibleProps extends ExtensionComponentData {
   component: 'Collapsible'
   /** Title displayed in the header. */
-  title: string
+  title: LocalizedString
   /** Optional description rendered under the title. */
-  description?: string | string[]
+  description?: LocalizedString | LocalizedString[]
   /** Optional icon shown to the left of the title. */
   icon?: HugeIconName
   /** Whether the section is expanded by default. */
@@ -449,7 +451,7 @@ export type PillVariant = 'default' | 'primary' | 'success' | 'warning' | 'dange
 export interface PillProps extends ExtensionComponentData {
   component: 'Pill'
   /** Text to display in the pill. */
-  text: string
+  text: LocalizedString
   /** Optional icon shown to the left of the text. */
   icon?: HugeIconName
   /** Color variant. Defaults to 'default'. */
@@ -460,7 +462,7 @@ export interface PillProps extends ExtensionComponentData {
 export interface CheckboxProps extends ExtensionComponentData {
   component: 'Checkbox'
   /** Label text displayed next to the checkbox. */
-  label: string
+  label: LocalizedString
   /** Whether the checkbox is checked. */
   checked?: boolean
   /** Whether the checkbox is disabled. */
@@ -475,7 +477,7 @@ export interface CheckboxProps extends ExtensionComponentData {
 export interface MarkdownProps extends ExtensionComponentData {
   component: 'Markdown'
   /** Markdown content to render. */
-  content: string
+  content: LocalizedString
 }
 
 /** The extension API properties for the TextPreview component. */
@@ -491,7 +493,7 @@ export interface TextPreviewProps extends ExtensionComponentData {
 export interface ModalProps extends ExtensionComponentData {
   component: 'Modal'
   /** Title displayed in the modal header. */
-  title: string
+  title: LocalizedString
   /** Whether the modal is open. */
   open?: boolean
   /** Optional max width for the modal (e.g., '600px', '80%'). Defaults to '600px'. */
@@ -532,7 +534,7 @@ export type FrameVariant = 'border' | 'solid'
 export interface FrameProps extends ExtensionComponentData {
   component: 'Frame'
   /** Optional title displayed in the header. Can be a plain string or extension components. */
-  title?: string | ExtensionComponentChildren
+  title?: LocalizedString | ExtensionComponentChildren
   /** Whether the content can be toggled (collapsed/expanded) by clicking the title. Requires title to be set. */
   collapsible?: boolean
   /** Whether the frame content is expanded by default. Only used when collapsible is true. Defaults to true. */
@@ -658,7 +660,7 @@ export interface WeatherForecastStep {
 export interface WeatherForecastProps extends ExtensionComponentData {
   component: 'WeatherForecast'
   /** Heading above the row, e.g. "Kommande timmar". */
-  title?: string
+  title?: LocalizedString
   /** Icon shown to the left of the title. */
   icon?: HugeIconName
   /** Written after every temperature. Defaults to `°`. */
@@ -699,7 +701,7 @@ export interface ChartProps extends ExtensionComponentData {
   /** One per point, along the horizontal axis. */
   labels?: string[]
   /** Heading above the plot. With a single series this is what names it, so no legend is drawn. */
-  title?: string
+  title?: LocalizedString
   /** Icon shown to the left of the title. */
   icon?: HugeIconName
   /** Written after every value, e.g. `°`, ` mm`, ` kr`. */
@@ -726,12 +728,12 @@ export type StatTrend = 'up' | 'down' | 'flat'
 export interface StatTileProps extends ExtensionComponentData {
   component: 'StatTile'
   /** What the number is, e.g. "Förbrukning i går". */
-  label: string
+  label: LocalizedString
   value: string | number
   /** Written after the value in smaller type, e.g. `kWh`. */
   unit?: string
   /** One quiet line under the number. */
-  caption?: string
+  caption?: LocalizedString
   icon?: HugeIconName
   /** `flat` draws no arrow. */
   trend?: StatTrend
@@ -772,7 +774,7 @@ export type ProgressColor = 'accent' | 'success' | 'warning' | 'danger' | 'info'
 export interface ProgressBarProps extends ExtensionComponentData {
   component: 'ProgressBar'
   /** What is being measured, e.g. "Stressnivå". Shown beside the reading. */
-  label: string
+  label: LocalizedString
   value: number
   /** Bottom of the range. Defaults to 0. */
   min?: number
@@ -787,7 +789,7 @@ export interface ProgressBarProps extends ExtensionComponentData {
   /** 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
+  caption?: LocalizedString
   icon?: HugeIconName
 }
 
@@ -848,7 +850,7 @@ export interface TimelineEntry {
 export interface TimelineProps extends ExtensionComponentData {
   component: 'Timeline'
   /** Heading above the rail, e.g. "I dag". */
-  title?: string
+  title?: LocalizedString
   /** Icon shown to the left of the title. */
   icon?: HugeIconName
   entries: TimelineEntry[]
@@ -873,7 +875,7 @@ export type NoteVariant = 'default' | 'accent' | 'success' | 'warning' | 'danger
  */
 export interface NoteProps extends ExtensionComponentData {
   component: 'Note'
-  title?: string
+  title?: LocalizedString
   /** Icon shown to the left of the title. */
   icon?: HugeIconName
   /** Trailing badge next to the title: a source, a category, a time. */
@@ -1004,7 +1006,7 @@ export interface AgendaDay {
 export interface AgendaProps extends ExtensionComponentData {
   component: 'Agenda'
   /** Heading above the days. */
-  title?: string
+  title?: LocalizedString
   /** Icon shown to the left of the title. */
   icon?: HugeIconName
   days: AgendaDay[]

package/src/types.contributions.ts

@@ -87,6 +87,36 @@ export interface AccountContribution {
 // Tool Settings Views
 // ============================================================================
 
+/**
+ * What a settings view is about, which decides where Stina shows it.
+ *
+ * An extension never picks a place in the settings menu: the menu belongs to Stina and
+ * changes between versions. It says what the view is *about*, and Stina puts each topic
+ * where it belongs, the way `accounts`, `providers` and `statusCards` already work.
+ *
+ * - `accounts`: connects Stina to an account or a service (a mailbox, a calendar feed).
+ *   Shown with the other connected accounts.
+ * - `notifications`: when and how the extension may get in touch. Shown with Stina's own
+ *   notification settings.
+ * - `personal`: facts about the user the extension relies on (a home town for the
+ *   weather). Shown with the profile.
+ * - `tracking`: things Stina keeps track of for the user that are worth looking through
+ *   now and then (people, projects, reminders). Gets its own row in the register.
+ *
+ * A view without a topic, or with one this version of Stina does not know, is shown on
+ * the extension's own page. That is always a working place, only a less fitting one, so
+ * a topic added later never breaks an older Stina.
+ */
+export type ExtensionSettingsTopic = 'accounts' | 'notifications' | 'personal' | 'tracking'
+
+/** Every topic this version of the API knows, in no particular order. */
+export const EXTENSION_SETTINGS_TOPICS: readonly ExtensionSettingsTopic[] = [
+  'accounts',
+  'notifications',
+  'personal',
+  'tracking',
+]
+
 /**
  * Tool settings view definition (UI schema)
  */
@@ -94,9 +124,11 @@ export interface ToolSettingsViewDefinition {
   /** Unique view ID within the extension */
   id: string
   /** Display title */
-  title: string
+  title: LocalizedString
   /** Help text */
-  description?: string
+  description?: LocalizedString
+  /** What the view is about, and so where Stina shows it. See {@link ExtensionSettingsTopic}. */
+  topic?: ExtensionSettingsTopic
   /** View configuration */
   view: ToolSettingsView
 }
@@ -155,7 +187,7 @@ export interface ToolSettingsListGroupBy {
   /** Explicit ordering of group values. Groups not listed appear afterwards, sorted alphabetically. */
   order?: string[]
   /** Human-friendly labels per group value (rendered as section headers). Falls back to the raw value if missing. */
-  labels?: Record<string, string>
+  labels?: Record<string, LocalizedString>
 }
 
 /**
@@ -212,7 +244,7 @@ export interface PanelDefinition {
   /** Unique panel ID within the extension */
   id: string
   /** Display title */
-  title: string
+  title: LocalizedString
   /** Icon name (from huge-icons) */
   icon?: string
   /** Panel view schema */
@@ -234,7 +266,7 @@ export interface StatusCardDefinition {
   /** Unique card ID within the extension */
   id: string
   /** What it is called where the user picks it */
-  title: string
+  title: LocalizedString
   /** Icon name (from huge-icons) */
   icon?: string
   /**

package/src/types.ts

@@ -24,6 +24,7 @@ export type {
   ExtensionContributions,
   // Tool Settings Views
   ToolSettingsViewDefinition,
+  ExtensionSettingsTopic,
   ToolSettingsView,
   ToolSettingsListView,
   ToolSettingsListMapping,
@@ -51,6 +52,7 @@ export type {
   AccountProvider,
   AccountContribution,
 } from './types.contributions.js'
+export { EXTENSION_SETTINGS_TOPICS } from './types.contributions.js'
 
 // Manifest
 export type { ExtensionManifest, Platform } from './types.manifest.js'