@gcsa/console-react 0.1.0

package/src/GcsaUpload.tsx

@@ -0,0 +1,206 @@
+import { useRef, useState } from 'react';
+import { GcsaIcon } from './GcsaIcon';
+import { useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+
+export type GcsaUploadProps = {
+  files?: File[];
+  accept?: string;
+  multiple?: boolean;
+  disabled?: boolean;
+  buttonLabel?: string;
+  hint?: string;
+  maxCount?: number;
+  maxSize?: number;
+  drag?: boolean;
+  directory?: boolean;
+  dragLabel?: string;
+  uploadingLabel?: string;
+  uploadErrorLabel?: string;
+  upload?: (file: File, onProgress?: (percent: number) => void) => Promise<void> | void;
+  retryLabel?: string;
+  onProgress?: (file: File, percent: number) => void;
+  onUploadStart?: (file: File) => void;
+  onUploadSuccess?: (file: File) => void;
+  onUploadError?: (file: File, error: unknown) => void;
+  className?: string;
+  onFilesChange?: (files: File[]) => void;
+};
+
+export function GcsaUpload({
+  files = [],
+  accept,
+  multiple = false,
+  disabled,
+  buttonLabel,
+  hint,
+  maxCount,
+  className,
+  onFilesChange,
+  maxSize,
+  drag = false,
+  directory = false,
+  dragLabel,
+  uploadingLabel,
+  uploadErrorLabel,
+  upload,
+  retryLabel,
+  onProgress,
+  onUploadStart,
+  onUploadSuccess,
+  onUploadError
+}: GcsaUploadProps) {
+  const messages = useGcsaLocaleMessages();
+  const resolvedButtonLabel = buttonLabel ?? messages.uploadSelectFile;
+  const resolvedDragLabel = dragLabel ?? messages.uploadDragHint;
+  const resolvedUploadingLabel = uploadingLabel ?? messages.uploadUploading;
+  const resolvedUploadErrorLabel = uploadErrorLabel ?? messages.uploadFailed;
+  const resolvedRetryLabel = retryLabel ?? messages.uploadRetry;
+  const resolvedHint = hint || (drag ? resolvedDragLabel : undefined);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const [dragging, setDragging] = useState(false);
+  const [statuses, setStatuses] = useState<Map<File, 'uploading' | 'success' | 'error'>>(new Map());
+  const [progress, setProgress] = useState<Map<File, number>>(new Map());
+
+  function openPicker() {
+    inputRef.current?.click();
+  }
+
+  function onNativeChange(event: React.ChangeEvent<HTMLInputElement>) {
+    const picked = Array.from(event.target.files ?? []);
+    event.target.value = '';
+    if (!picked.length) return;
+
+    acceptFiles(picked);
+  }
+
+  function acceptFiles(picked: File[]) {
+    const valid = maxSize == null ? picked : picked.filter(file => file.size <= maxSize);
+    let next = multiple ? [...files, ...valid] : valid.slice(0, 1);
+    if (maxCount != null) next = next.slice(0, maxCount);
+    onFilesChange?.(next);
+    if (upload) next.filter(file => valid.includes(file)).forEach(uploadFile);
+  }
+
+  function onDragEnter(event: React.DragEvent<HTMLDivElement>) {
+    event.preventDefault();
+    if (!drag || disabled) return;
+    setDragging(true);
+  }
+
+  function onDrop(event: React.DragEvent<HTMLDivElement>) {
+    event.preventDefault();
+    setDragging(false);
+    if (!drag || disabled) return;
+    acceptFiles(Array.from(event.dataTransfer.files));
+  }
+
+  async function uploadFile(file: File) {
+    if (!upload) return;
+    setStatuses(current => new Map(current).set(file, 'uploading'));
+    setProgress(current => new Map(current).set(file, 0));
+    onUploadStart?.(file);
+    try {
+      await upload(file, percent => {
+        const next = Math.max(0, Math.min(100, Math.round(percent)));
+        setProgress(current => new Map(current).set(file, next));
+        onProgress?.(file, next);
+      });
+      setStatuses(current => new Map(current).set(file, 'success'));
+      setProgress(current => new Map(current).set(file, 100));
+      onUploadSuccess?.(file);
+    } catch (error) {
+      setStatuses(current => new Map(current).set(file, 'error'));
+      onUploadError?.(file, error);
+    }
+  }
+
+  function removeAt(index: number) {
+    onFilesChange?.(files.filter((_, i) => i !== index));
+  }
+
+  function formatSize(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+
+  return (
+    <div
+      className={`gcsa-upload${disabled ? ' gcsa-upload--disabled' : ''}${dragging ? ' gcsa-upload--dragging' : ''}${className ? ` ${className}` : ''}`}
+    >
+      <input
+        ref={inputRef}
+        type="file"
+        className="gcsa-upload__native"
+        accept={accept}
+        multiple={multiple}
+        {...(directory ? { webkitdirectory: '' } : {})}
+        disabled={disabled}
+        onChange={onNativeChange}
+      />
+      <div
+        className="gcsa-upload__dropzone"
+        role="button"
+        tabIndex={0}
+        onClick={openPicker}
+        onKeyDown={event => {
+          if (event.key === 'Enter' || event.key === ' ') openPicker();
+        }}
+        onDragEnter={onDragEnter}
+        onDragOver={onDragEnter}
+        onDragLeave={() => setDragging(false)}
+        onDrop={onDrop}
+      >
+        <span className="gcsa-upload__icon" aria-hidden="true">
+          <GcsaIcon name="plus" />
+        </span>
+        <span className="gcsa-upload__title">{resolvedButtonLabel}</span>
+        {resolvedHint ? <p className="gcsa-upload__hint">{resolvedHint}</p> : null}
+      </div>
+      {files.length > 0 ? (
+        <ul className="gcsa-upload__list">
+          {files.map((file, index) => (
+            <li key={`${file.name}-${index}`} className="gcsa-upload__item">
+              <span className="gcsa-upload__name">{file.name}</span>
+              <span className="gcsa-upload__size">{formatSize(file.size)}</span>
+              {statuses.get(file) === 'uploading' ? (
+                <span className="gcsa-upload__status" role="status">
+                  {resolvedUploadingLabel} {progress.get(file) ?? 0}%
+                </span>
+              ) : null}
+              {statuses.get(file) === 'error' ? (
+                <span className="gcsa-upload__status gcsa-upload__status--error" role="alert">
+                  {resolvedUploadErrorLabel}
+                </span>
+              ) : null}
+              {statuses.get(file) === 'uploading' ? (
+                <div className="gcsa-upload__progress" aria-hidden="true">
+                  <span style={{ width: `${progress.get(file) ?? 0}%` }} />
+                </div>
+              ) : null}
+              {statuses.get(file) === 'error' ? (
+                <button
+                  type="button"
+                  className="gcsa-upload__retry gcsa-focus-ring"
+                  disabled={disabled}
+                  onClick={() => uploadFile(file)}
+                >
+                  {resolvedRetryLabel}
+                </button>
+              ) : null}
+              <button
+                type="button"
+                className="gcsa-upload__remove gcsa-focus-ring"
+                disabled={disabled}
+                aria-label={messages.uploadRemoveFile}
+                onClick={() => removeAt(index)}
+              >
+                {messages.remove}
+              </button>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </div>
+  );
+}

package/src/hooks/gcsaFormTypes.ts

@@ -0,0 +1,23 @@
+import type { ReactFormExtendedApi } from '@tanstack/react-form';
+
+export type GcsaFormValues = Record<string, unknown>;
+
+/**
+ * Form instance used by GcsaForm / GcsaFormField.
+ * Validator generics are relaxed so schema-backed forms remain assignable.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GcsaFormApi = ReactFormExtendedApi<
+  GcsaFormValues,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any
+>;

package/src/hooks/useDocumentThemeSync.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+
+/** Docs / app may provide this to restore document theme after ConfigProvider unmounts. */
+export const GcsaRestoreDocumentThemeContext = createContext<(() => void) | null>(null);
+
+export const GCSA_RESTORE_DOCUMENT_THEME_KEY = Symbol('gcsa-restore-document-theme');

package/src/hooks/useGcsaComponentSize.ts

@@ -0,0 +1,24 @@
+import { createContext, useContext } from 'react';
+import {
+  GCSA_DEFAULT_COMPONENT_SIZE,
+  resolveGcsaButtonSize,
+  resolveGcsaComponentSize,
+  type GcsaButtonSize,
+  type GcsaComponentSize
+} from '@gcsa/console-core';
+
+export const GcsaComponentSizeContext = createContext<GcsaComponentSize>(GCSA_DEFAULT_COMPONENT_SIZE);
+
+export function useGcsaComponentSizeConfig(): GcsaComponentSize {
+  return useContext(GcsaComponentSizeContext);
+}
+
+export function useGcsaComponentSize(propSize?: GcsaComponentSize): GcsaComponentSize {
+  const configSize = useGcsaComponentSizeConfig();
+  return resolveGcsaComponentSize(propSize, configSize);
+}
+
+export function useGcsaButtonSize(propSize?: GcsaButtonSize): GcsaButtonSize {
+  const configSize = useGcsaComponentSizeConfig();
+  return resolveGcsaButtonSize(propSize, configSize);
+}

package/src/hooks/useGcsaFormField.ts

@@ -0,0 +1,49 @@
+import type { FieldApi } from '@tanstack/react-form';
+
+/** TanStack FieldApi with relaxed generics for field binding helpers. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GcsaAnyFieldApi = FieldApi<any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any>;
+
+export function gcsaTextFieldBindings(field: GcsaAnyFieldApi) {
+  const error = field.state.meta.errors[0];
+  return {
+    value: (field.state.value as string) ?? '',
+    invalid: Boolean(error),
+    onBlur: () => field.handleBlur(),
+    onChange: (value: string) => field.handleChange(value)
+  };
+}
+
+export function gcsaBooleanFieldBindings(field: GcsaAnyFieldApi) {
+  return {
+    checked: Boolean(field.state.value),
+    onCheckedChange: (value: boolean) => field.handleChange(value)
+  };
+}
+
+export function gcsaRadioFieldBindings(field: GcsaAnyFieldApi) {
+  const error = field.state.meta.errors[0];
+  return {
+    value: (field.state.value as string) ?? '',
+    invalid: Boolean(error),
+    onValueChange: (value: string) => field.handleChange(value)
+  };
+}
+
+export function gcsaNumberFieldBindings(field: GcsaAnyFieldApi) {
+  const error = field.state.meta.errors[0];
+  return {
+    value: field.state.value as number | null,
+    invalid: Boolean(error),
+    onBlur: () => field.handleBlur(),
+    onValueChange: (value: number | null) => field.handleChange(value)
+  };
+}
+
+export function gcsaFieldError(field: GcsaAnyFieldApi) {
+  return field.state.meta.errors[0] as string | undefined;
+}
+
+export function gcsaFieldInvalid(field: GcsaAnyFieldApi) {
+  return field.state.meta.errors.length > 0;
+}

package/src/hooks/useGcsaFormSchema.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+import type { ZodObject, ZodTypeAny } from 'zod';
+
+export const GcsaFormSchemaContext = createContext<ZodObject<Record<string, ZodTypeAny>> | null>(null);
+
+export const GCSA_FORM_SCHEMA_KEY = Symbol('gcsa-form-schema');

package/src/hooks/useGcsaLocale.ts

@@ -0,0 +1,16 @@
+import { createContext, useContext } from 'react';
+import {
+  GCSA_DEFAULT_LOCALE,
+  getGcsaLocaleMessages,
+  type GcsaConsoleLocale
+} from '@gcsa/console-core';
+
+export const GcsaLocaleContext = createContext<GcsaConsoleLocale>(GCSA_DEFAULT_LOCALE);
+
+export function useGcsaLocale(): GcsaConsoleLocale {
+  return useContext(GcsaLocaleContext);
+}
+
+export function useGcsaLocaleMessages() {
+  return getGcsaLocaleMessages(useGcsaLocale());
+}

package/src/hooks/useGcsaPopupZIndex.ts

@@ -0,0 +1,23 @@
+import { useCallback, useState } from 'react';
+import { useGcsaZIndex } from './useGcsaZIndex';
+
+/** Select / Dropdown / Popover 等：打开时领取高于当前 overlay 的 z-index */
+export function useGcsaPopupZIndex() {
+  const { nextZIndex } = useGcsaZIndex();
+  const [zIndex, setZIndex] = useState<number>();
+
+  const claimZIndex = useCallback(() => {
+    const next = nextZIndex();
+    setZIndex(next);
+    return next;
+  }, [nextZIndex]);
+
+  const onOpenChange = useCallback(
+    (open: boolean) => {
+      if (open) claimZIndex();
+    },
+    [claimZIndex]
+  );
+
+  return { zIndex, claimZIndex, onOpenChange };
+}

package/src/hooks/useGcsaTextCount.ts

@@ -0,0 +1,44 @@
+import { useMemo } from 'react';
+
+export type GcsaTextCountFormatter = (info: {
+  value: string;
+  count: number;
+  maxLength?: number;
+}) => string;
+
+export function useGcsaTextCount(options: {
+  modelValue: string;
+  maxLength?: number;
+  showCount?: boolean;
+  formatter?: GcsaTextCountFormatter;
+}) {
+  const showCounter = useMemo(() => {
+    const max = options.maxLength;
+    const explicit = options.showCount;
+
+    if (explicit === true) return true;
+    if (explicit === false) return false;
+    return max != null;
+  }, [options.maxLength, options.showCount]);
+
+  const count = options.modelValue?.length ?? 0;
+
+  const countText = useMemo(() => {
+    const value = options.modelValue ?? '';
+    const max = options.maxLength;
+
+    if (options.formatter) {
+      return options.formatter({ value, count, maxLength: max });
+    }
+
+    if (max != null) {
+      return `${count}/${max}`;
+    }
+
+    return String(count);
+  }, [options.modelValue, options.formatter, options.maxLength, count]);
+
+  const isNearLimit = options.maxLength != null && count >= options.maxLength * 0.9;
+
+  return { showCounter, count, countText, isNearLimit };
+}

package/src/hooks/useGcsaTheme.ts

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+import type { GcsaConsoleTheme } from '@gcsa/console-core';
+import type { GcsaMessageApi } from './useMessage';
+
+export const GcsaMessageContext = createContext<GcsaMessageApi | null>(null);
+export const GcsaThemeContext = createContext<GcsaConsoleTheme>('dark');
+export const GcsaConfigProviderContext = createContext(false);
+
+export function useGcsaMessage(): GcsaMessageApi {
+  const api = useContext(GcsaMessageContext);
+  if (!api) {
+    throw new Error('useGcsaMessage must be used within GcsaConfigProvider');
+  }
+  return api;
+}
+
+export function useGcsaTheme(): GcsaConsoleTheme {
+  return useContext(GcsaThemeContext);
+}

package/src/hooks/useGcsaZIndex.ts

@@ -0,0 +1,60 @@
+import { createContext, useCallback, useContext } from 'react';
+
+export type GcsaZIndexApi = {
+  next: () => number;
+};
+
+export const GcsaZIndexContext = createContext<GcsaZIndexApi | null>(null);
+
+const FALLBACK_INITIAL = 2000;
+const FALLBACK_TOAST = 1300;
+const Z_INDEX_STEP = 2;
+
+function readCssZIndex(token: string, fallback: number): number {
+  if (typeof document === 'undefined') return fallback;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue(token).trim();
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export function readToastZIndex(): number {
+  const toast = readCssZIndex('--gcsa-z-toast', Number.NaN);
+  const overlay = readCssZIndex('--z-overlay-toast', Number.NaN);
+  const candidates = [toast, overlay, FALLBACK_TOAST].filter(value => Number.isFinite(value));
+  return Math.max(...candidates);
+}
+
+function readInitialZIndex(): number {
+  if (typeof document === 'undefined') return FALLBACK_INITIAL;
+  const root = document.documentElement;
+  const initial = getComputedStyle(root).getPropertyValue('--gcsa-z-index-initial').trim();
+  const parsedInitial = Number.parseInt(initial, 10);
+  if (Number.isFinite(parsedInitial)) return parsedInitial;
+  const modal = getComputedStyle(root).getPropertyValue('--gcsa-z-modal').trim();
+  const parsedModal = Number.parseInt(modal, 10);
+  return Number.isFinite(parsedModal) ? parsedModal : FALLBACK_INITIAL;
+}
+
+export function createGcsaZIndexApi(initial?: number): GcsaZIndexApi {
+  let current = initial ?? readInitialZIndex();
+  return {
+    next() {
+      current += Z_INDEX_STEP;
+      return current;
+    }
+  };
+}
+
+/**
+ * 与 Vue `useGcsaZIndex` 同职责：从 ConfigProvider 的共享计数器领取下一层 z-index。
+ * `nextZIndex` 引用稳定，避免 overlay 在每次父级重渲染时重复抢占层级。
+ */
+export function useGcsaZIndex() {
+  const api = useContext(GcsaZIndexContext);
+
+  const nextZIndex = useCallback(() => {
+    return api?.next() ?? FALLBACK_INITIAL + Z_INDEX_STEP;
+  }, [api]);
+
+  return { nextZIndex };
+}

package/src/hooks/useMessage.ts

@@ -0,0 +1,7 @@
+export type GcsaMessageApi = {
+  success: (message: string) => void;
+  error: (message: string) => void;
+  info: (message: string) => void;
+};
+
+export const GCSA_MESSAGE_KEY = Symbol('gcsa-message');

package/src/hooks/useOverlayZIndex.ts

@@ -0,0 +1,23 @@
+import { useEffect, useRef, useState } from 'react';
+import { useGcsaZIndex } from './useGcsaZIndex';
+
+/**
+ * Modal / Drawer：仅在 open 变为 true 时分配 backdrop + positioner 两层 z-index（与 Vue watch(open) 一致）。
+ * 打开期间父组件重渲染不得再次 claim，否则会盖住内部后打开的 Select/Dropdown。
+ */
+export function useGcsaOverlayZIndex(open: boolean) {
+  const { nextZIndex } = useGcsaZIndex();
+  const nextZIndexRef = useRef(nextZIndex);
+  nextZIndexRef.current = nextZIndex;
+
+  const [backdropZ, setBackdropZ] = useState<number>();
+  const [positionerZ, setPositionerZ] = useState<number>();
+
+  useEffect(() => {
+    if (!open) return;
+    setBackdropZ(nextZIndexRef.current());
+    setPositionerZ(nextZIndexRef.current());
+  }, [open]);
+
+  return { backdropZ, positionerZ };
+}