@genesislcap/ai-assistant 14.458.3 → 14.460.0

package/src/main/main.types.ts

@@ -53,24 +53,53 @@ export type SuggestionsState =
 export interface AiAssistantAnimationDef {
   /** Display label shown in the settings multiselect. */
   label: string;
-  /** Short description shown as a tooltip on the option. */
-  tooltip: string;
+  /** Short description shown beneath the label in the categorized multiselect. */
+  description: string;
+  /** Group heading the option is listed under in the settings multiselect. */
+  category: string;
 }
 
 /**
  * Registry of all available animations with their display metadata.
  * Adding an entry here automatically extends the {@link AiAssistantAnimation} type.
  *
+ * @remarks
+ * `loading` (dots), `waves`, `flowingWaves` and `plasma` are interchangeable
+ * styles of the same "is the assistant working" indicator and are therefore
+ * grouped under the same {@link AiAssistantAnimationDef.category}. They are
+ * mutually exclusive — see `LOADING_STYLE_ANIMATIONS`.
+ *
  * @beta
  */
 export const ANIMATION_DEFS = {
   loading: {
-    label: 'Loading indicator',
-    tooltip: 'Shows a pulsing animation while the assistant is generating a response.',
+    label: 'Dots',
+    description: 'Shows pulsing dots while the assistant is generating a response.',
+    category: 'Loading style',
+  },
+  waves: {
+    label: 'Waves',
+    description:
+      'Shows glowing sine waves inside a circle while the assistant is generating a response.',
+    category: 'Loading style',
+  },
+  flowingWaves: {
+    label: 'Flowing waves',
+    description:
+      'Shows coloured waves rising and settling from a line while the assistant is generating a response.',
+    category: 'Loading style',
+  },
+  plasma: {
+    label: 'Plasma orb',
+    description:
+      'Shows a glowing plasma sphere with drifting energy while the assistant is generating a response.',
+    category: 'Loading style',
   },
   halo: {
     label: 'Halo',
-    tooltip: 'Displays a glowing halo around the assistant avatar while a response is streaming.',
+    description:
+      'Displays a glowing halo around the assistant avatar while a response is streaming.',
+    category: 'Effects',
   },
 } satisfies Record<string, AiAssistantAnimationDef>;
 
@@ -87,3 +116,25 @@ export type AiAssistantAnimation = keyof typeof ANIMATION_DEFS;
  * @internal
  */
 export const ALL_ANIMATIONS = Object.keys(ANIMATION_DEFS) as AiAssistantAnimation[];
+
+/**
+ * The interchangeable "assistant is working" loading-indicator styles. At most
+ * one of these may be enabled at a time — enabling one disables the other.
+ *
+ * @internal
+ */
+export const LOADING_STYLE_ANIMATIONS = [
+  'loading',
+  'waves',
+  'flowingWaves',
+  'plasma',
+] as const satisfies readonly AiAssistantAnimation[];
+
+/**
+ * Animations enabled by default when a consumer opts into the animations
+ * feature without specifying an explicit `enabled` list. Keeps the dots loading
+ * style (the long-standing default); the waves style is opt-in.
+ *
+ * @internal
+ */
+export const DEFAULT_ANIMATIONS: AiAssistantAnimation[] = ['loading', 'halo'];

package/src/utils/animation-exclusivity.test.ts

@@ -0,0 +1,72 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import type { AiAssistantAnimation } from '../main/main.types';
+import { resolveExclusiveLoadingStyle } from './animation-exclusivity';
+
+const suite = createLogicSuite('resolveExclusiveLoadingStyle');
+
+suite('leaves a selection with only the dots loading style untouched', () => {
+  const next: AiAssistantAnimation[] = ['loading', 'halo'];
+  assert.equal(resolveExclusiveLoadingStyle(next, ['halo']), ['loading', 'halo']);
+});
+
+suite('leaves a selection with only the waves loading style untouched', () => {
+  const next: AiAssistantAnimation[] = ['waves', 'halo'];
+  assert.equal(resolveExclusiveLoadingStyle(next, ['halo']), ['waves', 'halo']);
+});
+
+suite('leaves a selection with no loading style untouched', () => {
+  assert.equal(resolveExclusiveLoadingStyle(['halo'], []), ['halo']);
+});
+
+suite('drops dots when waves was just added on top of dots', () => {
+  // Previously dots was on; user ticks waves → waves wins, dots removed.
+  const result = resolveExclusiveLoadingStyle(['loading', 'waves', 'halo'], ['loading', 'halo']);
+  assert.equal(result, ['waves', 'halo']);
+});
+
+suite('drops waves when dots was just added on top of waves', () => {
+  // Previously waves was on; user ticks dots → dots wins, waves removed.
+  const result = resolveExclusiveLoadingStyle(['loading', 'waves', 'halo'], ['waves', 'halo']);
+  assert.equal(result, ['loading', 'halo']);
+});
+
+suite('preserves the order of the surviving selection', () => {
+  const result = resolveExclusiveLoadingStyle(['halo', 'loading', 'waves'], ['halo', 'loading']);
+  // waves was just added → loading dropped; halo and waves keep their order.
+  assert.equal(result, ['halo', 'waves']);
+});
+
+suite('falls back to dots when both are present with no prior state (e.g. bad config)', () => {
+  const result = resolveExclusiveLoadingStyle(['loading', 'waves', 'halo'], []);
+  assert.equal(result, ['loading', 'halo']);
+});
+
+suite('falls back to dots when both were already present (neither newly added)', () => {
+  const result = resolveExclusiveLoadingStyle(['loading', 'waves'], ['loading', 'waves', 'halo']);
+  assert.equal(result, ['loading']);
+});
+
+suite('handles an empty selection', () => {
+  assert.equal(resolveExclusiveLoadingStyle([], ['loading']), []);
+});
+
+suite('switching between any two loading styles keeps only the newly added one', () => {
+  // flowingWaves was on; user picks plasma → plasma wins, flowingWaves dropped.
+  assert.equal(
+    resolveExclusiveLoadingStyle(['flowingWaves', 'plasma', 'halo'], ['flowingWaves', 'halo']),
+    ['plasma', 'halo'],
+  );
+  // plasma was on; user picks the dots → dots win, plasma dropped.
+  assert.equal(resolveExclusiveLoadingStyle(['plasma', 'loading'], ['plasma']), ['loading']);
+});
+
+suite('drops all but the newly added style when several are somehow selected', () => {
+  const result = resolveExclusiveLoadingStyle(
+    ['loading', 'waves', 'flowingWaves', 'plasma'],
+    ['loading', 'waves', 'plasma'],
+  );
+  // flowingWaves is the only one absent from `previous`, so it wins.
+  assert.equal(result, ['flowingWaves']);
+});
+
+suite.run();

package/src/utils/animation-exclusivity.ts

@@ -0,0 +1,40 @@
+import type { AiAssistantAnimation } from '../main/main.types';
+import { LOADING_STYLE_ANIMATIONS } from '../main/main.types';
+
+/**
+ * Enforces that at most one loading-indicator style (dots vs. waves) is enabled
+ * at a time. The two are alternative presentations of the same "assistant is
+ * working" state, so selecting one must deselect the other.
+ *
+ * The settings control is a multiselect (checkboxes), which permits selecting
+ * both; this resolver makes the loading-style group behave like a radio group
+ * by dropping the previously-selected style whenever a new one is added.
+ *
+ * @param next - The freshly-selected animation list (e.g. emitted by the
+ *   multiselect, or read from consumer config).
+ * @param previous - The animation list in effect before this change. Used to
+ *   work out which loading style was just added so the other can be dropped.
+ *   Pass `[]` when resolving an initial/config value with no prior state.
+ * @returns `next` with at most one loading style retained. When both are
+ *   present and neither is newly added (e.g. a misconfigured `enabled` list),
+ *   the first entry of `LOADING_STYLE_ANIMATIONS` (dots) wins.
+ *
+ * @internal
+ */
+export function resolveExclusiveLoadingStyle(
+  next: AiAssistantAnimation[],
+  previous: AiAssistantAnimation[] = [],
+): AiAssistantAnimation[] {
+  const selectedStyles = LOADING_STYLE_ANIMATIONS.filter((style) => next.includes(style));
+  if (selectedStyles.length <= 1) {
+    return next;
+  }
+  // Both styles selected — keep whichever was just added (absent from
+  // `previous`); fall back to the first declared style on ambiguity.
+  const justAdded = selectedStyles.find((style) => !previous.includes(style)) ?? selectedStyles[0];
+  return next.filter(
+    (animation) =>
+      animation === justAdded ||
+      !(LOADING_STYLE_ANIMATIONS as readonly AiAssistantAnimation[]).includes(animation),
+  );
+}