@pcoi/components 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcoi/components",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "PCOI Design System — React UI components",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -11,9 +11,9 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     },
     "./css": "./dist/components.css"
   },

package/src/Callout/Callout.css

@@ -22,9 +22,14 @@
   line-height: var(--pcoi-semantic-type-body-compact-line-height);
   max-width: var(--pcoi-semantic-sizing-callout-width, 640px);
   margin: 0 0 var(--pcoi-semantic-spacing-panel-padding) 0;
+  padding: 0;
   font-style: italic;
 }
 
+.pcoi-callout__quote p {
+  margin: 0;
+}
+
 .pcoi-callout__attribution {
   font-size: var(--pcoi-semantic-type-body-sm-size);
   color: var(--pcoi-semantic-text-muted);

package/src/Callout/Callout.tsx

@@ -1,37 +1,41 @@
 import React from "react";
 
-export interface CalloutProps extends React.HTMLAttributes<HTMLDivElement> {
+export interface CalloutProps extends React.HTMLAttributes<HTMLElement> {
   /** Quote text */
   quote: string;
   /** Attribution name */
   attribution?: string;
   /** Attribution title/context */
   attributionTitle?: string;
-  /** Link URL */
+  /** Link URL for the source reference */
   sourceUrl?: string;
-  /** Link label */
+  /** Display label for the source link (default: "Source") */
   sourceLabel?: string;
 }
 
 /**
  * PCOI Callout / Blockquote
+ *
+ * Renders a semantic `<figure>` with `<blockquote>` and optional `<figcaption>`.
  * Tokens: spacing-40 (padding), text/secondary, text/accent (link)
  */
-export const Callout = React.forwardRef<HTMLDivElement, CalloutProps>(
+export const Callout = React.forwardRef<HTMLElement, CalloutProps>(
   ({ quote, attribution, attributionTitle, sourceUrl, sourceLabel, className = "", ...rest }, ref) => (
-    <div ref={ref} className={`pcoi-callout ${className}`} {...rest}>
-      <div className="pcoi-callout__line" />
-      <p className="pcoi-callout__quote">{quote}</p>
+    <figure ref={ref} className={`pcoi-callout ${className}`} {...rest}>
+      <div className="pcoi-callout__line" aria-hidden="true" />
+      <blockquote className="pcoi-callout__quote">
+        <p>{quote}</p>
+      </blockquote>
       {(attribution || sourceUrl) && (
-        <p className="pcoi-callout__attribution">
+        <figcaption className="pcoi-callout__attribution">
           {attributionTitle && <span>{attributionTitle} &nbsp;~&nbsp; </span>}
           {attribution}
           {sourceUrl && (
             <> &nbsp;|&nbsp; <a href={sourceUrl} target="_blank" rel="noopener noreferrer">{sourceLabel || "Source"}</a></>
           )}
-        </p>
+        </figcaption>
       )}
-    </div>
+    </figure>
   )
 );
 

package/src/ChatInterface/ChatInterface.css

@@ -3,6 +3,7 @@
 .pcoi-chat {
   display: flex;
   flex-direction: column;
+  width: 100%;
   height: 100%;
   max-width: var(--pcoi-semantic-sizing-container-narrow, 800px);
   margin: 0 auto;

package/src/ChatInterface/ChatInterface.integration.test.tsx

@@ -98,7 +98,7 @@ describe("ChatInterface integration", () => {
 
     render(<ChatCitationHarness />);
 
-    fireEvent.click(screen.getByRole("button", { name: "Knowledge Report" }));
+    fireEvent.click(screen.getByRole("button", { name: "View source: Knowledge Report" }));
 
     expect(screen.getByRole("dialog")).toBeInTheDocument();
     expect(screen.getByText("Knowledge Retention Report")).toBeInTheDocument();

package/src/ChatInterface/ChatInterface.tsx

@@ -7,10 +7,15 @@ import { TypingIndicator } from "../TypingIndicator/TypingIndicator";
 import type { ChatMessageRole, Citation, Suggestion } from "../types";
 
 export interface ChatInterfaceMessage {
+  /** Unique message identifier */
   id: string;
+  /** Sender role: "user" or "assistant" */
   role: ChatMessageRole;
+  /** Message body content */
   content: React.ReactNode;
+  /** Citations referenced in the message */
   citations?: Citation[];
+  /** ISO timestamp displayed below the message */
   timestamp?: string;
 }
 
@@ -85,7 +90,7 @@ export const ChatInterface = React.forwardRef<
             )}
           </div>
         ) : (
-          <ChatMessageList className="pcoi-chat__messages">
+          <ChatMessageList className="pcoi-chat__messages" aria-live="polite" aria-relevant="additions">
             {messages.map((msg) => (
               <ChatMessage
                 key={msg.id}

package/src/ChatMessageList/ChatMessageList.test.tsx

@@ -30,14 +30,17 @@ describe("ChatMessageList", () => {
 
     expect(screen.getByText("Assistant response")).toBeInTheDocument();
 
-    fireEvent.click(screen.getByRole("button", { name: "Knowledge Report" }));
-    fireEvent.click(screen.getByRole("button", { name: "[1]" }));
+    fireEvent.click(screen.getByRole("button", { name: "View source: Knowledge Report" }));
+    fireEvent.click(screen.getByRole("button", { name: "Citation 1, view source: Knowledge Report" }));
 
     expect(onCitationClick).toHaveBeenCalledTimes(2);
     expect(onCitationClick).toHaveBeenCalledWith(citation);
   });
 
-  it("auto-scrolls to bottom when new messages are added", async () => {
+  it("auto-scrolls last message into view when new messages are added", async () => {
+    const scrollIntoViewMock = vi.fn();
+    Element.prototype.scrollIntoView = scrollIntoViewMock;
+
     vi.spyOn(window, "requestAnimationFrame").mockImplementation(
       (cb: FrameRequestCallback) => {
         cb(0);
@@ -45,20 +48,13 @@ describe("ChatMessageList", () => {
       }
     );
 
-    const { container, rerender } = render(
+    const { rerender } = render(
       <ChatMessageList>
         <div>Message 1</div>
       </ChatMessageList>
     );
 
-    const inner = container.querySelector(
-      ".pcoi-chat-message-list__inner"
-    ) as HTMLDivElement;
-
-    Object.defineProperty(inner, "scrollHeight", {
-      configurable: true,
-      get: () => 480,
-    });
+    scrollIntoViewMock.mockClear();
 
     rerender(
       <ChatMessageList>
@@ -68,7 +64,7 @@ describe("ChatMessageList", () => {
     );
 
     await waitFor(() => {
-      expect(inner.scrollTop).toBe(480);
+      expect(scrollIntoViewMock).toHaveBeenCalledWith({ block: "nearest" });
     });
   });
 });

package/src/ChatMessageList/ChatMessageList.tsx

@@ -23,7 +23,12 @@ export const ChatMessageList = React.forwardRef<
 
     const scrollToEnd = () => {
       requestAnimationFrame(() => {
-        el.scrollTop = el.scrollHeight;
+        const lastChild = el.lastElementChild;
+        if (lastChild) {
+          lastChild.scrollIntoView({ block: "nearest" });
+        } else {
+          el.scrollTop = el.scrollHeight;
+        }
       });
     };
 
@@ -39,7 +44,7 @@ export const ChatMessageList = React.forwardRef<
     .join(" ");
 
   return (
-    <div ref={ref} className={classes} {...rest}>
+    <div ref={ref} className={classes} role="log" aria-label="Conversation" {...rest}>
       <div ref={innerRef} className="pcoi-chat-message-list__inner">
         {children}
       </div>

package/src/CitedExcerpt/CitedExcerpt.tsx

@@ -29,6 +29,7 @@ export const CitedExcerpt = React.forwardRef<HTMLDivElement, CitedExcerptProps>(
           type="button"
           className="pcoi-cited-excerpt__source"
           onClick={onSourceClick}
+          aria-label={`View source: ${sourceTitle}`}
         >
           {sourceTitle}
         </button>
@@ -37,6 +38,7 @@ export const CitedExcerpt = React.forwardRef<HTMLDivElement, CitedExcerptProps>(
             type="button"
             className="pcoi-cited-excerpt__index"
             onClick={onSourceClick}
+            aria-label={`Citation ${index}, view source: ${sourceTitle}`}
           >
             [{index}]
           </button>

package/src/ComparisonTable/ComparisonTable.tsx

@@ -1,14 +1,20 @@
 import React from "react";
 
 export interface ComparisonRow {
+  /** Feature label shown in the first column */
   label: string;
+  /** Competitor's value for this feature */
   competitor: string;
+  /** PCOI's value for this feature */
   pcoi: string;
 }
 
 export interface ComparisonTableProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Column header for the competitor (default: "Typical SaaS AI") */
   competitorName?: string;
+  /** Column header for PCOI (default: "PCOI") */
   pcoiName?: string;
+  /** Feature comparison rows */
   rows: ComparisonRow[];
 }
 

package/src/ContactForm/ContactForm.tsx

@@ -3,6 +3,7 @@ import { Button } from "../Button";
 import { FormField } from "../FormField";
 
 export interface ContactFormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit"> {
+  /** Called with form field values when the form is submitted */
   onSubmit?: (data: Record<string, string>) => void;
 }
 

package/src/DocumentOverlay/DocumentOverlay.tsx

@@ -31,7 +31,7 @@ export const DocumentOverlay = React.forwardRef<
 >(
   (
     { open, onClose, title, sourceLabel, children, highlightId, highlightIndex, className = "", ...rest },
-    _ref
+    ref
   ) => {
     const contentRef = useRef<HTMLDivElement>(null);
 
@@ -65,6 +65,7 @@ export const DocumentOverlay = React.forwardRef<
     return React.createElement(
       Modal,
       {
+        ref,
         open,
         onClose,
         title,

package/src/Footer/Footer.tsx

@@ -6,8 +6,11 @@ import type { LinkItem } from "../types";
 export type FooterLink = LinkItem;
 
 export interface FooterProps extends React.HTMLAttributes<HTMLElement> {
+  /** Navigation links rendered in the footer */
   links?: LinkItem[];
+  /** Brand tagline displayed alongside the logo */
   tagline?: string;
+  /** Copyright notice shown at the bottom */
   copyright?: string;
 }
 
@@ -39,11 +42,11 @@ export const Footer = React.forwardRef<HTMLElement, FooterProps>(
           <LogoMark className="pcoi-footer__logo" />
           <p className="pcoi-footer__tagline">{tagline}</p>
         </div>
-        <div className="pcoi-footer__links">
+        <nav className="pcoi-footer__links" aria-label="Footer">
           {links.map((link) => (
             <a key={link.href} href={link.href} data-track-id={link.trackingId}>{link.label}</a>
           ))}
-        </div>
+        </nav>
       </div>
       <div className="pcoi-footer__bottom">
         <p>{copyright}</p>

package/src/LogoMark/LogoMark.tsx

@@ -14,8 +14,8 @@ export type LogoMarkProps = React.AnchorHTMLAttributes<HTMLAnchorElement>;
  */
 export const LogoMark = React.forwardRef<HTMLAnchorElement, LogoMarkProps>(
   ({ href = "#", className = "", ...rest }, ref) => (
-    <a ref={ref} href={href} className={`pcoi-logo ${className}`} {...rest}>
-      <span className="pcoi-logo__mark">P</span>COI
+    <a ref={ref} href={href} className={`pcoi-logo ${className}`} aria-label="PCOI home" {...rest}>
+      <span className="pcoi-logo__mark" aria-hidden="true">P</span>COI
     </a>
   )
 );

package/src/Modal/Modal.tsx

@@ -25,115 +25,120 @@ export interface ModalProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "
  * Tokens: bg/overlay, surface/elevated, border/default, shadow/elevated,
  *         zIndex/modal, radius-lg, text/primary, text/secondary
  */
-export const Modal: React.FC<ModalProps> = ({
-  open,
-  onClose,
-  title,
-  headingLevel = "h2",
-  size = "default",
-  children,
-  footer,
-  className = "",
-  ...rest
-}) => {
-  const dialogRef = useRef<HTMLDivElement>(null);
-  const previousFocusRef = useRef<HTMLElement | null>(null);
+export const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
+  (
+    {
+      open,
+      onClose,
+      title,
+      headingLevel = "h2",
+      size = "default",
+      children,
+      footer,
+      className = "",
+      ...rest
+    },
+    _ref
+  ) => {
+    const dialogRef = useRef<HTMLDivElement>(null);
+    const previousFocusRef = useRef<HTMLElement | null>(null);
 
-  const Heading = headingLevel;
-  const titleId = title ? "pcoi-modal-title" : undefined;
+    const Heading = headingLevel;
+    const titleId = title ? "pcoi-modal-title" : undefined;
 
-  const handleKeyDown = useCallback(
-    (e: KeyboardEvent) => {
-      if (e.key === "Escape") {
-        onClose();
-        return;
-      }
+    const handleKeyDown = useCallback(
+      (e: KeyboardEvent) => {
+        if (e.key === "Escape") {
+          onClose();
+          return;
+        }
 
-      if (e.key === "Tab" && dialogRef.current) {
-        const focusable = dialogRef.current.querySelectorAll<HTMLElement>(
-          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-        );
-        if (focusable.length === 0) return;
+        if (e.key === "Tab" && dialogRef.current) {
+          const focusable = dialogRef.current.querySelectorAll<HTMLElement>(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+          );
+          if (focusable.length === 0) return;
 
-        const first = focusable[0];
-        const last = focusable[focusable.length - 1];
+          const first = focusable[0];
+          const last = focusable[focusable.length - 1];
 
-        if (e.shiftKey && document.activeElement === first) {
-          e.preventDefault();
-          last.focus();
-        } else if (!e.shiftKey && document.activeElement === last) {
-          e.preventDefault();
-          first.focus();
+          if (e.shiftKey && document.activeElement === first) {
+            e.preventDefault();
+            last.focus();
+          } else if (!e.shiftKey && document.activeElement === last) {
+            e.preventDefault();
+            first.focus();
+          }
         }
-      }
-    },
-    [onClose]
-  );
+      },
+      [onClose]
+    );
 
-  useEffect(() => {
-    if (open) {
-      previousFocusRef.current = document.activeElement as HTMLElement;
-      document.addEventListener("keydown", handleKeyDown);
-      document.body.style.overflow = "hidden";
+    useEffect(() => {
+      if (open) {
+        previousFocusRef.current = document.activeElement as HTMLElement;
+        document.addEventListener("keydown", handleKeyDown);
+        document.body.style.overflow = "hidden";
 
-      // Focus the dialog after render
-      requestAnimationFrame(() => {
-        const focusable = dialogRef.current?.querySelector<HTMLElement>(
-          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-        );
-        focusable?.focus();
-      });
-    }
+        // Focus the dialog after render
+        requestAnimationFrame(() => {
+          const focusable = dialogRef.current?.querySelector<HTMLElement>(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+          );
+          focusable?.focus();
+        });
+      }
 
-    return () => {
-      document.removeEventListener("keydown", handleKeyDown);
-      document.body.style.overflow = "";
-      previousFocusRef.current?.focus();
-    };
-  }, [open, handleKeyDown]);
+      return () => {
+        document.removeEventListener("keydown", handleKeyDown);
+        document.body.style.overflow = "";
+        previousFocusRef.current?.focus();
+      };
+    }, [open, handleKeyDown]);
 
-  const handleBackdropClick = (e: React.MouseEvent) => {
-    if (e.target === e.currentTarget) {
-      onClose();
-    }
-  };
+    const handleBackdropClick = (e: React.MouseEvent) => {
+      if (e.target === e.currentTarget) {
+        onClose();
+      }
+    };
 
-  if (!open) return null;
+    if (!open) return null;
 
-  const wrapperClasses = ["pcoi-modal", className].filter(Boolean).join(" ");
+    const wrapperClasses = ["pcoi-modal", className].filter(Boolean).join(" ");
 
-  return createPortal(
-    <div className={wrapperClasses} onClick={handleBackdropClick}>
-      <div
-        ref={dialogRef}
-        className={`pcoi-modal__dialog${size === "wide" ? " pcoi-modal__dialog--wide" : ""}`}
-        role="dialog"
-        aria-modal="true"
-        aria-labelledby={titleId}
-        {...rest}
-      >
-        <div className="pcoi-modal__header">
-          {title && (
-            <Heading id={titleId} className="pcoi-modal__title">
-              {title}
-            </Heading>
-          )}
-          <button
-            type="button"
-            className="pcoi-modal__close"
-            onClick={onClose}
-            aria-label="Close modal"
-          >
-            <CloseIcon size={20} />
-          </button>
+    return createPortal(
+      <div className={wrapperClasses} onClick={handleBackdropClick}>
+        <div
+          ref={dialogRef}
+          className={`pcoi-modal__dialog${size === "wide" ? " pcoi-modal__dialog--wide" : ""}`}
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={titleId}
+          {...rest}
+        >
+          <div className="pcoi-modal__header">
+            {title && (
+              <Heading id={titleId} className="pcoi-modal__title">
+                {title}
+              </Heading>
+            )}
+            <button
+              type="button"
+              className="pcoi-modal__close"
+              onClick={onClose}
+              aria-label="Close modal"
+            >
+              <CloseIcon size={20} />
+            </button>
+          </div>
+          <div className="pcoi-modal__body">{children}</div>
+          {footer && <div className="pcoi-modal__footer">{footer}</div>}
         </div>
-        <div className="pcoi-modal__body">{children}</div>
-        {footer && <div className="pcoi-modal__footer">{footer}</div>}
-      </div>
-    </div>,
-    document.body
-  );
-};
+      </div>,
+      document.body
+    );
+  }
+);
 
 Modal.displayName = "Modal";
 export default Modal;

package/src/Nav/Nav.tsx

@@ -7,9 +7,13 @@ import type { LinkItem } from "../types";
 export type NavLink = LinkItem;
 
 export interface NavProps extends React.HTMLAttributes<HTMLElement> {
+  /** Navigation links rendered in the navbar */
   links?: LinkItem[];
+  /** Label text for the call-to-action button */
   ctaLabel?: string;
+  /** URL the CTA button links to */
   ctaHref?: string;
+  /** Called when the CTA button is clicked */
   onCtaClick?: () => void;
 }
 
@@ -82,9 +86,9 @@ export const Nav = React.forwardRef<HTMLElement, NavProps>(
             <span /><span /><span />
           </button>
         </div>
-        <div className="pcoi-nav__mobile-menu" id="pcoi-mobile-menu">
+        <div className="pcoi-nav__mobile-menu" id="pcoi-mobile-menu" role="menu" aria-hidden={!menuOpen}>
           {links.map((link) => (
-            <a key={link.href} href={link.href} data-track-id={link.trackingId} onClick={() => setMenuOpen(false)}>
+            <a key={link.href} href={link.href} data-track-id={link.trackingId} role="menuitem" tabIndex={menuOpen ? 0 : -1} onClick={() => setMenuOpen(false)}>
               {link.label}
             </a>
           ))}

package/src/SignalsPanel/SignalsPanel.tsx

@@ -2,7 +2,9 @@ import React from "react";
 import type { HeadingLevel } from "../types";
 
 export interface SignalsPanelProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Panel heading text */
   title?: string;
+  /** List of signal statements displayed as bullet points */
   signals: string[];
   /** Heading level for the title (default: "h3") */
   headingLevel?: HeadingLevel;