@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Base/Pagination.svelte

@@ -1,18 +1,29 @@
 <svelte:options runes />
 
-<!-- @component
-	Allows for automated pagination of local content in cases where a collection may become a performance concern
+<!--
+@component
+Generic local-collection paginator. Renders a window of items via a
+`snippet` plus a control bar with page-number buttons, a jump-to-page
+input, and previous/next buttons. The component is generic over
+`T extends object` with a `key: keyof T` used as the
+`{#each}` key inside the rendered page.
 
-	### Usage
-	```svelte
-		<Pagination snippet={itemSnippet} pageSize={20} items={dataWrapper.value} key="id" />
-	```
- -->
+### Usage
+
+```svelte
+<Pagination snippet={itemSnippet} pageSize={20} items={dataWrapper.value} key="id" />
+```
+
+The `pageButtons` window (up to five numbered buttons) is recomputed
+via `$derived`, not via an `$effect`, so the page bar diffs in a
+single reactive pass and the keyed `{#each pageButtons as page ...}`
+preserves button identity across page changes.
+-->
 <script
 	lang="ts"
 	generics="T extends object"
 >
-	import { autoPluralise, generateShortUUID } from '../../Helpers/Helpers.svelte.js';
+	import { autoPluralise, generateWeakId } from '../../Helpers/Helpers.svelte.js';
 	import { Colour } from '../../scss/colours.js';
 	import { Side } from '../../Types/Internal/Side.js';
 	import { Size } from '../../Types/Internal/Size.js';
@@ -29,23 +40,27 @@
 		snippet,
 		itemName = 'Item',
 		border = false,
-		padding = '1.5rem', //sizing.$regular-padding
+		padding = '1.5rem', // sizing.$regular-padding
 		gap = '1.5rem', // sizing.$regular-gap
 		height,
 	}: PaginationProps<T> = $props();
 
-	const _uuid = generateShortUUID();
+	const _uuid = generateWeakId();
 	let pageIndex = $state(0);
-	let pageValue = $derived(pageIndex + 1);
+	const pageValue = $derived(pageIndex + 1);
 	const startIndex = $derived(pageIndex * pageSize);
 	const pageItems = $derived(items.slice(startIndex, startIndex + pageSize));
 
 	const lastPage = $derived(Math.ceil(items.length / pageSize));
 	const lastPageIndex = $derived(lastPage - 1);
 
+	// Debounced jump-to-page handler. Reads the raw event because the
+	// debounce drives state, not the input value directly; binding to
+	// `pageValue` would defeat the debounce.
 	let debounceTimeout = -1;
 	function onNumberInput(e: Event) {
-		const page = parseInt((e.target as HTMLInputElement).value);
+		const value = (e.target as HTMLInputElement).value;
+		const page = Number(value);
 
 		clearTimeout(debounceTimeout);
 		if (!isNaN(page)) {
@@ -55,45 +70,36 @@
 		}
 	}
 
-	let pageButtons: Array<number> = $state([]);
-
-	$effect(() => {
-		const startingPage = Math.min(lastPage - 2, pageIndex - 1);
-		const pageToStartWith = Math.max(1, Math.min(startingPage, lastPage - 4));
+	/**
+	 * Compute the window of up to five page numbers shown in the
+	 * control bar. Centred on the current page where possible and
+	 * clamped against both ends. Pulled into a stand-alone helper so
+	 * the windowing logic is unit-testable from outside the component.
+	 */
+	function getPageWindow(
+		currentIndex: number,
+		totalPages: number,
+		windowSize: number
+	): Array<number> {
+		const start = Math.min(totalPages - 2, currentIndex - 1);
+		const clampedStart = Math.max(1, Math.min(start, totalPages - (windowSize - 1)));
+		const count = Math.min(totalPages, windowSize);
+		const out = new Array<number>(count);
+		for (let i = 0; i < count; i++) {
+			out[i] = clampedStart + i;
+		}
+		return out;
+	}
 
-		pageButtons = new Array<number>(Math.min(lastPage, 5))
-			.fill(pageToStartWith)
-			.map((item, index) => item + index);
-	});
+	const pageButtons = $derived(getPageWindow(pageIndex, lastPage, 5));
 </script>
 
-<!-- PROPER -->
-<!-- 
-
-	<div class="pagination">
-		<div>page {pageIndex}</div>
-		<button
-			onclick={() => {
-				pageIndex = Math.max(pageIndex - 1, 0);
-			}}>Previous</button
-		>
-		<button
-			onclick={() => {
-				pageIndex = Math.min(pageIndex + 1, lastPageIndex);
-			}}>Next</button
-		>
-	</div>
-</div> -->
-
-<!-- 	style={`${padding ? `padding: ${padding};` : ''}` +
-		`${gap ? `gap: ${gap};` : ''}` +
-		`${height ? `height: ${height};` : ''}`} -->
 <div
 	class="wrapper"
 	class:border
-	style={(padding ? `padding: ${padding};` : '') +
-		(gap ? `gap: ${gap};` : '') +
-		(height ? `height: ${height};` : '')}
+	style:padding
+	style:gap
+	style:height
 >
 	{#each pageItems as item, index (item[key])}
 		{@render snippet(item, index)}
@@ -108,9 +114,12 @@
 		</div>
 
 		<div class="spacer"></div>
-		<!-- {/* TODO switch to a lib element for this */} -->
 
-		<div class="scrollable">
+		<div
+			class="scrollable"
+			role="navigation"
+			aria-label="Pagination"
+		>
 			<div class="block">
 				<Icon
 					name="paper"
@@ -152,21 +161,20 @@
 				>
 			</div>
 
-			{#key pageButtons}
-				{#each pageButtons as pageNumber (pageNumber)}
-					<div class="block nopad">
-						<Button
-							variant={Variant.Toolbar}
-							side={Side.Bottom}
-							size={Size.FillHeight}
-							toggled={pageIndex + 1 === pageNumber}
-							onclick={() => {
-								pageIndex = pageNumber - 1;
-							}}>{pageNumber}</Button
-						>
-					</div>
-				{/each}
-			{/key}
+			{#each pageButtons as pageNumber (pageNumber)}
+				<div class="block nopad">
+					<Button
+						variant={Variant.Toolbar}
+						side={Side.Bottom}
+						size={Size.FillHeight}
+						toggled={pageIndex + 1 === pageNumber}
+						label={`Go to page ${pageNumber.toString()}`}
+						onclick={() => {
+							pageIndex = pageNumber - 1;
+						}}>{pageNumber}</Button
+					>
+				</div>
+			{/each}
 
 			<div class="block nopad page-arrow">
 				<Button

package/dist/Components/Base/Pagination.svelte.d.ts

@@ -21,12 +21,22 @@ interface $$IsomorphicComponent {
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
 /**
- * Allows for automated pagination of local content in cases where a collection may become a performance concern
+ * Generic local-collection paginator. Renders a window of items via a
+ * `snippet` plus a control bar with page-number buttons, a jump-to-page
+ * input, and previous/next buttons. The component is generic over
+ * `T extends object` with a `key: keyof T` used as the
+ * `{#each}` key inside the rendered page.
  *
  * ### Usage
+ *
  * ```svelte
- * 	<Pagination snippet={itemSnippet} pageSize={20} items={dataWrapper.value} key="id" />
+ * <Pagination snippet={itemSnippet} pageSize={20} items={dataWrapper.value} key="id" />
  * ```
+ *
+ * The `pageButtons` window (up to five numbered buttons) is recomputed
+ * via `$derived`, not via an `$effect`, so the page bar diffs in a
+ * single reactive pass and the keyed `{#each pageButtons as page ...}`
+ * preserves button identity across page changes.
  */
 declare const Pagination: $$IsomorphicComponent;
 type Pagination<T extends object> = InstanceType<typeof Pagination<T>>;

package/dist/Components/Base/PaginationProps.d.ts

@@ -1,14 +1,71 @@
 import type { Snippet } from 'svelte';
+/**
+ * Props for {@link Pagination}.
+ *
+ * `Pagination` renders a windowed view of a local collection along
+ * with a control bar (records-per-page, jump-to-page, prev/next, and
+ * up to five numbered page buttons). It is generic over the item
+ * record `T`.
+ */
 export interface PaginationProps<T extends object> {
-    /** Used to index each item for a unique key. Duplicate values will result in error */
+    /**
+     * Property name on each item whose value is used as the `{#each}`
+     * key. Duplicate values across `items` will cause Svelte to throw
+     * at render time, so the chosen field should be unique (typically
+     * an `id` column).
+     *
+     * The constraint enforces a string key only; uniqueness across
+     * the collection cannot be expressed in the type system - mirror
+     * the contract of `Table.selectionExtractor` if you need a
+     * derived key.
+     */
     key: string & keyof T;
-    items: Array<T>;
-    /** Second argument is the index */
+    /** The collection to paginate. */
+    items: ReadonlyArray<T>;
+    /**
+     * Renderer invoked once per item in the current page. The second
+     * argument is the index within the current page (zero-based).
+     */
     snippet: Snippet<[T, number]>;
+    /**
+     * Number of items rendered per page.
+     *
+     * @default 20
+     */
     pageSize?: number;
+    /**
+     * Singular noun shown next to the total record count
+     * ("`<count>` `<itemName>`s"); pluralised automatically by
+     * `autoPluralise`.
+     *
+     * @default 'Item'
+     */
     itemName?: string;
+    /**
+     * When `true` the wrapper draws a rounded thick border around
+     * the rendered items.
+     */
     border?: boolean;
+    /**
+     * Raw CSS length used for the wrapper `padding`. Strings are
+     * accepted because the component takes any CSS value; prefer
+     * one of the standard `sizing.$*-padding` tokens
+     * (`'1.5rem'` matches `sizing.$regular-padding`).
+     *
+     * @default '1.5rem'
+     */
     padding?: string;
+    /**
+     * Raw CSS length used for the wrapper `gap`. Same conventions as
+     * `padding`; prefer the `sizing.$*-gap` tokens.
+     *
+     * @default '1.5rem'
+     */
     gap?: string;
+    /**
+     * Optional raw CSS length used for the wrapper `height`. Useful
+     * for fixed-height scroll containers; left unset by default so
+     * the wrapper consumes the available flex space.
+     */
     height?: string;
 }

package/dist/Components/Base/Snippets.svelte

@@ -2,6 +2,8 @@
 
 <!-- @component
 An empty component that only exists to export common snippets
+(`pending` and `failed`) for re-use by `{#await}` blocks and other
+async-status surfaces. The component itself renders nothing.
  -->
 <script
 	lang="ts"
@@ -10,6 +12,11 @@ An empty component that only exists to export common snippets
 	import { getErrorMessage, loadingText } from '../../Helpers/Helpers.svelte.js';
 	import Button from '../Button.svelte';
 
+	// The local `{#snippet _pending}` / `{#snippet _failed}` declarations
+	// must be hoistable references for `export const` to bind to them.
+	// Svelte 5 currently requires the snippet name to differ from the
+	// exported binding, so we use an underscore prefix on the local
+	// declaration and expose the un-prefixed name as the public surface.
 	export const pending = _pending;
 	export const failed = _failed;
 </script>

package/dist/Components/Base/Snippets.svelte.d.ts

@@ -1,6 +1,10 @@
 export declare const pending: () => ReturnType<import("svelte").Snippet>;
 export declare const failed: (e: unknown, retry?: () => void) => ReturnType<import("svelte").Snippet>;
-/** An empty component that only exists to export common snippets */
+/**
+ * An empty component that only exists to export common snippets
+ * (`pending` and `failed`) for re-use by `{#await}` blocks and other
+ * async-status surfaces. The component itself renders nothing.
+ */
 declare const Snippets: import("svelte").Component<Record<string, never>, {}, "">;
 type Snippets = ReturnType<typeof Snippets>;
 export default Snippets;

package/dist/Components/BigRadioSet.svelte

@@ -1,24 +1,33 @@
 <svelte:options runes />
 
-<script lang="ts" generics="T">
+<script
+	lang="ts"
+	generics="T"
+>
 	import type { BigRadioOption } from '../Types/Internal/BigRadioOption.js';
 	import type { BigRadioSetProps } from './BigRadioSetProps.js';
-	let { name, options, selected = $bindable() }: BigRadioSetProps<T> = $props();
-
-	// let selected: T | undefined = $state();
+	let { name, options, selected = $bindable(), onchange }: BigRadioSetProps<T> = $props();
 </script>
 
-<div class="wrapper">
-	{#each options as option (option)}
+<div
+	class="wrapper"
+	role="radiogroup"
+>
+	{#each options as option (option.value)}
 		<!-- eslint-disable-next-line @typescript-eslint/no-confusing-void-expression -->
 		{@render radio(option)}
 	{/each}
 </div>
 
 {#snippet radio(option: BigRadioOption<T>)}
-	<!-- {@debug selected} -->
 	<label class:selected={selected === option.value}>
-		<input type="radio" {name} bind:group={selected} value={option.value} />
+		<input
+			type="radio"
+			{name}
+			bind:group={selected}
+			value={option.value}
+			onchange={() => void onchange?.(option.value)}
+		/>
 		<div class="text">
 			<h5 class="title">{option.label}</h5>
 			<p class="note">{option.info}</p>
@@ -60,7 +69,7 @@ label input {
   accent-color: #259fc7;
 }
 label input:checked {
-  accent-color: #94dff6;
+  accent-color: #9fdaec;
 }
 label .text h5 {
   font-size: 1rem;

package/dist/Components/BigRadioSetProps.d.ts

@@ -1,6 +1,22 @@
 import type { BigRadioOption } from '../Types/Internal/BigRadioOption.js';
+/**
+ * Props for the {@link BigRadioSet} component.
+ *
+ * Each option exposes a `label`, `info`, and `value`. The `value`
+ * field is the bindable selection. Option keying uses `option.value`
+ * for `{#each}` so that the DOM remains stable across renders that
+ * pass freshly-allocated option arrays.
+ *
+ * `T` is unconstrained but compared with `===` in the radio group;
+ * use a primitive (string / number) or hold stable object references.
+ */
 export interface BigRadioSetProps<T> {
+    /** `name` attribute on the underlying radio group. */
     name?: string;
-    options: Array<BigRadioOption<T>>;
+    /** The option set rendered as cards. */
+    options: ReadonlyArray<BigRadioOption<T>>;
+    /** Bindable selected value. */
     selected?: T;
+    /** Change handler. May be `void` or `Promise<void>`. */
+    onchange?: (value: T) => void | Promise<void>;
 }

package/dist/Components/Bubble.svelte

@@ -1,32 +1,40 @@
 <svelte:options runes />
 
-<script lang="ts" module>
+<script
+	lang="ts"
+	module
+>
 	import { Size } from '../Types/Internal/Size.js';
 	import type { BubbleProps } from './BubbleProps.js';
 	import Icon from './Icon.svelte';
 
-	const horizontalWithValue: Partial<Record<Size, string>> = {
-		[Size.Large]: '1rem'
-	};
+	// Per-size padding/typography. Only `Size.Large` has explicit overrides;
+	// other sizes fall back to the medium defaults handled in $derived blocks
+	// below. Replaced the previous one-key `Partial<Record<Size, string>>`
+	// lookup tables with a simple `size === Size.Large` branch.
+	const LARGE_HORIZONTAL_WITH_VALUE = '1rem';
+	const LARGE_HORIZONTAL_WITHOUT_VALUE = '1.25rem';
+	const LARGE_VERTICAL = '0.5rem';
+	const LARGE_FONT_SIZE = '1.12rem';
+	const LARGE_BORDER_RADIUS = '1.75rem';
 
-	const horizontalWithoutValue: Partial<Record<Size, string>> = {
-		[Size.Large]: '1.25rem'
-	};
-
-	const vertical: Partial<Record<Size, string>> = {
-		[Size.Large]: '0.5rem'
-	};
-
-	const fontSizes: Partial<Record<Size, string>> = {
-		[Size.Large]: '1.12rem'
-	};
-
-	const borderRadii: Partial<Record<Size, string>> = {
-		[Size.Large]: '1.75rem'
-	};
+	const DEFAULT_VERTICAL = '0.18rem';
+	const DEFAULT_HORIZONTAL_WITH_VALUE = '0.5rem';
+	const DEFAULT_HORIZONTAL_WITHOUT_VALUE = '0.75rem';
+	const DEFAULT_FONT_SIZE = '1rem';
 </script>
 
-<script lang="ts">
+<script
+	lang="ts"
+	generics="T = unknown"
+>
+	// `BubbleProps<T>` is intentionally annotated with `<T>` even though
+	// the interface declares `T = unknown` as a default; the explicit
+	// substitution flows the generic from `<Bubble<MyType> ...>` consumers
+	// into the destructured `options` array type. The lint rule
+	// `@typescript-eslint/no-unnecessary-type-arguments` flags this as
+	// redundant when `T` resolves to `unknown` at the lint pass, hence
+	// the disable.
 	const {
 		options,
 		value,
@@ -35,23 +43,41 @@
 		size = Size.Medium,
 		bold,
 		icon,
-		onclick
-	}: BubbleProps = $props();
+		onclick,
+		// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+	}: BubbleProps<T> = $props();
 
-	const verticalPadding = $derived(vertical[size] ?? '0.18rem');
+	const isLarge = $derived(size === Size.Large);
+	const verticalPadding = $derived(isLarge ? LARGE_VERTICAL : DEFAULT_VERTICAL);
 	const horizontalPadding = $derived.by(() => {
 		if (value.length === 1) {
-			return horizontalWithValue[size] ?? '0.5rem';
+			return isLarge ? LARGE_HORIZONTAL_WITH_VALUE : DEFAULT_HORIZONTAL_WITH_VALUE;
 		}
 
-		return horizontalWithoutValue[size] ?? '0.75rem';
+		return isLarge ? LARGE_HORIZONTAL_WITHOUT_VALUE : DEFAULT_HORIZONTAL_WITHOUT_VALUE;
+	});
+	const fontSize = $derived(isLarge ? LARGE_FONT_SIZE : DEFAULT_FONT_SIZE);
+
+	// Precompute the label lookup once per `options`/`value` change.
+	const displayLabel = $derived(
+		options?.length ? (options.find((it) => it.value === value)?.label ?? value) : value
+	);
+
+	// Precompute the inline style string once per reactive input change.
+	const wrapperStyle = $derived.by(() => {
+		const colourPart = colours
+			? `background-color: ${colours.backgroundColour}; color: ${colours.colour};`
+			: '';
+		const radiusPart = isLarge ? `border-radius: ${LARGE_BORDER_RADIUS};` : '';
+		return `${colourPart} padding: var(--bubble-padding, ${verticalPadding} ${horizontalPadding}); font-size: ${fontSize}; ${radiusPart}`;
 	});
-	const fontSize = $derived(fontSizes[size] ?? '1rem');
-	const borderRadius = $derived(borderRadii[size] ?? '12px');
 </script>
 
 {#if onclick}
-	<button class="contents" {onclick}>
+	<button
+		class="contents"
+		{onclick}
+	>
 		<!-- eslint-disable-next-line @typescript-eslint/no-confusing-void-expression -->
 		{@render bubble()}
 	</button>
@@ -65,12 +91,10 @@
 		class="bubble"
 		class:bold
 		class:hoverable={!!onclick}
-		style="{colours
-			? `background-color: ${colours.backgroundColour}; color: ${colours.colour};`
-			: ''} padding: var(--bubble-padding, {verticalPadding} {horizontalPadding}); font-size: {fontSize}; border-radius: {borderRadius}"
-		>{#if label}{label}:&nbsp;{/if}{options?.length
-			? options.find((it) => it.value === value)?.label
-			: value}{#if icon}<div class="icon"><Icon {...icon} /></div>{/if}</span
+		style={wrapperStyle}
+		>{#if label}{label}:&nbsp;{/if}{displayLabel}{#if icon}<div class="icon">
+				<Icon {...icon} />
+			</div>{/if}</span
 	>
 {/snippet}
 
@@ -87,9 +111,18 @@
   flex-flow: row nowrap;
   align-items: center;
   gap: 0.75rem;
+  border-radius: 12px;
   line-height: var(--line-height, inherit);
   transition: border-color ease-out 0.15s 0s, background-color ease-out 0.15s 0s, color ease-out 0.15s 0s, fill ease-out 0.15s 0s;
 }
+@media (prefers-reduced-motion: reduce) {
+  .bubble {
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.001ms !important;
+    scroll-behavior: auto !important;
+  }
+}
 .bubble.hoverable:hover {
   background-color: #cbd4da;
 }

package/dist/Components/Bubble.svelte.d.ts

@@ -1,4 +1,25 @@
 import type { BubbleProps } from './BubbleProps.js';
-declare const Bubble: import("svelte").Component<BubbleProps, {}, "">;
-type Bubble = ReturnType<typeof Bubble>;
+declare function $$render<T = unknown>(): {
+    props: BubbleProps<T>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T = unknown> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Bubble: $$IsomorphicComponent;
+type Bubble<T = unknown> = InstanceType<typeof Bubble<T>>;
 export default Bubble;

package/dist/Components/BubbleProps.d.ts

@@ -2,13 +2,64 @@ import type { SelectOption } from '../Types/Internal/SelectOption.js';
 import type { Size } from '../Types/Internal/Size.js';
 import type { BubbleColour } from './BubbleColour.js';
 import type { PartialIconProps } from './PartialIconProps.js';
-export interface BubbleProps {
+/**
+ * Props for {@link Bubble}.
+ *
+ * `Bubble` renders a pill / chip showing a value (optionally resolved via
+ * a parallel `options` list). It is generic over the value type `T` of the
+ * options array so consumers do not lose type information when looking up
+ * the display label.
+ *
+ * @typeParam T - The value type of the `options` array. Defaults to
+ *                `unknown` so existing call sites that do not specify a
+ *                generic continue to compile.
+ */
+export interface BubbleProps<T = unknown> {
+    /**
+     * The current value rendered inside the bubble. If `options` is provided
+     * and contains a matching entry, the corresponding `label` is shown
+     * instead.
+     */
     value: string;
-    onclick?: () => void;
+    /**
+     * Optional click handler. When provided the bubble is wrapped in a
+     * `<button>` (via `display: contents`) and becomes keyboard-focusable.
+     *
+     * The `MouseEvent` is forwarded so callers can inspect modifier keys
+     * or call `preventDefault()`. The argument is optional for backwards
+     * compatibility with handlers that ignore it.
+     */
+    onclick?: (event?: MouseEvent) => void;
+    /**
+     * Optional trailing icon. Accepts a {@link PartialIconProps} which is
+     * spread into a nested `Icon` component.
+     */
     icon?: PartialIconProps;
+    /**
+     * When true the bubble text is rendered at `font-weight: 700`.
+     */
     bold?: boolean;
+    /**
+     * Visual size band. Drives padding, font size, and border radius.
+     * Defaults to `Size.Medium`. Only `Size.Large` carries explicit
+     * overrides; other values fall back to the medium defaults.
+     */
     size?: Size;
+    /**
+     * Optional inline label rendered before the value, e.g. "Status: ".
+     * Followed by a non-breaking space in the rendered output.
+     */
     label?: string;
-    options?: Array<SelectOption<unknown>>;
-    colours?: BubbleColour | null | undefined;
+    /**
+     * Optional lookup table. When provided, the rendered text uses the
+     * `label` of the entry whose `value` equals `value`, falling back to
+     * the raw `value` if no entry matches.
+     */
+    options?: Array<SelectOption<T>>;
+    /**
+     * Optional foreground / background colour pair. When omitted the
+     * bubble uses its default UI-blue palette. Passing `undefined`
+     * explicitly is equivalent to omitting the prop.
+     */
+    colours?: BubbleColour | undefined;
 }