@pcoi/components 0.1.0

package/src/ChatInterface/ChatInterface.tsx

@@ -0,0 +1,120 @@
+import React from "react";
+import { ChatMessageList } from "../ChatMessageList/ChatMessageList";
+import { ChatMessage } from "../ChatMessage/ChatMessage";
+import { SuggestionCards } from "../SuggestionCards/SuggestionCards";
+import { PromptBar } from "../PromptBar/PromptBar";
+import { TypingIndicator } from "../TypingIndicator/TypingIndicator";
+import type { ChatMessageRole, Citation, Suggestion } from "../types";
+
+export interface ChatInterfaceMessage {
+  id: string;
+  role: ChatMessageRole;
+  content: React.ReactNode;
+  citations?: Citation[];
+  timestamp?: string;
+}
+
+export interface ChatInterfaceProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** Conversation messages */
+  messages: ChatInterfaceMessage[];
+  /** Suggestion prompts for the empty state */
+  suggestions?: Suggestion[];
+  /** Current prompt textarea value */
+  promptValue: string;
+  /** Called when the prompt textarea changes */
+  onPromptChange: (value: string) => void;
+  /** Called when the user submits a prompt */
+  onPromptSubmit: (value: string) => void;
+  /** Called when a suggestion card is clicked */
+  onSuggestionSelect?: (suggestion: Suggestion) => void;
+  /** Called when a citation is clicked */
+  onCitationClick?: (citation: Citation) => void;
+  /** Textarea placeholder */
+  placeholder?: string;
+  /** Disable input while loading */
+  loading?: boolean;
+}
+
+/**
+ * PCOI ChatInterface — Top-level chat composition
+ * Empty state: suggestions + prompt. Active state: messages + prompt.
+ * Tokens: bg/default, container/narrow, spacing-16/24
+ */
+export const ChatInterface = React.forwardRef<
+  HTMLDivElement,
+  ChatInterfaceProps
+>(
+  (
+    {
+      messages,
+      suggestions,
+      promptValue,
+      onPromptChange,
+      onPromptSubmit,
+      onSuggestionSelect,
+      onCitationClick,
+      placeholder,
+      loading = false,
+      className = "",
+      ...rest
+    },
+    ref
+  ) => {
+    const isEmpty = messages.length === 0;
+
+    const classes = [
+      "pcoi-chat",
+      isEmpty ? "pcoi-chat--empty" : "",
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <div ref={ref} className={classes} {...rest}>
+        {isEmpty ? (
+          <div className="pcoi-chat__empty-state">
+            {suggestions && suggestions.length > 0 && onSuggestionSelect && (
+              <div className="pcoi-chat__suggestions">
+                <SuggestionCards
+                  suggestions={suggestions}
+                  onSelect={onSuggestionSelect}
+                />
+              </div>
+            )}
+          </div>
+        ) : (
+          <ChatMessageList className="pcoi-chat__messages">
+            {messages.map((msg) => (
+              <ChatMessage
+                key={msg.id}
+                role={msg.role}
+                citations={msg.citations}
+                timestamp={msg.timestamp}
+                onCitationClick={onCitationClick}
+              >
+                {msg.content}
+              </ChatMessage>
+            ))}
+            {loading && <TypingIndicator />}
+          </ChatMessageList>
+        )}
+
+        <div className="pcoi-chat__prompt">
+          <PromptBar
+            value={promptValue}
+            onChange={onPromptChange}
+            onSubmit={onPromptSubmit}
+            placeholder={placeholder}
+            loading={loading}
+            disabled={loading}
+          />
+        </div>
+      </div>
+    );
+  }
+);
+
+ChatInterface.displayName = "ChatInterface";
+export default ChatInterface;

package/src/ChatInterface/index.ts

@@ -0,0 +1,6 @@
+export {
+  ChatInterface,
+  type ChatInterfaceProps,
+  type ChatInterfaceMessage,
+} from "./ChatInterface";
+export { default } from "./ChatInterface";

package/src/ChatMessage/ChatMessage.css

@@ -0,0 +1,55 @@
+/* ChatMessage — @pcoi/components */
+
+.pcoi-chat-message {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pcoi-spacing-8);
+  padding: var(--pcoi-spacing-16);
+  border-radius: var(--pcoi-radius-md);
+  border: 1px solid var(--pcoi-semantic-border-card);
+}
+
+/* ── Role variants ── */
+.pcoi-chat-message--user {
+  background: var(--pcoi-color-surface);
+}
+
+.pcoi-chat-message--assistant {
+  background: var(--pcoi-semantic-surface-accent-dim);
+}
+
+.pcoi-chat-message__header {
+  display: flex;
+  align-items: center;
+}
+
+.pcoi-chat-message__body {
+  font-family: var(--pcoi-semantic-type-body-font);
+  font-size: var(--pcoi-semantic-type-body-size);
+  line-height: var(--pcoi-semantic-type-body-line-height);
+  color: var(--pcoi-semantic-text-primary);
+}
+
+.pcoi-chat-message__citations {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pcoi-spacing-8);
+  margin-top: var(--pcoi-spacing-4);
+}
+
+.pcoi-chat-message__timestamp {
+  font-family: var(--pcoi-semantic-type-body-font);
+  font-size: var(--pcoi-semantic-type-body-sm-size);
+  color: var(--pcoi-semantic-text-muted);
+}
+
+/* ── Responsive: offset margins on desktop ── */
+@media (min-width: 1025px) {
+  .pcoi-chat-message--user {
+    margin-left: var(--pcoi-spacing-48);
+  }
+
+  .pcoi-chat-message--assistant {
+    margin-right: var(--pcoi-spacing-48);
+  }
+}

package/src/ChatMessage/ChatMessage.tsx

@@ -0,0 +1,71 @@
+import React from "react";
+import { Badge } from "../Badge/Badge";
+import { CitedExcerpt } from "../CitedExcerpt/CitedExcerpt";
+import type { ChatMessageRole, Citation } from "../types";
+
+export interface ChatMessageProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** Message sender role */
+  role: ChatMessageRole;
+  /** Message body content */
+  children: React.ReactNode;
+  /** Citations referenced in the message */
+  citations?: Citation[];
+  /** Displayed below the message body */
+  timestamp?: string;
+  /** Called when a citation marker or source link is clicked */
+  onCitationClick?: (citation: Citation) => void;
+}
+
+/**
+ * PCOI ChatMessage — User or assistant message bubble
+ * Tokens: surface/elevated (user), bg/card (assistant), border/card,
+ *         radius-md, text/primary, text/muted, type/body-size
+ */
+export const ChatMessage = React.forwardRef<HTMLDivElement, ChatMessageProps>(
+  (
+    { role, children, citations, timestamp, onCitationClick, className = "", ...rest },
+    ref
+  ) => {
+    const classes = [
+      "pcoi-chat-message",
+      `pcoi-chat-message--${role}`,
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <div ref={ref} className={classes} {...rest}>
+        <div className="pcoi-chat-message__header">
+          <Badge variant={role === "assistant" ? "default" : "info"}>
+            {role === "assistant" ? "PCOI" : "You"}
+          </Badge>
+        </div>
+
+        <div className="pcoi-chat-message__body">{children}</div>
+
+        {citations && citations.length > 0 && (
+          <div className="pcoi-chat-message__citations">
+            {citations.map((c) => (
+              <CitedExcerpt
+                key={c.index}
+                index={c.index}
+                excerpt={c.excerpt}
+                sourceTitle={c.sourceTitle}
+                onSourceClick={() => onCitationClick?.(c)}
+              />
+            ))}
+          </div>
+        )}
+
+        {timestamp && (
+          <time className="pcoi-chat-message__timestamp">{timestamp}</time>
+        )}
+      </div>
+    );
+  }
+);
+
+ChatMessage.displayName = "ChatMessage";
+export default ChatMessage;

package/src/ChatMessage/index.ts

@@ -0,0 +1,2 @@
+export { ChatMessage, type ChatMessageProps } from "./ChatMessage";
+export { default } from "./ChatMessage";

package/src/ChatMessageList/ChatMessageList.css

@@ -0,0 +1,24 @@
+/* ChatMessageList — @pcoi/components */
+
+.pcoi-chat-message-list {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.pcoi-chat-message-list__inner {
+  height: 100%;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--pcoi-spacing-16);
+  padding: var(--pcoi-spacing-16);
+}
+
+/* ── Responsive: wider spacing on tablet+ ── */
+@media (min-width: 768px) {
+  .pcoi-chat-message-list__inner {
+    gap: var(--pcoi-spacing-20);
+    padding: var(--pcoi-spacing-24);
+  }
+}

package/src/ChatMessageList/ChatMessageList.tsx

@@ -0,0 +1,51 @@
+import React, { useRef, useEffect } from "react";
+
+export interface ChatMessageListProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** ChatMessage elements */
+  children: React.ReactNode;
+}
+
+/**
+ * PCOI ChatMessageList — Scrollable container that auto-scrolls to newest message
+ * Tokens: spacing-16/20 (gap), spacing-16/24 (padding)
+ */
+export const ChatMessageList = React.forwardRef<
+  HTMLDivElement,
+  ChatMessageListProps
+>(({ children, className = "", ...rest }, ref) => {
+  const innerRef = useRef<HTMLDivElement>(null);
+
+  /* Scroll to bottom whenever the DOM inside the list changes */
+  useEffect(() => {
+    const el = innerRef.current;
+    if (!el) return;
+
+    const scrollToEnd = () => {
+      requestAnimationFrame(() => {
+        el.scrollTop = el.scrollHeight;
+      });
+    };
+
+    const observer = new MutationObserver(scrollToEnd);
+    observer.observe(el, { childList: true, subtree: true });
+
+    scrollToEnd();
+    return () => observer.disconnect();
+  }, []);
+
+  const classes = ["pcoi-chat-message-list", className]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div ref={ref} className={classes} {...rest}>
+      <div ref={innerRef} className="pcoi-chat-message-list__inner">
+        {children}
+      </div>
+    </div>
+  );
+});
+
+ChatMessageList.displayName = "ChatMessageList";
+export default ChatMessageList;

package/src/ChatMessageList/index.ts

@@ -0,0 +1,2 @@
+export { ChatMessageList, type ChatMessageListProps } from "./ChatMessageList";
+export { default } from "./ChatMessageList";

package/src/Checkbox/Checkbox.css

@@ -0,0 +1,97 @@
+/* Checkbox — @pcoi/components */
+
+.pcoi-checkbox {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pcoi-spacing-6);
+}
+
+.pcoi-checkbox__control {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--pcoi-spacing-8);
+  cursor: pointer;
+}
+
+.pcoi-checkbox__input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+.pcoi-checkbox__box {
+  width: var(--pcoi-layout-component-control-box);
+  height: var(--pcoi-layout-component-control-box);
+  flex-shrink: 0;
+  border: 1px solid var(--pcoi-semantic-border-default);
+  border-radius: var(--pcoi-radius-sm);
+  background: var(--pcoi-semantic-bg-default);
+  transition: background var(--pcoi-effect-transition-fast, 0.2s ease),
+              border-color var(--pcoi-effect-transition-fast, 0.2s ease);
+  position: relative;
+}
+
+.pcoi-checkbox__box::after {
+  content: "";
+  position: absolute;
+  top: 2px;
+  left: 5px;
+  width: 5px;
+  height: 9px;
+  border: solid var(--pcoi-semantic-action-primary-text);
+  border-width: 0 2px 2px 0;
+  transform: rotate(45deg);
+  opacity: 0;
+  transition: opacity var(--pcoi-effect-transition-fast, 0.2s ease);
+}
+
+.pcoi-checkbox__input:checked + .pcoi-checkbox__box {
+  background: var(--pcoi-semantic-action-primary-bg);
+  border-color: var(--pcoi-semantic-action-primary-bg);
+}
+
+.pcoi-checkbox__input:checked + .pcoi-checkbox__box::after {
+  opacity: 1;
+}
+
+.pcoi-checkbox__control:hover .pcoi-checkbox__box {
+  border-color: var(--pcoi-semantic-border-input-hover);
+}
+
+.pcoi-checkbox__control:active .pcoi-checkbox__box {
+  transform: var(--pcoi-effect-transform-press-scale-control);
+}
+
+.pcoi-checkbox__input:focus-visible + .pcoi-checkbox__box {
+  border-color: var(--pcoi-semantic-focus-border);
+  box-shadow: var(--pcoi-effect-shadow-focus-ring);
+}
+
+.pcoi-checkbox__label {
+  font-size: var(--pcoi-semantic-type-body-size);
+  color: var(--pcoi-semantic-text-primary);
+}
+
+/* ── Error state ── */
+.pcoi-checkbox--error .pcoi-checkbox__box {
+  border-color: var(--pcoi-semantic-border-error);
+}
+
+.pcoi-checkbox__error {
+  font-size: var(--pcoi-semantic-type-label-size);
+  color: var(--pcoi-semantic-text-error);
+  margin: 0;
+  padding-left: calc(var(--pcoi-layout-component-control-box) + var(--pcoi-spacing-8));
+}
+
+/* ── Disabled state ── */
+.pcoi-checkbox--disabled {
+  opacity: var(--pcoi-effect-opacity-disabled);
+  pointer-events: none;
+}

package/src/Checkbox/Checkbox.tsx

@@ -0,0 +1,70 @@
+import React from "react";
+
+export interface CheckboxProps
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
+  /** Visible label text */
+  label: string;
+  /** Unique field name, also used to generate id */
+  name: string;
+  /** Error message — when truthy, field enters error state */
+  error?: string;
+}
+
+/**
+ * PCOI Checkbox — Custom styled checkbox with label
+ * Tokens: bg/default, border/default, border/error, focus/border, focus/glow,
+ *         action/primary-bg, action/primary-text, text/primary, text/error, radius-sm
+ */
+export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
+  (
+    {
+      label,
+      name,
+      error,
+      disabled = false,
+      className = "",
+      ...props
+    },
+    ref
+  ) => {
+    const fieldId = `pcoi-field-${name}`;
+    const errorId = error ? `${fieldId}-error` : undefined;
+
+    const wrapperClasses = [
+      "pcoi-checkbox",
+      error ? "pcoi-checkbox--error" : "",
+      disabled ? "pcoi-checkbox--disabled" : "",
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <div className={wrapperClasses}>
+        <label htmlFor={fieldId} className="pcoi-checkbox__control">
+          <input
+            ref={ref}
+            type="checkbox"
+            id={fieldId}
+            name={name}
+            disabled={disabled}
+            aria-invalid={!!error}
+            aria-describedby={errorId}
+            className="pcoi-checkbox__input"
+            {...props}
+          />
+          <span className="pcoi-checkbox__box" aria-hidden="true" />
+          <span className="pcoi-checkbox__label">{label}</span>
+        </label>
+        {error && (
+          <span id={errorId} className="pcoi-checkbox__error" role="alert">
+            {error}
+          </span>
+        )}
+      </div>
+    );
+  }
+);
+
+Checkbox.displayName = "Checkbox";
+export default Checkbox;

package/src/Checkbox/index.ts

@@ -0,0 +1,2 @@
+export { Checkbox, type CheckboxProps } from "./Checkbox";
+export { default } from "./Checkbox";

package/src/CitationMark/CitationMark.css

@@ -0,0 +1,40 @@
+/* CitationMark — @pcoi/components */
+
+.pcoi-citation-mark {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 32px;
+  min-height: 32px;
+  padding: var(--pcoi-spacing-4) var(--pcoi-spacing-10);
+  font-family: var(--pcoi-semantic-type-mono-font);
+  font-size: var(--pcoi-semantic-type-body-compact-size);
+  font-weight: var(--pcoi-semantic-type-label-weight);
+  line-height: var(--pcoi-semantic-type-none-line-height);
+  color: var(--pcoi-semantic-text-accent);
+  background: var(--pcoi-semantic-surface-accent-dim);
+  border: 1px solid var(--pcoi-semantic-border-accent-dim);
+  border-radius: var(--pcoi-radius-full);
+  cursor: pointer;
+  vertical-align: middle;
+  transition:
+    background var(--pcoi-effect-transition-fast),
+    color var(--pcoi-effect-transition-fast),
+    border-color var(--pcoi-effect-transition-fast),
+    transform var(--pcoi-effect-transition-fast);
+}
+
+.pcoi-citation-mark:hover {
+  color: var(--pcoi-semantic-text-accent-hover);
+  background: var(--pcoi-color-accent-dim);
+  border-color: var(--pcoi-semantic-border-accent-subtle);
+}
+
+.pcoi-citation-mark:active {
+  transform: var(--pcoi-effect-transform-press-scale-control);
+}
+
+.pcoi-citation-mark:focus-visible {
+  outline: none;
+  box-shadow: var(--pcoi-effect-shadow-focus-ring);
+}

package/src/CitationMark/CitationMark.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+
+export interface CitationMarkProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** 1-based citation index displayed in the button */
+  index: number;
+  /** Tooltip text (defaults to "Citation {index}") */
+  sourceLabel?: string;
+}
+
+/**
+ * PCOI CitationMark — Inline pill-shaped citation button [1]
+ * Tokens: text/accent, surface/accent-dim, border/accent-dim,
+ *         radius-full, font-family/mono, transition-fast,
+ *         shadow/focus-ring, transform/press-scale-control
+ */
+export const CitationMark = React.forwardRef<
+  HTMLButtonElement,
+  CitationMarkProps
+>(({ index, sourceLabel, className = "", ...rest }, ref) => {
+  const classes = ["pcoi-citation-mark", className].filter(Boolean).join(" ");
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      className={classes}
+      title={sourceLabel ?? `Citation ${index}`}
+      aria-label={sourceLabel ?? `Citation ${index}`}
+      {...rest}
+    >
+      {index}
+    </button>
+  );
+});
+
+CitationMark.displayName = "CitationMark";
+export default CitationMark;

package/src/CitationMark/index.ts

@@ -0,0 +1,2 @@
+export { CitationMark, type CitationMarkProps } from "./CitationMark";
+export { default } from "./CitationMark";

package/src/CitedExcerpt/CitedExcerpt.css

@@ -0,0 +1,75 @@
+/* CitedExcerpt — @pcoi/components */
+
+.pcoi-cited-excerpt {
+  display: flex;
+  flex-direction: column;
+  gap: var(--pcoi-spacing-6);
+  padding: var(--pcoi-spacing-12);
+  background: var(--pcoi-semantic-surface-accent-dim);
+  border-left: var(--pcoi-layout-component-accent-border-w) solid
+    var(--pcoi-semantic-border-accent-dim);
+  border-radius: var(--pcoi-radius-sm);
+}
+
+.pcoi-cited-excerpt__source {
+  display: inline-flex;
+  align-items: center;
+  align-self: flex-start;
+  padding: 0;
+  font-family: var(--pcoi-semantic-type-body-font);
+  font-size: var(--pcoi-semantic-type-body-sm-size);
+  color: var(--pcoi-semantic-text-accent);
+  background: none;
+  border: none;
+  cursor: pointer;
+  transition:
+    color var(--pcoi-effect-transition-fast);
+}
+
+.pcoi-cited-excerpt__source:hover {
+  color: var(--pcoi-semantic-text-accent-hover);
+  text-decoration: underline;
+}
+
+.pcoi-cited-excerpt__source:focus-visible {
+  outline: none;
+  box-shadow: var(--pcoi-effect-shadow-focus-ring);
+  border-radius: var(--pcoi-radius-sm);
+}
+
+.pcoi-cited-excerpt__body {
+  display: flex;
+  align-items: baseline;
+  gap: var(--pcoi-spacing-6);
+}
+
+.pcoi-cited-excerpt__index {
+  flex-shrink: 0;
+  padding: 0;
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-family: var(--pcoi-semantic-type-mono-font);
+  font-size: var(--pcoi-semantic-type-body-compact-size);
+  font-weight: var(--pcoi-semantic-type-label-weight);
+  color: var(--pcoi-semantic-text-accent);
+  transition: color var(--pcoi-effect-transition-fast);
+}
+
+.pcoi-cited-excerpt__index:hover {
+  color: var(--pcoi-semantic-text-accent-hover);
+}
+
+.pcoi-cited-excerpt__index:focus-visible {
+  outline: none;
+  box-shadow: var(--pcoi-effect-shadow-focus-ring);
+  border-radius: var(--pcoi-radius-sm);
+}
+
+.pcoi-cited-excerpt__text {
+  margin: 0;
+  font-family: var(--pcoi-semantic-type-body-font);
+  font-size: var(--pcoi-semantic-type-body-compact-size);
+  color: var(--pcoi-semantic-text-secondary);
+  line-height: var(--pcoi-semantic-type-body-line-height);
+}