@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/ChatBubble/ChatBubble.module.scss

@@ -0,0 +1,93 @@
+@use './ChatBubble.tokens';
+
+// Full-width row; the member/assistant side is justify-content, not align-self
+// (Rule 4: the component never positions itself in its parent).
+.bubble {
+  display: flex;
+  width: 100%;
+}
+
+.member {
+  justify-content: flex-end;
+}
+
+.assistant {
+  justify-content: flex-start;
+}
+
+.column {
+  display: flex;
+  flex-direction: column;
+  gap: var(--chat-bubble-gap);
+  max-width: var(--chat-bubble-max-width);
+}
+
+.member .column {
+  align-items: flex-end;
+}
+
+.assistant .column {
+  align-items: flex-start;
+}
+
+.body {
+  padding: var(--chat-bubble-padding-y) var(--chat-bubble-padding-x);
+  border-radius: var(--chat-bubble-radius);
+  color: var(--chat-bubble-fg);
+  overflow-wrap: anywhere;
+}
+
+.member .body {
+  background: var(--chat-bubble-member-bg);
+}
+
+.assistant .body {
+  background: var(--chat-bubble-assistant-bg);
+}
+
+.dots {
+  display: inline-flex;
+  gap: var(--chat-bubble-dot-gap);
+  align-items: center;
+}
+
+.dot {
+  width: var(--chat-bubble-dot-size);
+  height: var(--chat-bubble-dot-size);
+  border-radius: var(--radius-full);
+  background: var(--chat-bubble-dot-color);
+  animation: chat-bubble-dot 1.2s ease-in-out infinite;
+
+  &:nth-child(2) {
+    animation-delay: 0.2s;
+  }
+
+  &:nth-child(3) {
+    animation-delay: 0.4s;
+  }
+}
+
+@keyframes chat-bubble-dot {
+  0%,
+  80%,
+  100% {
+    opacity: var(--chat-bubble-dot-opacity-low);
+  }
+
+  40% {
+    opacity: var(--chat-bubble-dot-opacity-high);
+  }
+}
+
+// Same specificity as .dot, later in source order: wins without !important.
+@media (prefers-reduced-motion: reduce) {
+  .dot {
+    animation: none;
+  }
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--chat-bubble-list-gap);
+}

package/src/components/ChatBubble/ChatBubble.tokens.scss

@@ -0,0 +1,17 @@
+// ChatBubble.tokens.scss — Component tokens for <ChatBubble> and <ChatBubble.List>. Default to primitives.
+:root {
+  --chat-bubble-max-width: 80%;
+  --chat-bubble-radius: var(--radius-lg);
+  --chat-bubble-padding-y: var(--space-2);
+  --chat-bubble-padding-x: var(--space-3);
+  --chat-bubble-gap: var(--space-1);
+  --chat-bubble-fg: var(--color-fg);
+  --chat-bubble-member-bg: var(--color-accent-subtle-bg);
+  --chat-bubble-assistant-bg: var(--color-bg-muted);
+  --chat-bubble-dot-size: var(--space-2);
+  --chat-bubble-dot-gap: var(--space-1);
+  --chat-bubble-dot-color: var(--color-fg-muted);
+  --chat-bubble-dot-opacity-high: var(--opacity-visible);
+  --chat-bubble-dot-opacity-low: var(--opacity-subtle);
+  --chat-bubble-list-gap: var(--space-3);
+}

package/src/components/ChatBubble/ChatBubble.tsx

@@ -0,0 +1,61 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n';
+import { VisuallyHidden } from '../VisuallyHidden';
+import { ChatBubbleList } from './ChatBubbleList';
+import styles from './ChatBubble.module.scss';
+
+/** Who a bubble is from: `member` (the signed-in user, aligned to the inline end) or `assistant` (aligned to the inline start). */
+export type ChatBubbleFrom = 'member' | 'assistant';
+
+export interface ChatBubbleProps extends HTMLAttributes<HTMLDivElement> {
+  /** Speaker. `member` = the user (accent tint, end side); `assistant` = the AI (neutral, start side). */
+  from: ChatBubbleFrom;
+  /** Message content. Ignored while `pending`. */
+  children?: ReactNode;
+  /** Slot below the coloured body, same side (feedback buttons, sources). */
+  footer?: ReactNode;
+  /**
+   * Show a "typing" indicator instead of `children`; announced once when
+   * inserted into a `ChatBubble.List`. Intended for `from="assistant"`.
+   * @default false
+   */
+  pending?: boolean;
+}
+
+const BubbleRoot = forwardRef<HTMLDivElement, ChatBubbleProps>(function ChatBubble(
+  { from, footer, pending = false, children, className, ...props },
+  ref,
+) {
+  const t = useTranslation();
+  return (
+    <div ref={ref} className={clsx(styles.bubble, styles[from], className)} {...props}>
+      <div className={styles.column}>
+        <div className={styles.body}>
+          {pending ? (
+            <>
+              <span className={styles.dots} aria-hidden="true">
+                <span className={styles.dot} />
+                <span className={styles.dot} />
+                <span className={styles.dot} />
+              </span>
+              <VisuallyHidden>{t('chatBubble.pending')}</VisuallyHidden>
+            </>
+          ) : (
+            <>
+              <VisuallyHidden>{t(`chatBubble.${from}`)}: </VisuallyHidden>
+              {children}
+            </>
+          )}
+        </div>
+        {footer}
+      </div>
+    </div>
+  );
+});
+
+/**
+ * One chat message bubble, aligned by speaker; `ChatBubble.List` is the live-region container.
+ * @see docs/components/ChatBubble.md
+ */
+export const ChatBubble = Object.assign(BubbleRoot, { List: ChatBubbleList });

package/src/components/ChatBubble/ChatBubbleList.tsx

@@ -0,0 +1,27 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './ChatBubble.module.scss';
+
+export interface ChatBubbleListProps extends HTMLAttributes<HTMLDivElement> {
+  /** The `ChatBubble`s of the conversation, oldest first. Pass an `aria-label` naming the conversation. */
+  children: ReactNode;
+}
+
+/**
+ * Vertical list of ChatBubbles that is also the `role="log"` live region announcing new messages.
+ * @see docs/components/ChatBubble.md
+ */
+export const ChatBubbleList = forwardRef<HTMLDivElement, ChatBubbleListProps>(
+  function ChatBubbleList({ className, ...props }, ref) {
+    // {...props} first so role/aria-live (the announcement contract) win.
+    return (
+      <div
+        {...props}
+        ref={ref}
+        role="log"
+        aria-live="polite"
+        className={clsx(styles.list, className)}
+      />
+    );
+  },
+);

package/src/components/ChatBubble/index.ts

@@ -0,0 +1,3 @@
+export { ChatBubble } from './ChatBubble';
+export type { ChatBubbleProps, ChatBubbleFrom } from './ChatBubble';
+export type { ChatBubbleListProps } from './ChatBubbleList';

package/src/components/ChatLauncher/ChatLauncher.module.scss

@@ -0,0 +1,68 @@
+@use './ChatLauncher.tokens';
+
+// The component IS a viewport layer (like Toast's stack), so it owns its own
+// fixed corner. Panel stacks above the launcher, both flush to the end edge.
+.root {
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- viewport layer owns its own positioning, not a flow component (same as Toast)
+  position: fixed;
+  inset-inline-end: var(--chat-launcher-inset);
+  bottom: var(--chat-launcher-inset);
+  z-index: var(--z-chat-launcher);
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--chat-launcher-gap);
+}
+
+// Capped to the viewport so the float never spills off a narrow screen.
+.panel {
+  display: flex;
+  flex-direction: column;
+  width: min(var(--chat-launcher-panel-width), 100vw - 2 * var(--chat-launcher-inset));
+  height: min(var(--chat-launcher-panel-height), 100dvh - var(--chat-launcher-reserved-y));
+  overflow: hidden;
+  background: var(--chat-launcher-panel-bg);
+  border: var(--border-width) solid var(--chat-launcher-panel-border-color);
+  border-radius: var(--chat-launcher-panel-radius);
+  box-shadow: var(--chat-launcher-panel-shadow);
+}
+
+// `display: flex` above would beat the UA `[hidden]` rule.
+.panel[hidden] {
+  display: none;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--chat-launcher-header-gap);
+  padding: var(--chat-launcher-header-padding-y) var(--chat-launcher-header-padding-x);
+  border-bottom: var(--border-width) solid var(--chat-launcher-section-border-color);
+}
+
+.title {
+  // stylelint-disable-next-line property-disallowed-list -- reset h2 default margin; internal
+  margin: 0;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--chat-launcher-title-font-size);
+  font-weight: var(--chat-launcher-title-font-weight);
+  color: var(--chat-launcher-title-fg);
+}
+
+// The scroll container; fills the panel's own column (internal, not consumer layout).
+.body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: var(--chat-launcher-body-padding);
+}
+
+.footer {
+  padding: var(--chat-launcher-footer-padding);
+  border-top: var(--border-width) solid var(--chat-launcher-section-border-color);
+}

package/src/components/ChatLauncher/ChatLauncher.tokens.scss

@@ -0,0 +1,27 @@
+// ChatLauncher.tokens.scss — Component tokens for <ChatLauncher>. Default to primitives.
+// The panel surface reuses Card's visual language (bg, border, radius) with a raised shadow.
+:root {
+  --chat-launcher-inset: var(--space-4);
+  --chat-launcher-gap: var(--space-3);
+  --chat-launcher-button-size: var(--size-lg); // the launcher is Button size="lg"
+  --chat-launcher-panel-width: 380px;
+  --chat-launcher-panel-height: 560px;
+
+  // Vertical space the panel can never use: both insets, the launcher, the gap.
+  --chat-launcher-reserved-y: calc(
+    2 * var(--chat-launcher-inset) + var(--chat-launcher-button-size) + var(--chat-launcher-gap)
+  );
+  --chat-launcher-panel-bg: var(--color-bg);
+  --chat-launcher-panel-border-color: var(--color-border);
+  --chat-launcher-panel-radius: var(--radius-lg);
+  --chat-launcher-panel-shadow: var(--shadow-lg);
+  --chat-launcher-header-gap: var(--space-3);
+  --chat-launcher-header-padding-y: var(--space-3);
+  --chat-launcher-header-padding-x: var(--space-4);
+  --chat-launcher-title-font-size: var(--font-size-md);
+  --chat-launcher-title-font-weight: var(--font-weight-semibold);
+  --chat-launcher-title-fg: var(--color-fg);
+  --chat-launcher-body-padding: var(--space-4);
+  --chat-launcher-footer-padding: var(--space-3);
+  --chat-launcher-section-border-color: var(--color-border);
+}

package/src/components/ChatLauncher/ChatLauncher.tsx

@@ -0,0 +1,202 @@
+import {
+  forwardRef,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import { createPortal } from 'react-dom';
+import clsx from 'clsx';
+import { X } from 'lucide-react';
+import { useTranslation } from '../../i18n';
+import { Button } from '../Button';
+import { mergeRefs } from '../_internal/refs';
+import { isAtBottom } from './isAtBottom';
+import styles from './ChatLauncher.module.scss';
+
+export interface ChatLauncherProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'title' | 'children'
+> {
+  /** Accessible name of the launcher button — names the assistant ("Ask Scout"). */
+  label: string;
+  /** Whether the panel is open. Controlled only: pair with `onOpenChange`. */
+  open: boolean;
+  /** Called with the requested state: launcher toggle, close button, Escape. */
+  onOpenChange(open: boolean): void;
+  /** Launcher glyph (e.g. a lucide icon with `aria-hidden`). */
+  icon: ReactNode;
+  /** Panel header text; also the dialog's accessible name. */
+  title: ReactNode;
+  /** Scrolling body — usually a `<ChatBubble.List>`. Stays mounted while closed. */
+  children: ReactNode;
+  /** Pinned area below the body — the composer (`Textarea` + send `Button`). */
+  footer?: ReactNode;
+  /**
+   * Element focused when the panel opens (point it at the composer).
+   * Default: the panel itself. Focus already inside the panel is not moved.
+   */
+  initialFocusRef?: RefObject<HTMLElement | null>;
+}
+
+/**
+ * Fixed bottom-end launcher button that toggles a non-modal chat panel.
+ * @see docs/components/ChatLauncher.md
+ */
+export const ChatLauncher = forwardRef<HTMLDivElement, ChatLauncherProps>(function ChatLauncher(
+  {
+    label,
+    open,
+    onOpenChange,
+    icon,
+    title,
+    children,
+    footer,
+    initialFocusRef,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const autoId = useId();
+  const panelId = props.id ?? `chat-launcher-${autoId}`;
+  const titleId = `${panelId}-title`;
+
+  const rootRef = useRef<HTMLDivElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const launcherRef = useRef<HTMLButtonElement>(null);
+
+  // Scroll is tracked live: a `hidden` body reads 0 for every metric, so it
+  // can't be measured at close time.
+  const openRef = useRef(open);
+  // Seeded with `open`: mounting open is not a transition, so it scrolls but
+  // doesn't pull focus on page load.
+  const wasOpenRef = useRef(open);
+  const initialFocus = useRef(initialFocusRef);
+  const openedOnceRef = useRef(false);
+  const scrollRef = useRef({ top: 0, atBottom: true });
+
+  // Read via a ref so a new `initialFocusRef` identity never re-runs the
+  // focus move below (non-modal: focus outside the panel stays put).
+  useLayoutEffect(() => {
+    initialFocus.current = initialFocusRef;
+  });
+
+  useLayoutEffect(() => {
+    openRef.current = open;
+    const panel = panelRef.current;
+    const body = bodyRef.current;
+    if (open) {
+      if (body) {
+        if (!openedOnceRef.current || scrollRef.current.atBottom) {
+          body.scrollTop = body.scrollHeight;
+          scrollRef.current = { top: body.scrollTop, atBottom: true };
+        } else {
+          body.scrollTop = scrollRef.current.top;
+        }
+      }
+      openedOnceRef.current = true;
+      if (!wasOpenRef.current && panel && !panel.contains(document.activeElement)) {
+        (initialFocus.current?.current ?? panel).focus({ preventScroll: true });
+      }
+    } else if (wasOpenRef.current && rootRef.current?.contains(document.activeElement)) {
+      // Escape / close button / programmatic close from inside: return focus.
+      // Focus outside the chat is never stolen.
+      launcherRef.current?.focus();
+    }
+    wasOpenRef.current = open;
+  }, [open]);
+
+  // Follow new content, or a shrinking body (composer grows, mobile keyboard),
+  // only while the user is already at the bottom.
+  useEffect(() => {
+    const content = contentRef.current;
+    const bodyEl = bodyRef.current;
+    if (!content || !bodyEl || typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(() => {
+      const body = bodyRef.current;
+      if (!openRef.current || !body || !scrollRef.current.atBottom) return;
+      body.scrollTop = body.scrollHeight;
+    });
+    observer.observe(content);
+    observer.observe(bodyEl);
+    return () => observer.disconnect();
+  }, []);
+
+  const onScroll = () => {
+    const body = bodyRef.current;
+    if (!openRef.current || !body) return;
+    scrollRef.current = {
+      top: body.scrollTop,
+      atBottom: isAtBottom(body.scrollTop, body.scrollHeight, body.clientHeight),
+    };
+  };
+
+  // Non-modal: Escape is scoped to the panel + launcher, never the document.
+  // React bubbles through portals, so a portaled descendant (a Modal opened
+  // from a bubble) is ignored by DOM containment.
+  const onRootKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (e.key !== 'Escape' || !open || e.defaultPrevented) return;
+    if (!rootRef.current?.contains(e.target as Node)) return;
+    e.preventDefault();
+    onOpenChange(false);
+  };
+
+  // SSR: no document to portal into; the chat mounts on the client.
+  if (typeof document === 'undefined') return null;
+
+  return createPortal(
+    <div ref={rootRef} className={styles.root} onKeyDown={onRootKeyDown}>
+      {/* {...props} first so role/hidden/aria-labelledby/tabIndex win */}
+      <div
+        {...props}
+        ref={mergeRefs<HTMLDivElement>(panelRef, ref)}
+        id={panelId}
+        className={clsx(styles.panel, className)}
+        role="dialog"
+        aria-labelledby={titleId}
+        tabIndex={-1}
+        hidden={!open}
+      >
+        <div className={styles.header}>
+          <h2 id={titleId} className={styles.title}>
+            {title}
+          </h2>
+          <Button
+            variant="ghost"
+            size="sm"
+            iconOnly
+            aria-label={t('chatLauncher.close')}
+            onClick={() => onOpenChange(false)}
+          >
+            <X size={16} aria-hidden="true" />
+          </Button>
+        </div>
+        <div ref={bodyRef} className={styles.body} onScroll={onScroll}>
+          <div ref={contentRef}>{children}</div>
+        </div>
+        {footer != null && <div className={styles.footer}>{footer}</div>}
+      </div>
+      <Button
+        ref={launcherRef}
+        variant="primary"
+        size="lg"
+        iconOnly
+        aria-label={label}
+        aria-expanded={open}
+        aria-controls={panelId}
+        onClick={() => onOpenChange(!open)}
+      >
+        {icon}
+      </Button>
+    </div>,
+    document.body,
+  );
+});

package/src/components/ChatLauncher/index.ts

@@ -0,0 +1,2 @@
+export { ChatLauncher } from './ChatLauncher';
+export type { ChatLauncherProps } from './ChatLauncher';

package/src/components/ChatLauncher/isAtBottom.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether a scroll container is at (within `threshold` px of) its bottom.
+ * Content shorter than the viewport counts as at the bottom.
+ */
+export function isAtBottom(
+  scrollTop: number,
+  scrollHeight: number,
+  clientHeight: number,
+  threshold = 24,
+): boolean {
+  return scrollHeight - clientHeight - scrollTop <= threshold;
+}

package/src/components/Checkbox/Checkbox.module.scss

@@ -0,0 +1,147 @@
+@use '../../styles/mixins' as *;
+@use './Checkbox.tokens';
+
+.checkbox {
+  // Anchors the visually-hidden input so a scrolling ancestor clips it (#670).
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--checkbox-gap);
+  cursor: pointer;
+  user-select: none;
+
+  // Pin the label's baseline contribution to its middle so the surrounding
+  // line-box stays the same height whether the box is checked (SVG inside)
+  // or unchecked (empty). Without this, an inline-flex element's baseline
+  // shifts based on inner content and the parent line-box grows/shrinks ~2px.
+  vertical-align: middle;
+
+  &.disabled {
+    cursor: not-allowed;
+  }
+}
+
+// Visually-hidden native input — stays in tab order + AT tree.
+.input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  /* stylelint-disable-next-line property-disallowed-list -- margin: -1px is the standard visually-hidden recipe; it offsets the 1px width/height so the element doesn't affect flow. Not a layout concern on the component boundary. */
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+// The painted box.
+.box {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  box-sizing: border-box;
+
+  // line-height: 1 keeps the box's intrinsic height constant whether it
+  // contains an SVG (checked / indeterminate) or nothing (unchecked).
+  // Without this the inline-box height jumps between states because the
+  // child SVG's baseline contributes to the line-box.
+  line-height: 1;
+  border: var(--border-width) solid var(--checkbox-border-color);
+  border-radius: var(--checkbox-radius);
+  background: var(--checkbox-bg);
+  color: var(--checkbox-fg);
+  transition:
+    border-color var(--transition-fast),
+    background var(--transition-fast),
+    box-shadow var(--transition-fast);
+}
+
+// Size modifiers — box diameter + label font.
+.size-sm .box {
+  width: var(--checkbox-box-size-sm);
+  height: var(--checkbox-box-size-sm);
+}
+
+.size-md .box {
+  width: var(--checkbox-box-size-md);
+  height: var(--checkbox-box-size-md);
+}
+
+.size-lg .box {
+  width: var(--checkbox-box-size-lg);
+  height: var(--checkbox-box-size-lg);
+}
+
+.size-sm .labelText {
+  font-size: var(--checkbox-label-font-size-sm);
+}
+
+.size-md .labelText {
+  font-size: var(--checkbox-label-font-size-md);
+}
+
+.size-lg .labelText {
+  font-size: var(--checkbox-label-font-size-lg);
+}
+
+// Hover preview — border only, no fill (Atlassian-style restraint).
+// Excludes .invalid so the danger border stays visible on hover instead
+// of flipping to accent and hiding the error signal.
+.checkbox:not(.disabled, .invalid):hover .box {
+  border-color: var(--checkbox-border-color-hover);
+}
+
+// Checked + indeterminate share the filled-accent visual. The
+// --checkbox-color CSS variable is set by the React layer when the
+// `color` prop is passed (palette color); otherwise the fallback
+// keeps the existing accent fill — defaults are byte-identical.
+.input:checked + .box,
+.input:indeterminate + .box {
+  background: var(--checkbox-color, var(--checkbox-bg-checked));
+  border-color: var(--checkbox-color, var(--checkbox-bg-checked));
+}
+
+// Focus ring on the box (sibling selector picks up native input focus).
+.input:focus-visible + .box {
+  @include focus-ring(var(--checkbox-ring));
+}
+
+// Disabled — muted bg + border. The input still receives `disabled`
+// natively which gates pointer events on the label.
+.disabled .box {
+  background: var(--checkbox-bg-disabled);
+  border-color: var(--checkbox-border-color-disabled);
+  color: var(--checkbox-fg-disabled);
+}
+
+.disabled .input:checked + .box,
+.disabled .input:indeterminate + .box {
+  background: var(--checkbox-bg-checked-disabled);
+  border-color: var(--checkbox-border-color-checked-disabled);
+}
+
+.disabled .labelText {
+  color: var(--checkbox-fg-disabled);
+}
+
+// Invalid — danger border + danger focus ring. Wins over the unchecked
+// hover preview.
+.invalid .box {
+  border-color: var(--checkbox-border-color-invalid);
+}
+
+.invalid .input:focus-visible + .box {
+  @include focus-ring(var(--checkbox-ring-invalid));
+}
+
+.invalid .input:checked + .box,
+.invalid .input:indeterminate + .box {
+  background: var(--checkbox-bg-checked-invalid);
+  border-color: var(--checkbox-border-color-checked-invalid);
+}
+
+.labelText {
+  line-height: var(--checkbox-label-line-height);
+}