@genesislcap/ai-assistant 15.6.2 → 15.7.0

package/src/main/main.styles.test.ts

@@ -0,0 +1,103 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { styles } from './main.styles';
+
+// CSS is not otherwise unit-tested in this package, so this covers the two
+// properties of the BLOCKED BANNER that are cheap to assert from the generated
+// text and that a reviewer had to catch by eye:
+//
+//   1. Design-system tokens are consumed UNFALLBACKED, as every other rule in the
+//      file does. A `var(--token, fallback)` here is dead code at best — both
+//      tokens below ship with defaults — and actively wrong at worst: the blocked
+//      banner's old `var(--neutral-layer-2, transparent)` would, if it ever fired,
+//      have produced a banner with no surface at all.
+//   2. The blocked banner's visual treatment hangs off `.is-visible`, not the bare
+//      class, because the container stays mounted while unblocked so that its
+//      `role="status"` region is registered before the text arrives (see
+//      main.template.ts). Collapsing the empty container would undo that.
+//
+// Scope: the banner's own rules, and nothing else. Both negative assertions were
+// written for one component, but an earlier version grepped the WHOLE stylesheet
+// — quietly turning a banner test into a global style policy nobody agreed to, so
+// any future rule anywhere in an 800-line sheet that legitimately wanted a
+// fallback on either token would have failed a test named after the banner.
+
+const suite = createLogicSuite('main.styles blocked-banner rules');
+
+/**
+ * The generated stylesheet text. `css` composes nested `ElementStyles` (this file
+ * builds the sheet from several partials), so flatten recursively rather than
+ * only reading the top level — a shallow read silently returns almost nothing,
+ * which would make every `assert.not.ok` below pass vacuously. The first test
+ * guards exactly that.
+ */
+const flatten = (value: unknown): string => {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.map(flatten).join('\n');
+  const nested = (value as { styles?: unknown } | null | undefined)?.styles;
+  return nested ? flatten(nested) : '';
+};
+
+const cssText = flatten(styles);
+
+/**
+ * Every declaration block whose selector mentions `.blocked-banner`, joined.
+ *
+ * Deliberately crude — one regex over the generated text, no CSS parser — but
+ * enough to keep these assertions about the banner rather than about the whole
+ * sheet, which was the only thing wrong with them. It matches
+ * `<selector> { <declarations> }` for any selector containing `.blocked-banner`,
+ * so it picks up the bare class, the `.is-visible` / `.is-partial` modifiers, the
+ * shared composer-width group and the copy inside the container query alike.
+ */
+const bannerRules = (cssText.match(/[^{}]*\.blocked-banner[^{}]*\{[^}]*\}/g) ?? []).join('\n');
+
+/** Declarations of the bare-class rule — the one that applies while empty. */
+const emptyStateRule = cssText.match(/[\s{}](\.blocked-banner)\s*\{([^}]*)\}/)?.[2] ?? '';
+
+suite('the banner rules were extracted as text (guards the assertions below)', () => {
+  assert.ok(cssText.includes('.blocked-banner'), 'the banner rules are in the sheet');
+  assert.ok(bannerRules.includes('.is-visible'), 'the extraction found the modifier rules');
+  assert.ok(emptyStateRule.length > 0, 'and isolated the bare-class rule');
+});
+
+suite('the banner consumes design-system tokens without dead fallbacks', () => {
+  assert.not.ok(
+    bannerRules.includes('var(--neutral-layer-2,'),
+    '--neutral-layer-2 has a DS default and is used unfallbacked everywhere else here',
+  );
+  assert.not.ok(
+    bannerRules.includes('var(--warning-color,'),
+    '--warning-color has a DS default and is used unfallbacked by toast/badge styles',
+  );
+});
+
+suite('the blocked banner keeps its unblocked container visually inert', () => {
+  // `::part(blocked-banner)` matches at all times, so the empty state must set
+  // nothing that reserves space — and must not remove the container from the
+  // accessibility tree, which is where the `role="status"` region is registered.
+  //
+  // Asserted against the bare-class rule's own declarations rather than by
+  // grepping for a `:empty` selector nobody wrote: this catches the mistake as it
+  // would actually be made — a padding or border creeping onto the always-present
+  // container — instead of one specific spelling of it.
+  //
+  // `margin-block` rather than `margin`: the shared composer-width group sets
+  // `margin-inline: auto` on the banner along with the rest of the composer
+  // column, which centres it and reserves nothing.
+  assert.ok(cssText.includes('.blocked-banner.is-visible'), 'visuals hang off is-visible');
+  for (const property of ['display: none', 'padding', 'border', 'background', 'margin-block']) {
+    assert.not.ok(
+      emptyStateRule.includes(property),
+      `the always-present container must not set ${property} — that is .is-visible's job`,
+    );
+  }
+});
+
+suite('partial exhaustion has its own modifier, layered on the visible state', () => {
+  // `.is-visible` carries the layout and surface for BOTH states; `.is-partial`
+  // only softens it. Additive, never a replacement — so host CSS keyed on the
+  // visible state needs to know nothing about partial exhaustion.
+  assert.ok(cssText.includes('.blocked-banner.is-partial'), 'the partial modifier exists');
+});
+
+suite.run();

package/src/main/main.styles.ts

@@ -441,6 +441,7 @@ const baseStyles = css`
   .attachment-chips,
   .agent-picker-panel,
   .session-menu-panel,
+  .blocked-banner,
   chat-suggestions {
     box-sizing: border-box;
     width: 100%;
@@ -464,6 +465,13 @@ const baseStyles = css`
       border-radius: 12px;
     }
 
+    /* The banner joins the same floating-card family, but keeps its own
+       warning-toned border — overriding it with the neutral stroke would erase
+       the one colour signal it carries. Only the radius needs to match. */
+    .blocked-banner.is-visible {
+      border-radius: 12px;
+    }
+
     /* chat-suggestions paints its background on an inner element, so clip it to the
        rounded corners — otherwise that square inner background bleeds past the radius
        and the corners read as square with the border hidden behind them. */
@@ -617,6 +625,45 @@ const baseStyles = css`
     font-size: 0.9em;
   }
 
+  /* Backend-blocked banner (GENC-1464) — sits between the transcript and the
+     disabled composer. Flat and quiet rather than an error toast: the condition
+     is standing, not a momentary failure, so it should read as part of the
+     chrome the user is now working within. */
+
+  /* The container is ALWAYS in the DOM so the live region is registered before the
+     text arrives (see main.template.ts) — so the bare selector carries only layout,
+     and an unblocked banner is an empty, zero-height, invisible box. Everything
+     that would make it visible hangs off .is-visible. */
+  .blocked-banner {
+    display: flex;
+    align-items: center;
+    gap: calc(var(--design-unit) * 2px);
+  }
+
+  .blocked-banner.is-visible {
+    /* Block axis only. The inline-axis margin is owned by the composer width group
+       above (margin-inline: auto), which centres the banner on the same column as
+       the input row — an inline margin here would fight it. */
+    margin-block: calc(var(--design-unit) * 1px);
+    padding: calc(var(--design-unit) * 2px) calc(var(--design-unit) * 3px);
+    border: calc(var(--stroke-width) * 1px) solid var(--warning-color);
+    border-radius: calc(var(--control-corner-radius) * 1px);
+    background: var(--neutral-layer-2);
+    color: var(--neutral-foreground-rest);
+  }
+
+  /* Partial exhaustion: at least one vendor is walled but the composer is still
+     live, so the banner is advice rather than a wall. Softened to match — same
+     layout, same part, lower alarm. */
+  .blocked-banner.is-partial {
+    border-color: var(--neutral-stroke-rest);
+  }
+
+  .blocked-banner-text {
+    font-size: 0.9em;
+    line-height: 1.4;
+  }
+
   .chat-input {
     flex: 1;
     resize: none;

package/src/main/main.template.ts

@@ -274,6 +274,118 @@ const restoringTemplate = html<FoundationAiAssistant>`
   </div>
 `;
 
+/**
+ * Class list for the banner below, joined rather than interpolated so an
+ * inapplicable modifier contributes nothing. Two interpolations directly in the
+ * attribute emitted `class="blocked-banner  "` in the common (unblocked) case —
+ * harmless to the browser, but it shows up in every DOM snapshot and every
+ * innerHTML assertion a host writes against this element.
+ *
+ * The two modifiers name what they actually gate, which is why neither is
+ * `is-blocked`: `is-visible` means the banner has something to say, and that
+ * includes PARTIAL exhaustion — one vendor walled, composer still live, `blocked`
+ * false. `is-partial` then softens the treatment for exactly that case. Naming
+ * the first after `blocked` read as a contradiction beside the second, and made
+ * the styles say `.blocked-banner.is-blocked` to mean "visible".
+ *
+ * Exported for the unit test that pins the attribute; not part of the element
+ * API.
+ *
+ * @internal
+ */
+export const blockedBannerClasses = (x: FoundationAiAssistant): string =>
+  [
+    'blocked-banner',
+    x.bannerVisible ? 'is-visible' : '',
+    x.bannerVisible && !x.blocked ? 'is-partial' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+/**
+ * Id of the blocked banner, referenced by the composer controls'
+ * `aria-describedby`. Shadow-DOM-scoped, so a fixed string cannot collide with
+ * the host page — and IDREF resolution is same-root, which is exactly where both
+ * ends of this reference live.
+ *
+ * @internal
+ */
+export const BLOCKED_BANNER_ID = 'blocked-banner';
+
+/**
+ * `aria-describedby` for the composer's textarea, send button and attach button:
+ * the banner's id whenever the banner has something to say, otherwise `null` (so
+ * the attribute is omitted rather than emitted empty).
+ *
+ * Keyed on `bannerVisible`, NOT on `blocked`, and that is the point. The
+ * PARTIAL state — some vendor walled, composer still live — is the state this
+ * feature exists to create, and it was the one state with no accessible
+ * explanation at all: `aria-disabled` and `aria-label` bind only on `blocked`, and
+ * a live composer keeps the host's own placeholder, so a screen-reader user
+ * arriving at the textarea heard "Type a message" with no hint that the next turn
+ * might be refused. The banner's `role="status"` announces the text when it
+ * CHANGES; this is what makes the same explanation reachable afterwards, on
+ * demand, from the control it is about.
+ *
+ * Applied in the fully blocked state too, where it is additive: the `aria-label`
+ * there states the reason as the control's name, and this restates it as its
+ * description for the send/attach buttons, which carry neither.
+ *
+ * Exported for the unit test that pins it; not part of the element API.
+ *
+ * @internal
+ */
+export const composerDescribedBy = (x: FoundationAiAssistant): string | null =>
+  x.bannerVisible ? BLOCKED_BANNER_ID : null;
+
+/**
+ * Persistent banner shown above the composer while a backend condition blocks
+ * the assistant — today an exhausted AI budget (GENC-1464).
+ *
+ * Deliberately NOT a transcript replacement like `compactingTemplate` /
+ * `restoringTemplate`: those cover a transient rewrite where the history is
+ * mid-flight and unsafe to show, whereas a block is indefinite. Hiding the
+ * conversation behind it would strand the user's work behind a wall they
+ * cannot clear, so the banner sits alongside a fully readable transcript.
+ *
+ * `role="status"` (not `alert`) — it is a standing condition the user can also
+ * see in the disabled composer, not an interruption.
+ *
+ * **Rendered unconditionally, empty when unblocked.** This is an accessibility
+ * requirement, not a stylistic choice: `role="status"` announces MUTATIONS to a
+ * region the assistive technology was already observing. A region INSERTED into
+ * the DOM already carrying its text is widely missed across NVDA, JAWS and
+ * VoiceOver — and it is the only announcement a screen-reader user gets, since
+ * the textarea simultaneously flips to `disabled`, which drops it out of the tab
+ * order and means the swapped "AI usage limit reached" placeholder is never
+ * voiced (`maybeAutoFocusChatInput` also no-ops against a disabled control). So
+ * the region stays mounted and only its TEXT changes.
+ *
+ * It is deliberately **not** collapsed with `display: none` when unblocked —
+ * that would drop it out of the accessibility tree and make the flip an
+ * insertion again, defeating the point. Instead the visual treatment (padding,
+ * border, background) hangs off the `is-visible` class, so the empty container
+ * occupies no space while remaining a live, registered region.
+ *
+ * It carries {@link BLOCKED_BANNER_ID} so the composer controls can point
+ * `aria-describedby` at it — see {@link composerDescribedBy}.
+ */
+const blockedBannerTemplate = html<FoundationAiAssistant>`
+  <div
+    id="${BLOCKED_BANNER_ID}"
+    class="${blockedBannerClasses}"
+    part="blocked-banner"
+    role="status"
+  >
+    ${when(
+      (x) => x.bannerVisible,
+      html<FoundationAiAssistant>`
+        <span class="blocked-banner-text">${(x) => x.effectiveBlockedReason}</span>
+      `,
+    )}
+  </div>
+`;
+
 // ─── Public factory ───────────────────────────────────────────────────────────
 
 /** @internal */
@@ -437,13 +549,18 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
     </${buttonTag}>
   `;
 
+  // The attach button shares the textarea's disable gate. Attaching a file that
+  // can never be sent is a dead end — and `blocked`, `compacting` and `restoring`
+  // were all missing from it, so files could be attached during a compaction or
+  // against an exhausted budget and then never sent.
   const attachButtonTemplate = html<FoundationAiAssistant>`
     <${buttonTag}
       class="attach-button"
       part="attach-button"
       appearance="stealth"
       title=${(x) => `Attach file (${x.chatConfig.ui?.acceptedFiles})`}
-      ?disabled=${(x) => x.busy}
+      ?disabled=${(x) => x.busy || x.compacting || x.restoring || x.blocked}
+      aria-describedby=${composerDescribedBy}
       @click=${(x) => x.triggerFileInput()}
     ><${iconTag} name="paperclip"></${iconTag}></${buttonTag}>
   `;
@@ -697,7 +814,7 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
         `,
       )}
       ${when(
-        (x) => x.chatConfig.suggestions?.behavior !== 'never',
+        (x) => x.chatConfig.suggestions?.behavior !== 'never' && !x.suggestionsBlocked,
         html<FoundationAiAssistant>`
           <chat-suggestions
             :state="${(x) => x.suggestionsState}"
@@ -710,6 +827,12 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
         (x) => x.sessionMenuOpen && !x.busy,
         sessionMenuPanelTemplate,
       )}
+      ${
+        /* Rendered above the composer and independently of it — a host that hides the
+           built-in composer (`composerHiddenByConfig`) still needs to be told why its own
+           input is being refused. */ ''
+      }
+      ${blockedBannerTemplate}
       ${when(
         (x) =>
           !x.composerHiddenByConfig &&
@@ -743,7 +866,10 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
               style=${(x) => x.composerHeightStyle}
               placeholder=${(x) => x.effectivePlaceholder}
               :value=${(x) => x.inputValue}
-              ?disabled=${(x) => x.busy || x.compacting || x.restoring}
+              ?disabled=${(x) => x.busy || x.compacting || x.restoring || x.blocked}
+              aria-disabled=${(x) => (x.blocked ? 'true' : null)}
+              aria-label=${(x) => (x.blocked ? x.effectiveBlockedReason : null)}
+              aria-describedby=${composerDescribedBy}
               @input=${(x, c) => (x.inputValue = (c.event.target as any).value)}
               @keydown=${(x, c) => {
                 if (
@@ -782,7 +908,8 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
               <${buttonTag}
                 class="send-button"
                 part="send-button"
-                ?disabled=${(x) => x.busy || x.compacting || x.restoring || (!x.inputValue.trim() && !x.attachments.length)}
+                ?disabled=${(x) => x.busy || x.compacting || x.restoring || x.blocked || (!x.inputValue.trim() && !x.attachments.length)}
+                aria-describedby=${composerDescribedBy}
                 @click=${(x) => x.handleSendClick()}
               >Send</${buttonTag}>
             </div>