@gcsa/console-react 0.1.0

package/src/GcsaChatPanel.tsx

@@ -0,0 +1,320 @@
+import { useContext, useEffect, useRef, useState, type ReactNode } from 'react';
+import type {
+  GcsaChatMarkdownMode,
+  GcsaChatMessage,
+  GcsaChatMessageRole
+} from '@gcsa/console-core';
+import {
+  copyGcsaText,
+  formatGcsaChatTime,
+  gcsaChatAvatarLabel,
+  shouldRenderGcsaChatMarkdown
+} from '@gcsa/console-core';
+import { GcsaButton } from './GcsaButton';
+import { GcsaMarkdownRenderer } from './GcsaMarkdownRenderer';
+import { GcsaMessageContext } from './hooks/useGcsaTheme';
+import { useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+
+export type GcsaChatMessageRenderContext = {
+  message: GcsaChatMessage;
+  index: number;
+};
+
+export type GcsaChatPanelProps = {
+  messages: GcsaChatMessage[];
+  loading?: boolean;
+  disabled?: boolean;
+  placeholder?: string;
+  sendLabel?: string;
+  sendingLabel?: string;
+  emptyText?: string;
+  renderMarkdown?: GcsaChatMarkdownMode;
+  showTimestamp?: boolean;
+  showAvatars?: boolean;
+  copyable?: boolean;
+  copyLabel?: string;
+  copySuccessLabel?: string;
+  copyErrorLabel?: string;
+  streamingCursor?: string;
+  avatarLabels?: Partial<Record<GcsaChatMessageRole, string>>;
+  header?: ReactNode;
+  empty?: ReactNode;
+  renderMessage?: (ctx: GcsaChatMessageRenderContext) => ReactNode;
+  renderAvatar?: (ctx: GcsaChatMessageRenderContext) => ReactNode;
+  renderMessageContent?: (ctx: GcsaChatMessageRenderContext) => ReactNode;
+  renderMessageFooter?: (ctx: GcsaChatMessageRenderContext) => ReactNode;
+  renderMessageActions?: (ctx: GcsaChatMessageRenderContext) => ReactNode;
+  renderComposer?: (ctx: {
+    draft: string;
+    setDraft: (value: string) => void;
+    submit: () => void;
+    loading: boolean;
+    disabled: boolean;
+  }) => ReactNode;
+  composerPrefix?: ReactNode;
+  composerActions?: ReactNode;
+  onSend?: (content: string) => void;
+  onCopy?: (message: GcsaChatMessage) => void;
+};
+
+function timeIso(value?: string | number | Date) {
+  if (value == null || value === '') return undefined;
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return undefined;
+  return date.toISOString();
+}
+
+export function GcsaChatPanel({
+  messages,
+  loading = false,
+  disabled = false,
+  placeholder,
+  sendLabel,
+  sendingLabel,
+  emptyText,
+  renderMarkdown = 'assistant',
+  showTimestamp = true,
+  showAvatars = true,
+  copyable = true,
+  copyLabel,
+  copySuccessLabel,
+  copyErrorLabel,
+  streamingCursor = '▍',
+  avatarLabels,
+  header,
+  empty,
+  renderMessage,
+  renderAvatar,
+  renderMessageContent,
+  renderMessageFooter,
+  renderMessageActions,
+  renderComposer,
+  composerPrefix,
+  composerActions,
+  onSend,
+  onCopy
+}: GcsaChatPanelProps) {
+  const localeMessages = useGcsaLocaleMessages();
+  const resolvedPlaceholder = placeholder ?? localeMessages.chatPlaceholder;
+  const resolvedSendLabel = sendLabel ?? localeMessages.chatSend;
+  const resolvedSendingLabel = sendingLabel ?? localeMessages.chatSending;
+  const resolvedEmptyText = emptyText ?? localeMessages.chatEmpty;
+  const resolvedCopyLabel = copyLabel ?? localeMessages.chatCopy;
+  const resolvedCopySuccessLabel = copySuccessLabel ?? localeMessages.chatCopySuccess;
+  const resolvedCopyErrorLabel = copyErrorLabel ?? localeMessages.chatCopyError;
+  const [draft, setDraft] = useState('');
+  const [copyToast, setCopyToast] = useState<{ text: string; type: 'success' | 'error' } | null>(null);
+  const listRef = useRef<HTMLDivElement | null>(null);
+  const copyToastTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const messageApi = useContext(GcsaMessageContext);
+
+  useEffect(() => {
+    if (listRef.current) {
+      listRef.current.scrollTop = listRef.current.scrollHeight;
+    }
+  }, [messages.length, messages[messages.length - 1]?.content, messages[messages.length - 1]?.status]);
+
+  const submit = () => {
+    const content = draft.trim();
+    if (!content || loading || disabled) return;
+    onSend?.(content);
+    setDraft('');
+  };
+
+  useEffect(() => {
+    return () => {
+      if (copyToastTimerRef.current) clearTimeout(copyToastTimerRef.current);
+    };
+  }, []);
+
+  const showCopyFeedback = (text: string, tone: 'success' | 'error' = 'success') => {
+    if (messageApi) {
+      messageApi[tone](text);
+      return;
+    }
+
+    setCopyToast({ text, type: tone });
+    if (copyToastTimerRef.current) clearTimeout(copyToastTimerRef.current);
+    copyToastTimerRef.current = setTimeout(() => {
+      setCopyToast(null);
+      copyToastTimerRef.current = null;
+    }, 2000);
+  };
+
+  const copyMessage = async (message: GcsaChatMessage) => {
+    const ok = await copyGcsaText(message.content);
+    onCopy?.(message);
+    showCopyFeedback(ok ? resolvedCopySuccessLabel : resolvedCopyErrorLabel, ok ? 'success' : 'error');
+  };
+
+  const onKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
+      submit();
+    }
+  };
+
+  const renderDefaultMessage = (ctx: GcsaChatMessageRenderContext) => {
+    const { message, index } = ctx;
+    const useMarkdown = shouldRenderGcsaChatMarkdown(message, renderMarkdown);
+
+    return (
+      <article
+        key={message.id}
+        className={[
+          'gcsa-chat__message',
+          `gcsa-chat__message--${message.role}`,
+          message.systemReady ? 'gcsa-chat__message--system-ready' : '',
+          message.error || message.status === 'error' ? 'gcsa-chat__message--error' : '',
+          message.status === 'streaming' ? 'gcsa-chat__message--streaming' : ''
+        ]
+          .filter(Boolean)
+          .join(' ')}
+      >
+        {showAvatars && message.role !== 'system' ? (
+          <div className={`gcsa-chat__avatar gcsa-chat__avatar--${message.role}`}>
+            {renderAvatar ? (
+              renderAvatar(ctx)
+            ) : (
+              <div className="gcsa-avatar">{gcsaChatAvatarLabel(message, avatarLabels)}</div>
+            )}
+          </div>
+        ) : null}
+
+        <div className="gcsa-chat__message-body">
+          <div
+            className={[
+              'gcsa-chat__bubble',
+              `gcsa-chat__bubble--${message.role}`,
+              useMarkdown ? 'gcsa-chat__bubble--rich' : ''
+            ]
+              .filter(Boolean)
+              .join(' ')}
+          >
+            {renderMessageContent ? (
+              renderMessageContent(ctx)
+            ) : (
+              <>
+                {useMarkdown ? (
+                  <GcsaMarkdownRenderer content={message.content} />
+                ) : (
+                  <p className="gcsa-chat__plain">{message.content}</p>
+                )}
+                {message.status === 'streaming' ? (
+                  <span className="gcsa-chat__cursor" aria-hidden="true">
+                    {streamingCursor}
+                  </span>
+                ) : null}
+              </>
+            )}
+
+            {copyable && message.role === 'assistant' && message.content ? (
+              <div className="gcsa-chat__bubble-actions">
+                {renderMessageActions ? (
+                  renderMessageActions(ctx)
+                ) : (
+                  <button
+                    type="button"
+                    className="gcsa-chat__action-btn"
+                    title={resolvedCopyLabel}
+                    aria-label={resolvedCopyLabel}
+                    onClick={() => copyMessage(message)}
+                  >
+                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                      <rect x="9" y="9" width="13" height="13" rx="2" stroke="currentColor" strokeWidth="1.5" />
+                      <path
+                        d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"
+                        stroke="currentColor"
+                        strokeWidth="1.5"
+                      />
+                    </svg>
+                  </button>
+                )}
+              </div>
+            ) : null}
+          </div>
+
+          {showTimestamp && message.role !== 'system' ? (
+            <footer className="gcsa-chat__meta">
+              {renderMessageFooter ? (
+                renderMessageFooter(ctx)
+              ) : formatGcsaChatTime(message.createdAt) ? (
+                <time dateTime={timeIso(message.createdAt)}>
+                  {formatGcsaChatTime(message.createdAt)}
+                </time>
+              ) : null}
+            </footer>
+          ) : null}
+        </div>
+      </article>
+    );
+  };
+
+  const composer = renderComposer ? (
+    renderComposer({ draft, setDraft, submit, loading, disabled })
+  ) : (
+    <div className="gcsa-chat__composer">
+      {composerPrefix}
+      <textarea
+        className="gcsa-textarea gcsa-chat__input"
+        value={draft}
+        placeholder={resolvedPlaceholder}
+        disabled={disabled || loading}
+        rows={1}
+        onChange={e => setDraft(e.target.value)}
+        onKeyDown={onKeyDown}
+      />
+      {composerActions ?? (
+        <GcsaButton disabled={!draft.trim() || loading || disabled} onClick={submit}>
+          {loading ? resolvedSendingLabel : resolvedSendLabel}
+        </GcsaButton>
+      )}
+    </div>
+  );
+
+  return (
+    <section className="gcsa-chat gcsa-ui-surface">
+      {copyToast ? (
+        <div
+          className={`gcsa-chat__toast gcsa-toast gcsa-toast--${copyToast.type}`}
+          role="status"
+        >
+          <span className="gcsa-toast__icon" aria-hidden="true">
+            {copyToast.type === 'success' ? (
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none">
+                <path
+                  d="M20 6 9 17l-5-5"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+              </svg>
+            ) : (
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none">
+                <path d="M15 9l-6 6M9 9l6 6" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
+                <circle cx="12" cy="12" r="9" stroke="currentColor" strokeWidth="1.75" />
+              </svg>
+            )}
+          </span>
+          <span className="gcsa-toast__content">{copyToast.text}</span>
+        </div>
+      ) : null}
+      {header ? <header className="gcsa-chat__header">{header}</header> : null}
+
+      <div className="gcsa-chat__messages" ref={listRef}>
+        {!messages.length ? (
+          <div className="gcsa-chat__empty">{empty ?? resolvedEmptyText}</div>
+        ) : null}
+
+        {messages.map((message, index) =>
+          renderMessage
+            ? renderMessage({ message, index })
+            : renderDefaultMessage({ message, index })
+        )}
+      </div>
+
+      {composer}
+    </section>
+  );
+}

package/src/GcsaCheckbox.tsx

@@ -0,0 +1,55 @@
+import { useRef, type ReactNode } from 'react';
+import { Checkbox } from '@ark-ui/react/checkbox';
+import { usePreventHiddenInputScroll } from './hooks/usePreventHiddenInputScroll';
+
+export type GcsaCheckboxProps = {
+  checked?: boolean;
+  label?: string;
+  ariaLabel?: string;
+  disabled?: boolean;
+  className?: string;
+  children?: ReactNode;
+  onCheckedChange?: (checked: boolean) => void;
+};
+
+export function GcsaCheckbox({
+  checked,
+  label,
+  ariaLabel,
+  disabled,
+  className,
+  children,
+  onCheckedChange
+}: GcsaCheckboxProps) {
+  const rootRef = useRef<HTMLLabelElement>(null);
+  usePreventHiddenInputScroll(rootRef);
+  return (
+    <Checkbox.Root
+      ref={rootRef}
+      checked={checked}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      className={`gcsa-checkbox gcsa-focus-ring${className ? ` ${className}` : ''}`}
+      onCheckedChange={details => onCheckedChange?.(details.checked === true)}
+    >
+      <Checkbox.Control className="gcsa-checkbox__box">
+        <Checkbox.Indicator className="gcsa-checkbox__indicator">
+          <svg viewBox="0 0 12 12" width="10" height="10" aria-hidden="true">
+            <path
+              d="M2 6.2L4.8 9 10 3.2"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.8"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+        </Checkbox.Indicator>
+      </Checkbox.Control>
+      {label || children ? (
+        <Checkbox.Label className="gcsa-checkbox__label">{children ?? label}</Checkbox.Label>
+      ) : null}
+      <Checkbox.HiddenInput />
+    </Checkbox.Root>
+  );
+}

package/src/GcsaCollapse.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import { useState } from 'react';
+
+export type GcsaCollapseItem = { key: string; title: string; content?: ReactNode; disabled?: boolean };
+export type GcsaCollapseProps = { items: GcsaCollapseItem[]; openKeys?: string[]; defaultOpenKeys?: string[]; accordion?: boolean; bordered?: boolean; onOpenKeysChange?: (keys: string[]) => void };
+
+export function GcsaCollapse({ items, openKeys, defaultOpenKeys = [], accordion = false, bordered = true, onOpenKeysChange }: GcsaCollapseProps) {
+  const [internalKeys, setInternalKeys] = useState(defaultOpenKeys);
+  const keys = openKeys ?? internalKeys;
+  function toggle(key: string) {
+    const next = keys.includes(key) ? keys.filter(value => value !== key) : accordion ? [key] : [...keys, key];
+    setInternalKeys(next);
+    onOpenKeysChange?.(next);
+  }
+  return <div className={`gcsa-collapse${bordered ? ' gcsa-collapse--bordered' : ''}`}>
+    {items.map(item => <section key={item.key} className="gcsa-collapse__item" data-open={keys.includes(item.key) || undefined}>
+      <button type="button" className="gcsa-collapse__trigger gcsa-focus-ring" disabled={item.disabled} aria-expanded={keys.includes(item.key)} aria-controls={`gcsa-collapse-${item.key}`} onClick={() => toggle(item.key)}>
+        <span className="gcsa-collapse__indicator" aria-hidden="true">{keys.includes(item.key) ? '−' : '+'}</span><span className="gcsa-collapse__title">{item.title}</span>
+      </button>
+      {keys.includes(item.key) ? <div id={`gcsa-collapse-${item.key}`} className="gcsa-collapse__content" role="region">{item.content}</div> : null}
+    </section>)}
+  </div>;
+}

package/src/GcsaConfigProvider.tsx

@@ -0,0 +1,121 @@
+import { useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import type { GcsaConsoleTheme, GcsaConsoleLocale, GcsaMessageType, GcsaComponentSize } from '@gcsa/console-core';
+import { GCSA_MESSAGE_DURATION_MS } from '@gcsa/console-core';
+import {
+  GcsaConfigProviderContext,
+  GcsaMessageContext,
+  GcsaThemeContext
+} from './hooks/useGcsaTheme';
+import type { GcsaMessageApi } from './hooks/useMessage';
+import { GcsaLocaleContext } from './hooks/useGcsaLocale';
+import { GcsaRestoreDocumentThemeContext } from './hooks/useDocumentThemeSync';
+import { GcsaToastStack } from './GcsaToastStack';
+import { GcsaZIndexContext, createGcsaZIndexApi, readToastZIndex } from './hooks/useGcsaZIndex';
+import { GcsaComponentSizeContext } from './hooks/useGcsaComponentSize';
+
+export type GcsaConfigProviderProps = {
+  theme?: GcsaConsoleTheme;
+  /** 界面语言（zh-CN / zh-TW / en-US） */
+  locale?: GcsaConsoleLocale;
+  /** 是否同步到 document（Portal 浮层）。文档站 demo 应关闭，由 VitePress 全局同步。 */
+  syncDocument?: boolean;
+  /** 全局控件尺寸（Button / Select / InputGroup / Switch / Table 等） */
+  size?: GcsaComponentSize;
+  children: ReactNode;
+};
+
+export function GcsaConfigProvider({
+  theme = 'dark',
+  locale = 'zh-CN',
+  syncDocument = true,
+  size,
+  children
+}: GcsaConfigProviderProps) {
+  const parentProvider = useContext(GcsaConfigProviderContext);
+  const parentZIndexApi = useContext(GcsaZIndexContext);
+  const parentSize = useContext(GcsaComponentSizeContext);
+  const restoreDocumentTheme = useContext(GcsaRestoreDocumentThemeContext);
+  const [toasts, setToasts] = useState<Array<{ id: number; message: string; type: GcsaMessageType }>>([]);
+  const [toastZIndex, setToastZIndex] = useState<number>(() => readToastZIndex());
+  const idRef = useRef(0);
+  const MAX_TOASTS = 4;
+
+  const zIndexApi = useMemo(
+    () => parentZIndexApi ?? createGcsaZIndexApi(),
+    [parentZIndexApi]
+  );
+
+  const shouldSyncDocument = !parentProvider && syncDocument;
+  const resolvedSize = size ?? parentSize ?? 'md';
+
+  const refreshToastZIndex = () => {
+    setToastZIndex(readToastZIndex());
+  };
+
+  const push = (message: string, type: GcsaMessageType) => {
+    refreshToastZIndex();
+    const current = ++idRef.current;
+    setToasts(prev => [...prev, { id: current, message, type }].slice(-MAX_TOASTS));
+    setTimeout(() => {
+      setToasts(prev => prev.filter(t => t.id !== current));
+    }, GCSA_MESSAGE_DURATION_MS);
+  };
+
+  const api: GcsaMessageApi = {
+    success: message => push(message, 'success'),
+    error: message => push(message, 'error'),
+    info: message => push(message, 'info')
+  };
+
+  useEffect(() => {
+    if (!shouldSyncDocument || typeof document === 'undefined') return;
+    document.documentElement.setAttribute('data-gcsa-theme', theme);
+  }, [theme, shouldSyncDocument]);
+
+  useEffect(() => {
+    refreshToastZIndex();
+  }, []);
+
+  useEffect(() => {
+    if (!shouldSyncDocument) return;
+    return () => {
+      if (typeof document === 'undefined') return;
+      if (restoreDocumentTheme) {
+        restoreDocumentTheme();
+        return;
+      }
+      document.documentElement.removeAttribute('data-gcsa-theme');
+    };
+  }, [shouldSyncDocument, restoreDocumentTheme]);
+
+  return (
+    <GcsaConfigProviderContext.Provider value={true}>
+      <GcsaZIndexContext.Provider value={zIndexApi}>
+        <GcsaComponentSizeContext.Provider value={resolvedSize}>
+          <GcsaMessageContext.Provider value={api}>
+            <GcsaThemeContext.Provider value={theme}>
+              <GcsaLocaleContext.Provider value={locale}>
+                <div className="gcsa-console-root" data-gcsa-theme={theme}>
+                  {children}
+                </div>
+                {typeof document !== 'undefined'
+                  ? createPortal(
+                      <div
+                        className="gcsa-portal-scope gcsa-toast-portal"
+                        data-gcsa-theme={theme}
+                        style={{ zIndex: toastZIndex }}
+                      >
+                        <GcsaToastStack toasts={toasts} />
+                      </div>,
+                      document.body
+                    )
+                  : null}
+              </GcsaLocaleContext.Provider>
+            </GcsaThemeContext.Provider>
+          </GcsaMessageContext.Provider>
+        </GcsaComponentSizeContext.Provider>
+      </GcsaZIndexContext.Provider>
+    </GcsaConfigProviderContext.Provider>
+  );
+}