@stina/extension-api 1.16.0 → 1.18.0

package/src/schemas/components.schema.ts

@@ -5,6 +5,7 @@
  */
 
 import { z } from 'zod'
+import { LocalizedStringSchema } from './localization.schema.js'
 
 // =============================================================================
 // CSS Properties
@@ -180,8 +181,8 @@ export const HeaderPropsSchema = z
   .object({
     component: z.literal('Header'),
     level: z.number().min(1).max(6).describe('Heading level (1-6)'),
-    title: z.string().describe('Header title'),
-    description: z.union([z.string(), z.array(z.string())]).optional().describe('Description text'),
+    title: LocalizedStringSchema.describe('Header title'),
+    description: z.union([LocalizedStringSchema, z.array(LocalizedStringSchema)]).optional().describe('Description text'),
     icon: z.string().optional().describe('Icon name'),
     style: ExtensionComponentStyleSchema.optional(),
   })
@@ -191,7 +192,7 @@ export const HeaderPropsSchema = z
 export const LabelPropsSchema = z
   .object({
     component: z.literal('Label'),
-    text: z.string().describe('Label text'),
+    text: LocalizedStringSchema.describe('Label text'),
     style: ExtensionComponentStyleSchema.optional(),
   })
   .passthrough()
@@ -208,7 +209,7 @@ export const ClockPropsSchema = z
 export const ParagraphPropsSchema = z
   .object({
     component: z.literal('Paragraph'),
-    text: z.string().describe('Paragraph text'),
+    text: LocalizedStringSchema.describe('Paragraph text'),
     style: ExtensionComponentStyleSchema.optional(),
   })
   .passthrough()
@@ -217,9 +218,9 @@ export const ParagraphPropsSchema = z
 export const ButtonPropsSchema = z
   .object({
     component: z.literal('Button'),
-    text: z.string().describe('Button text'),
+    text: LocalizedStringSchema.describe('Button text'),
     type: z.enum(['normal', 'primary', 'danger', 'accent']).optional().describe('Visual style'),
-    title: z.string().optional().describe('Tooltip shown on hover'),
+    title: LocalizedStringSchema.optional().describe('Tooltip shown on hover'),
     disabled: z.boolean().optional().describe('Disable the button'),
     onClickAction: ExtensionActionRefSchema.describe('Action to call on click'),
     style: ExtensionComponentStyleSchema.optional(),
@@ -230,8 +231,8 @@ export const ButtonPropsSchema = z
 export const TextInputPropsSchema = z
   .object({
     component: z.literal('TextInput'),
-    label: z.string().describe('Input label'),
-    placeholder: z.string().optional().describe('Placeholder text'),
+    label: LocalizedStringSchema.describe('Input label'),
+    placeholder: LocalizedStringSchema.optional().describe('Placeholder text'),
     value: z.string().optional().describe('Current value'),
     onChangeAction: ExtensionActionRefSchema.optional().describe('Action to call on change'),
     style: ExtensionComponentStyleSchema.optional(),
@@ -242,8 +243,8 @@ export const TextInputPropsSchema = z
 export const PasswordInputPropsSchema = z
   .object({
     component: z.literal('PasswordInput'),
-    label: z.string().describe('Input label'),
-    placeholder: z.string().optional().describe('Placeholder text'),
+    label: LocalizedStringSchema.describe('Input label'),
+    placeholder: LocalizedStringSchema.optional().describe('Placeholder text'),
     value: z.string().optional().describe('Current value'),
     onChangeAction: ExtensionActionRefSchema.optional().describe('Action to call on change'),
     style: ExtensionComponentStyleSchema.optional(),
@@ -254,8 +255,8 @@ export const PasswordInputPropsSchema = z
 export const NumberInputPropsSchema = z
   .object({
     component: z.literal('NumberInput'),
-    label: z.string().describe('Input label'),
-    placeholder: z.string().optional().describe('Placeholder text'),
+    label: LocalizedStringSchema.describe('Input label'),
+    placeholder: LocalizedStringSchema.optional().describe('Placeholder text'),
     value: z.union([z.string(), z.number()]).optional().describe('Current value'),
     min: z.number().optional().describe('Minimum value'),
     max: z.number().optional().describe('Maximum value'),
@@ -269,8 +270,8 @@ export const NumberInputPropsSchema = z
 export const TextAreaPropsSchema = z
   .object({
     component: z.literal('TextArea'),
-    label: z.string().describe('Input label'),
-    placeholder: z.string().optional().describe('Placeholder text'),
+    label: LocalizedStringSchema.describe('Input label'),
+    placeholder: LocalizedStringSchema.optional().describe('Placeholder text'),
     value: z.string().optional().describe('Current value'),
     rows: z.number().int().positive().optional().describe('Number of visible text rows'),
     onChangeAction: ExtensionActionRefSchema.optional().describe('Action to call on change'),
@@ -282,7 +283,7 @@ export const TextAreaPropsSchema = z
 export const DateTimeInputPropsSchema = z
   .object({
     component: z.literal('DateTimeInput'),
-    label: z.string().describe('Input label'),
+    label: LocalizedStringSchema.describe('Input label'),
     value: z.string().optional().describe('Current value'),
     onChangeAction: ExtensionActionRefSchema.optional().describe('Action to call on change'),
     style: ExtensionComponentStyleSchema.optional(),
@@ -293,8 +294,8 @@ export const DateTimeInputPropsSchema = z
 export const SelectPropsSchema = z
   .object({
     component: z.literal('Select'),
-    label: z.string().describe('Select label'),
-    options: z.array(z.object({ label: z.string(), value: z.string() })).describe('Available options'),
+    label: LocalizedStringSchema.describe('Select label'),
+    options: z.array(z.object({ label: LocalizedStringSchema, value: z.string() })).describe('Available options'),
     selectedValue: z.string().optional().describe('Currently selected value'),
     onChangeAction: ExtensionActionRefSchema.optional().describe('Action to call on change'),
     style: ExtensionComponentStyleSchema.optional(),
@@ -305,7 +306,7 @@ export const SelectPropsSchema = z
 export const IconPickerPropsSchema = z
   .object({
     component: z.literal('IconPicker'),
-    label: z.string().optional().describe('Picker label'),
+    label: LocalizedStringSchema.optional().describe('Picker label'),
     value: z.string().optional().describe('Currently selected icon name'),
     onChangeAction: ExtensionActionRefSchema.optional().describe('Action to call on change'),
     style: ExtensionComponentStyleSchema.optional(),
@@ -356,7 +357,7 @@ export const IconPropsSchema = z
   .object({
     component: z.literal('Icon'),
     name: z.string().describe('Icon name'),
-    title: z.string().optional().describe('Icon title'),
+    title: LocalizedStringSchema.optional().describe('Icon title'),
     style: ExtensionComponentStyleSchema.optional(),
   })
   .passthrough()
@@ -370,7 +371,7 @@ export const IconButtonPropsSchema = z
   .object({
     component: z.literal('IconButton'),
     icon: z.string().describe('Icon name'),
-    tooltip: z.string().describe('Tooltip text'),
+    tooltip: LocalizedStringSchema.describe('Tooltip text'),
     active: z.boolean().optional().describe('Whether the button is active'),
     disabled: z.boolean().optional().describe('Whether the button is disabled'),
     type: IconButtonTypeSchema.optional().describe('Button style type'),
@@ -383,7 +384,7 @@ export const IconButtonPropsSchema = z
 export const PanelActionSchema = z
   .object({
     icon: z.string().describe('Icon name'),
-    tooltip: z.string().describe('Tooltip text'),
+    tooltip: LocalizedStringSchema.describe('Tooltip text'),
     action: ExtensionActionRefSchema.describe('Action to call'),
     type: IconButtonTypeSchema.optional().describe('Button style type'),
   })
@@ -392,8 +393,8 @@ export const PanelActionSchema = z
 export const PanelPropsSchema = z
   .object({
     component: z.literal('Panel'),
-    title: z.string().describe('Panel title'),
-    description: z.union([z.string(), z.array(z.string())]).optional().describe('Description text'),
+    title: LocalizedStringSchema.describe('Panel title'),
+    description: z.union([LocalizedStringSchema, z.array(LocalizedStringSchema)]).optional().describe('Description text'),
     icon: z.string().optional().describe('Icon name'),
     actions: z.array(PanelActionSchema).optional().describe('Action buttons'),
     content: ExtensionComponentDataSchema.optional().describe('Panel content'),
@@ -405,8 +406,8 @@ export const PanelPropsSchema = z
 export const TogglePropsSchema = z
   .object({
     component: z.literal('Toggle'),
-    label: z.string().optional().describe('Toggle label'),
-    description: z.string().optional().describe('Description text'),
+    label: LocalizedStringSchema.optional().describe('Toggle label'),
+    description: LocalizedStringSchema.optional().describe('Description text'),
     checked: z.boolean().optional().describe('Whether the toggle is checked'),
     disabled: z.boolean().optional().describe('Whether the toggle is disabled'),
     onChangeAction: ExtensionActionRefSchema.optional().describe('Action to call on change'),
@@ -418,8 +419,8 @@ export const TogglePropsSchema = z
 export const CollapsiblePropsSchema = z
   .object({
     component: z.literal('Collapsible'),
-    title: z.string().describe('Title displayed in the header'),
-    description: z.union([z.string(), z.array(z.string())]).optional().describe('Description text'),
+    title: LocalizedStringSchema.describe('Title displayed in the header'),
+    description: z.union([LocalizedStringSchema, z.array(LocalizedStringSchema)]).optional().describe('Description text'),
     icon: z.string().optional().describe('Icon name'),
     defaultExpanded: z.boolean().optional().describe('Whether expanded by default'),
     content: ExtensionComponentDataSchema.optional().describe('Content when expanded'),
@@ -435,7 +436,7 @@ export const PillVariantSchema = z
 export const PillPropsSchema = z
   .object({
     component: z.literal('Pill'),
-    text: z.string().describe('Pill text'),
+    text: LocalizedStringSchema.describe('Pill text'),
     icon: z.string().optional().describe('Icon name'),
     variant: PillVariantSchema.optional().describe('Color variant'),
     style: ExtensionComponentStyleSchema.optional(),
@@ -446,7 +447,7 @@ export const PillPropsSchema = z
 export const CheckboxPropsSchema = z
   .object({
     component: z.literal('Checkbox'),
-    label: z.string().describe('Checkbox label'),
+    label: LocalizedStringSchema.describe('Checkbox label'),
     checked: z.boolean().optional().describe('Whether the checkbox is checked'),
     disabled: z.boolean().optional().describe('Whether the checkbox is disabled'),
     strikethrough: z.boolean().optional().describe('Strike through label when checked'),
@@ -459,7 +460,7 @@ export const CheckboxPropsSchema = z
 export const MarkdownPropsSchema = z
   .object({
     component: z.literal('Markdown'),
-    content: z.string().describe('Markdown content'),
+    content: LocalizedStringSchema.describe('Markdown content'),
     style: ExtensionComponentStyleSchema.optional(),
   })
   .passthrough()
@@ -478,7 +479,7 @@ export const TextPreviewPropsSchema = z
 export const ModalPropsSchema = z
   .object({
     component: z.literal('Modal'),
-    title: z.string().describe('Modal title'),
+    title: LocalizedStringSchema.describe('Modal title'),
     open: z.boolean().optional().describe('Whether the modal is open'),
     maxWidth: z.string().optional().describe('Max width of the modal'),
     body: ExtensionComponentDataSchema.optional().describe('Modal body content'),
@@ -506,7 +507,7 @@ export const FrameVariantSchema = z
 export const FramePropsSchema = z
   .object({
     component: z.literal('Frame'),
-    title: z.union([z.string(), ExtensionComponentChildrenSchema]).optional().describe('Optional title (string or components)'),
+    title: z.union([LocalizedStringSchema, ExtensionComponentChildrenSchema]).optional().describe('Optional title (string or components)'),
     icon: z.string().optional().describe('Icon name'),
     collapsible: z.boolean().optional().describe('Whether content can be toggled'),
     defaultExpanded: z.boolean().optional().describe('Whether expanded by default'),
@@ -598,7 +599,7 @@ export const WeatherForecastStepSchema = z
 export const WeatherForecastPropsSchema = z
   .object({
     component: z.literal('WeatherForecast'),
-    title: z.string().optional().describe('Heading above the row'),
+    title: LocalizedStringSchema.optional().describe('Heading above the row'),
     icon: z.string().optional().describe('Icon shown to the left of the title'),
     unit: z.string().optional().describe('Written after every temperature. Defaults to °'),
     steps: z.array(WeatherForecastStepSchema).min(1).describe('Steps, hourly or daily'),
@@ -631,7 +632,7 @@ export const ChartPropsSchema = z
     chart: ChartKindSchema.optional().describe('Defaults to line'),
     series: z.array(ChartSeriesSchema).min(1).max(8).describe('At most eight series'),
     labels: z.array(z.string()).optional().describe('One per point, along the horizontal axis'),
-    title: z.string().optional().describe('Heading above the plot'),
+    title: LocalizedStringSchema.optional().describe('Heading above the plot'),
     icon: z.string().optional().describe('Icon shown to the left of the title'),
     unit: z.string().optional().describe('Written after every value'),
     zeroBaseline: z.boolean().optional().describe('Force the value axis to include zero'),
@@ -646,10 +647,10 @@ export const StatTrendSchema = z.enum(['up', 'down', 'flat']).describe('Directio
 export const StatTilePropsSchema = z
   .object({
     component: z.literal('StatTile'),
-    label: z.string().describe('What the number is'),
+    label: LocalizedStringSchema.describe('What the number is'),
     value: z.union([z.string(), z.number()]).describe('The number itself'),
     unit: z.string().optional().describe('Written after the value in smaller type'),
-    caption: z.string().optional().describe('One quiet line under the number'),
+    caption: LocalizedStringSchema.optional().describe('One quiet line under the number'),
     icon: z.string().optional().describe('Icon name'),
     trend: StatTrendSchema.optional(),
     trendLabel: z.string().optional().describe('The change in words'),
@@ -670,7 +671,7 @@ export const ProgressColorSchema = z
 export const ProgressBarPropsSchema = z
   .object({
     component: z.literal('ProgressBar'),
-    label: z.string().describe('What is being measured'),
+    label: LocalizedStringSchema.describe('What is being measured'),
     value: z.number().describe('Where the reading sits. Clamped to the range'),
     min: z.number().optional().describe('Bottom of the range. Defaults to 0'),
     max: z.number().optional().describe('Top of the range. Defaults to 100'),
@@ -678,7 +679,7 @@ export const ProgressBarPropsSchema = z
     color: ProgressColorSchema.optional().describe('Defaults to accent'),
     unit: z.string().optional().describe('Written after the value'),
     valueLabel: z.string().optional().describe('The readout in words, replacing value and unit'),
-    caption: z.string().optional().describe('One quiet line under the reading'),
+    caption: LocalizedStringSchema.optional().describe('One quiet line under the reading'),
     icon: z.string().optional().describe('Icon name'),
     style: ExtensionComponentStyleSchema.optional(),
   })
@@ -725,7 +726,7 @@ export const TimelineEntrySchema = z
 export const TimelinePropsSchema = z
   .object({
     component: z.literal('Timeline'),
-    title: z.string().optional().describe('Heading above the rail'),
+    title: LocalizedStringSchema.optional().describe('Heading above the rail'),
     icon: z.string().optional().describe('Icon shown to the left of the title'),
     entries: z.array(TimelineEntrySchema).min(1).describe('Entries, in the order they happen'),
     style: ExtensionComponentStyleSchema.optional(),
@@ -740,7 +741,7 @@ export const NoteVariantSchema = z
 export const NotePropsSchema = z
   .object({
     component: z.literal('Note'),
-    title: z.string().optional(),
+    title: LocalizedStringSchema.optional(),
     icon: z.string().optional().describe('Icon shown to the left of the title'),
     badge: z.string().optional().describe('Trailing badge next to the title'),
     content: z.string().describe('The body, as markdown'),
@@ -798,7 +799,7 @@ export const AgendaDaySchema = z
 export const AgendaPropsSchema = z
   .object({
     component: z.literal('Agenda'),
-    title: z.string().optional(),
+    title: LocalizedStringSchema.optional(),
     icon: z.string().optional().describe('Icon shown to the left of the title'),
     days: z.array(AgendaDaySchema),
     warnOverlaps: z.boolean().optional().describe('Word clashes between events'),

package/src/schemas/contributions.schema.ts

@@ -6,17 +6,10 @@
 
 import { z } from 'zod'
 import { ExtensionComponentDataSchema } from './components.schema.js'
+import { LocalizedStringSchema } from './localization.schema.js'
 
-// =============================================================================
-// Localization
-// =============================================================================
+export { LocalizedStringSchema }
 
-/**
- * Localized string - either a simple string or a map of language codes to strings
- */
-export const LocalizedStringSchema = z
-  .union([z.string(), z.record(z.string())])
-  .describe('String or localized string map')
 
 // =============================================================================
 // Tool Settings Views
@@ -58,7 +51,7 @@ export const ToolSettingsListGroupBySchema = z
       .optional()
       .describe('Explicit ordering of group values; unlisted groups appear afterwards alphabetically'),
     labels: z
-      .record(z.string())
+      .record(LocalizedStringSchema)
       .optional()
       .describe('Human-friendly labels per group value (rendered as section headers)'),
   })
@@ -115,8 +108,16 @@ export const ToolSettingsViewSchema = z
 export const ToolSettingsViewDefinitionSchema = z
   .object({
     id: z.string().describe('Unique view ID within the extension'),
-    title: z.string().describe('Display title'),
-    description: z.string().optional().describe('Help text'),
+    title: LocalizedStringSchema.describe('Display title'),
+    description: LocalizedStringSchema.optional().describe('Help text'),
+    // A string rather than the known topics: one this host does not know yet must not stop
+    // the extension installing, it only lands on the extension's own page.
+    topic: z
+      .string()
+      .optional()
+      .describe(
+        'What the view is about, which decides where Stina shows it: accounts, notifications, personal or tracking. Without one, or with one Stina does not know, the view is shown on the extension\'s own page.'
+      ),
     view: ToolSettingsViewSchema.describe('View configuration'),
   })
   .describe('Tool settings view definition')
@@ -170,7 +171,7 @@ export const PanelViewSchema = z
 export const PanelDefinitionSchema = z
   .object({
     id: z.string().describe('Unique panel ID within the extension'),
-    title: z.string().describe('Display title'),
+    title: LocalizedStringSchema.describe('Display title'),
     icon: z.string().optional().describe('Icon name (from huge-icons)'),
     view: PanelViewSchema.describe('Panel view schema'),
   })
@@ -188,7 +189,7 @@ export const PanelDefinitionSchema = z
 export const StatusCardDefinitionSchema = z
   .object({
     id: z.string().describe('Unique card ID within the extension'),
-    title: z.string().describe('What it is called where the user picks it'),
+    title: LocalizedStringSchema.describe('What it is called where the user picks it'),
     icon: z.string().optional().describe('Icon name (from huge-icons)'),
     size: z
       .enum(['line', 'block'])

package/src/schemas/localization.schema.ts

@@ -0,0 +1,15 @@
+/**
+ * Localization Schema
+ *
+ * Kept apart so both the component and the contribution schemas can use it without importing
+ * each other.
+ */
+
+import { z } from 'zod'
+
+/**
+ * Localized string - either a simple string or a map of language codes to strings
+ */
+export const LocalizedStringSchema = z
+  .union([z.string(), z.record(z.string())])
+  .describe('String or localized string map')