@gcsa/console-react 0.1.0

package/src/GcsaForm.tsx

@@ -0,0 +1,82 @@
+import type { ReactNode } from 'react';
+import type { ZodObject, ZodTypeAny } from 'zod';
+import { useForm } from '@tanstack/react-form';
+import { GcsaButton } from './GcsaButton';
+import { GcsaFormSchemaContext } from './hooks/useGcsaFormSchema';
+import { useGcsaLocale, useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+import { zodFormValidator } from './utils/zodValidators';
+import type { GcsaFormApi } from './hooks/gcsaFormTypes';
+
+export type GcsaFormProps = {
+  defaultValues: Record<string, unknown>;
+  schema?: ZodObject<Record<string, ZodTypeAny>>;
+  onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+  submitLabel?: string;
+  resetLabel?: string;
+  showActions?: boolean;
+  children: ReactNode | ((form: GcsaFormApi) => ReactNode);
+};
+
+export function GcsaForm({
+  defaultValues,
+  schema,
+  onSubmit,
+  submitLabel,
+  resetLabel,
+  showActions = true,
+  children
+}: GcsaFormProps) {
+  const messages = useGcsaLocaleMessages();
+  const locale = useGcsaLocale();
+  const resolvedSubmitLabel = submitLabel ?? messages.formSubmit;
+  const resolvedResetLabel = resetLabel ?? messages.formReset;
+
+  const form = useForm({
+    defaultValues,
+    validators: schema
+      ? {
+          onSubmit: zodFormValidator(schema, locale)
+        }
+      : undefined,
+    onSubmit: async ({ value }) => {
+      if (schema) {
+        const parsed = schema.safeParse(value);
+        if (!parsed.success) return;
+        await onSubmit?.(parsed.data as Record<string, unknown>);
+        return;
+      }
+      await onSubmit?.(value as Record<string, unknown>);
+    }
+  });
+
+  const content = typeof children === 'function' ? children(form) : children;
+
+  return (
+    <GcsaFormSchemaContext.Provider value={schema ?? null}>
+      <form
+        className="gcsa-form"
+        onSubmit={event => {
+          event.preventDefault();
+          form.handleSubmit();
+        }}
+      >
+        {content}
+        {showActions ? (
+          <div className="gcsa-form__actions">
+            <GcsaButton type="submit" loading={form.state.isSubmitting} disabled={form.state.isSubmitting}>
+              {resolvedSubmitLabel}
+            </GcsaButton>
+            <GcsaButton
+              variant="secondary"
+              type="button"
+              disabled={form.state.isSubmitting}
+              onClick={() => form.reset()}
+            >
+              {resolvedResetLabel}
+            </GcsaButton>
+          </div>
+        ) : null}
+      </form>
+    </GcsaFormSchemaContext.Provider>
+  );
+}

package/src/GcsaFormField.tsx

@@ -0,0 +1,67 @@
+import type { ReactNode } from 'react';
+import { useContext, useMemo } from 'react';
+import { GcsaField } from './GcsaField';
+import { GcsaFormSchemaContext } from './hooks/useGcsaFormSchema';
+import type { GcsaFormApi } from './hooks/gcsaFormTypes';
+import {
+  gcsaBooleanFieldBindings,
+  gcsaFieldError,
+  gcsaFieldInvalid,
+  gcsaTextFieldBindings,
+  type GcsaAnyFieldApi
+} from './hooks/useGcsaFormField';
+import { zodFieldValidators } from './utils/zodValidators';
+import { useGcsaLocale } from './hooks/useGcsaLocale';
+
+export type GcsaFormFieldProps = {
+  form: GcsaFormApi;
+  name: string;
+  label?: string;
+  hint?: string;
+  required?: boolean;
+  fieldType?: 'text' | 'boolean';
+  children: (props: {
+    field: GcsaAnyFieldApi;
+    bindings: ReturnType<typeof gcsaTextFieldBindings> | ReturnType<typeof gcsaBooleanFieldBindings>;
+  }) => ReactNode;
+};
+
+export function GcsaFormField({
+  form,
+  name,
+  label,
+  hint,
+  required = false,
+  fieldType = 'text',
+  children
+}: GcsaFormFieldProps) {
+  const schema = useContext(GcsaFormSchemaContext);
+  const locale = useGcsaLocale();
+
+  const validators = useMemo(() => {
+    if (!schema) return undefined;
+    return zodFieldValidators(schema, name, locale);
+  }, [schema, name, locale]);
+
+  const Field = form.Field;
+
+  return (
+    <Field name={name} validators={validators}>
+      {(field: GcsaAnyFieldApi) => (
+        <GcsaField
+          label={label}
+          hint={hint}
+          error={gcsaFieldError(field)}
+          invalid={gcsaFieldInvalid(field)}
+          required={required}
+        >
+          {children({
+            field,
+            bindings:
+              fieldType === 'boolean' ? gcsaBooleanFieldBindings(field) : gcsaTextFieldBindings(field)
+          })}
+        </GcsaField>
+      )}
+    </Field>
+  );
+}

package/src/GcsaIcon.tsx

@@ -0,0 +1,21 @@
+import type { GcsaIconName } from './icons';
+import { getGcsaIconSvg } from './icons';
+
+export type GcsaIconProps = {
+  name: GcsaIconName;
+  size?: 'sm' | 'md';
+  className?: string;
+};
+
+export function GcsaIcon({ name, size = 'md', className }: GcsaIconProps) {
+  const sizeClass = size === 'sm' ? 'gcsa-icon--sm' : undefined;
+  const classes = ['gcsa-icon', 'gcsa-nav-icon', sizeClass, className].filter(Boolean).join(' ');
+
+  return (
+    <span
+      className={classes}
+      aria-hidden="true"
+      dangerouslySetInnerHTML={{ __html: getGcsaIconSvg(name) }}
+    />
+  );
+}

package/src/GcsaImagePreview.tsx

@@ -0,0 +1,30 @@
+import { Dialog } from '@ark-ui/react/dialog';
+import { GcsaIcon } from './GcsaIcon';
+import { useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+
+export type GcsaImagePreviewProps = {
+  open: boolean;
+  src: string;
+  alt?: string;
+  onOpenChange?: (open: boolean) => void;
+  onError?: () => void;
+};
+
+export function GcsaImagePreview({ open, src, alt, onOpenChange, onError }: GcsaImagePreviewProps) {
+  const messages = useGcsaLocaleMessages();
+  const resolvedAlt = alt ?? messages.imagePreview;
+
+  return (
+    <Dialog.Root open={open} lazyMount unmountOnExit onOpenChange={details => onOpenChange?.(details.open)}>
+      <Dialog.Backdrop className="gcsa-image-preview__backdrop" />
+      <Dialog.Positioner className="gcsa-image-preview__positioner">
+        <Dialog.Content className="gcsa-image-preview__content" aria-label={messages.imagePreview}>
+          <Dialog.CloseTrigger className="gcsa-image-preview__close" aria-label={messages.imagePreviewClose}>
+            <GcsaIcon name="close" size="sm" />
+          </Dialog.CloseTrigger>
+          <img className="gcsa-image-preview__image" src={src} alt={resolvedAlt} draggable={false} onError={onError} />
+        </Dialog.Content>
+      </Dialog.Positioner>
+    </Dialog.Root>
+  );
+}

package/src/GcsaInput.tsx

@@ -0,0 +1,87 @@
+import { useId, useLayoutEffect, useRef } from 'react';
+import type { InputHTMLAttributes } from 'react';
+import type { GcsaComponentSize } from '@gcsa/console-core';
+import { gcsaControlSizeClass } from '@gcsa/console-core';
+import { useGcsaTextCount, type GcsaTextCountFormatter } from './hooks/useGcsaTextCount';
+import { useGcsaComponentSize } from './hooks/useGcsaComponentSize';
+import { patchFocusPreventScroll } from './hooks/usePreventHiddenInputScroll';
+
+export type GcsaInputProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'value' | 'onChange' | 'onBlur'
+> & {
+  value?: string;
+  size?: GcsaComponentSize;
+  invalid?: boolean;
+  showCount?: boolean;
+  countFormatter?: GcsaTextCountFormatter;
+  onValueChange?: (value: string) => void;
+  onBlur?: () => void;
+};
+
+export function GcsaInput({
+  value = '',
+  type = 'text',
+  placeholder = '',
+  disabled = false,
+  invalid = false,
+  maxLength,
+  showCount,
+  countFormatter,
+  size,
+  className,
+  onValueChange,
+  onBlur,
+  ...rest
+}: GcsaInputProps) {
+  const resolvedSize = useGcsaComponentSize(size);
+  const countId = useId();
+  const inputRef = useRef<HTMLInputElement>(null);
+  useLayoutEffect(() => {
+    if (inputRef.current) patchFocusPreventScroll(inputRef.current);
+  });
+  const { showCounter, countText, isNearLimit } = useGcsaTextCount({
+    modelValue: value,
+    maxLength,
+    showCount,
+    formatter: countFormatter
+  });
+
+  return (
+    <div
+      className={[
+        'gcsa-text-control',
+        'gcsa-text-control--input',
+        gcsaControlSizeClass('gcsa-text-control', resolvedSize),
+        showCounter ? 'gcsa-text-control--count' : null,
+        className
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      <input
+        ref={inputRef}
+        className="gcsa-input"
+        value={value}
+        type={type}
+        placeholder={placeholder}
+        disabled={disabled}
+        maxLength={maxLength}
+        data-invalid={invalid || undefined}
+        aria-describedby={showCounter ? countId : undefined}
+        onChange={event => onValueChange?.(event.target.value)}
+        onBlur={() => onBlur?.()}
+        {...rest}
+      />
+      {showCounter ? (
+        <span
+          id={countId}
+          className={`gcsa-text-control__count${isNearLimit ? ' gcsa-text-control__count--near' : ''}`}
+          aria-live="polite"
+        >
+          {countText}
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/src/GcsaInputGroup.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+import type { GcsaComponentSize } from '@gcsa/console-core';
+import { useGcsaComponentSize } from './hooks/useGcsaComponentSize';
+
+export type GcsaInputGroupProps = {
+  disabled?: boolean;
+  invalid?: boolean;
+  size?: GcsaComponentSize;
+  className?: string;
+  addon?: ReactNode;
+  children?: ReactNode;
+};
+
+export function GcsaInputGroup({
+  disabled = false,
+  invalid = false,
+  size,
+  className,
+  addon,
+  children
+}: GcsaInputGroupProps) {
+  const resolvedSize = useGcsaComponentSize(size);
+  return (
+    <div
+      className={`gcsa-input-group gcsa-input-group--${resolvedSize}${disabled ? ' gcsa-input-group--disabled' : ''}${invalid ? ' gcsa-input-group--invalid' : ''}${className ? ` ${className}` : ''}`}
+      data-invalid={invalid || undefined}
+    >
+      <div className="gcsa-input-group__control">{children}</div>
+      {addon ? <div className="gcsa-input-group__addon">{addon}</div> : null}
+    </div>
+  );
+}

package/src/GcsaInputNumber.tsx

@@ -0,0 +1,155 @@
+import { useMemo } from 'react';
+import type { GcsaComponentSize, GcsaInputNumberControls } from '@gcsa/console-core';
+import { gcsaControlSizeClass } from '@gcsa/console-core';
+import { useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+import { useGcsaComponentSize } from './hooks/useGcsaComponentSize';
+
+export type GcsaInputNumberProps = {
+  value?: number | null;
+  min?: number;
+  max?: number;
+  step?: number;
+  precision?: number;
+  placeholder?: string;
+  disabled?: boolean;
+  invalid?: boolean;
+  size?: GcsaComponentSize;
+  /** both: 左右加减；right: 输入框在左、加减在右；none: 隐藏加减 */
+  controls?: GcsaInputNumberControls;
+  className?: string;
+  onBlur?: () => void;
+  onValueChange?: (value: number | null) => void;
+};
+
+export function GcsaInputNumber({
+  value,
+  min,
+  max,
+  step = 1,
+  precision = 0,
+  placeholder,
+  disabled,
+  invalid,
+  size,
+  controls = 'both',
+  className,
+  onBlur,
+  onValueChange
+}: GcsaInputNumberProps) {
+  const resolvedSize = useGcsaComponentSize(size);
+  const messages = useGcsaLocaleMessages();
+  const displayValue = value == null || Number.isNaN(value) ? '' : String(value);
+
+  const isAtMin = useMemo(
+    () => value != null && min != null && value <= min,
+    [value, min]
+  );
+  const isAtMax = useMemo(
+    () => value != null && max != null && value >= max,
+    [value, max]
+  );
+
+  function clamp(next: number): number {
+    let result = next;
+    if (precision != null) {
+      const factor = 10 ** precision;
+      result = Math.round(result * factor) / factor;
+    }
+    if (min != null) result = Math.max(min, result);
+    if (max != null) result = Math.min(max, result);
+    return result;
+  }
+
+  function parseInput(raw: string): number | null {
+    const trimmed = raw.trim();
+    if (!trimmed) return null;
+    const num = Number(trimmed);
+    if (Number.isNaN(num)) return value ?? null;
+    return clamp(num);
+  }
+
+  function stepUp() {
+    const base = value ?? min ?? 0;
+    onValueChange?.(clamp(base + step));
+  }
+
+  function stepDown() {
+    const base = value ?? max ?? 0;
+    onValueChange?.(clamp(base - step));
+  }
+
+  const rootClassName = [
+    'gcsa-input-number',
+    gcsaControlSizeClass('gcsa-input-number', resolvedSize),
+    disabled ? 'gcsa-input-number--disabled' : undefined,
+    `gcsa-input-number--controls-${controls}`,
+    className
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const inputProps = {
+    className:
+      controls === 'none'
+        ? 'gcsa-input-number__input gcsa-input gcsa-input-number__input--plain'
+        : 'gcsa-input-number__input gcsa-input',
+    type: 'text' as const,
+    inputMode: 'decimal' as const,
+    value: displayValue,
+    placeholder,
+    disabled,
+    'data-invalid': invalid || undefined,
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) =>
+      onValueChange?.(parseInput(event.target.value)),
+    onBlur: (event: React.FocusEvent<HTMLInputElement>) => {
+      onBlur?.();
+      void event;
+    }
+  };
+
+  const decreaseButton = (
+    <button
+      type="button"
+      className="gcsa-input-number__btn"
+      disabled={disabled || isAtMin}
+      aria-label={messages.inputNumberDecrease}
+      onClick={stepDown}
+    >
+      −
+    </button>
+  );
+
+  const increaseButton = (
+    <button
+      type="button"
+      className="gcsa-input-number__btn"
+      disabled={disabled || isAtMax}
+      aria-label={messages.inputNumberIncrease}
+      onClick={stepUp}
+    >
+      +
+    </button>
+  );
+
+  return (
+    <div className={rootClassName}>
+      {controls === 'both' ? (
+        <>
+          {decreaseButton}
+          <input {...inputProps} />
+          {increaseButton}
+        </>
+      ) : null}
+      {controls === 'right' ? (
+        <>
+          <input {...inputProps} />
+          <div className="gcsa-input-number__controls">
+            {decreaseButton}
+            {increaseButton}
+          </div>
+        </>
+      ) : null}
+      {controls === 'none' ? <input {...inputProps} /> : null}
+    </div>
+  );
+}

package/src/GcsaLoading.ts

@@ -0,0 +1,206 @@
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { GcsaLoadingMask } from './GcsaLoadingMask';
+
+export type GcsaLoadingOptions = {
+  target?: HTMLElement | string;
+  body?: boolean;
+  fullscreen?: boolean;
+  lock?: boolean;
+  text?: string;
+  background?: string;
+  customClass?: string;
+  visible?: boolean;
+  closed?: () => void;
+};
+
+export type GcsaLoadingInstance = {
+  readonly visible: boolean;
+  readonly text: string;
+  readonly $el: HTMLElement;
+  setText: (text: string) => void;
+  close: () => void;
+};
+
+type ServiceState = {
+  visible: boolean;
+  text: string;
+  background?: string;
+  customClass?: string;
+  fullscreen: boolean;
+};
+
+let fullscreenInstance: GcsaLoadingInstance | undefined;
+
+function readOverlayLoadingZIndex(): number {
+  if (typeof document === 'undefined') return 3200;
+  const candidates = [
+    getComputedStyle(document.documentElement).getPropertyValue('--gcsa-z-loading').trim(),
+    getComputedStyle(document.documentElement).getPropertyValue('--z-overlay-loading').trim(),
+    getComputedStyle(document.documentElement).getPropertyValue('--gcsa-z-toast').trim()
+  ];
+  for (const value of candidates) {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isFinite(parsed)) {
+      return value === candidates[2] ? parsed + 200 : parsed;
+    }
+  }
+  return 3200;
+}
+
+function resolveTarget(options: GcsaLoadingOptions) {
+  let target: HTMLElement;
+  if (typeof options.target === 'string') {
+    target = (document.querySelector(options.target) as HTMLElement) || document.body;
+  } else {
+    target = options.target || document.body;
+  }
+
+  const fullscreen = target === document.body && (options.fullscreen ?? true);
+  const parent = target === document.body || options.body ? document.body : target;
+
+  return { target, parent, fullscreen };
+}
+
+function addParentClass(parent: HTMLElement, lock: boolean, fullscreen: boolean) {
+  parent.classList.add('gcsa-loading-parent--relative');
+  if (lock || !fullscreen) {
+    parent.classList.add('gcsa-loading-parent--hidden');
+  }
+
+  const count = Number.parseInt(parent.getAttribute('data-gcsa-loading-number') || '0', 10) + 1;
+  parent.setAttribute('data-gcsa-loading-number', String(count));
+}
+
+function removeParentClass(parent: HTMLElement) {
+  const count = Number.parseInt(parent.getAttribute('data-gcsa-loading-number') || '1', 10) - 1;
+  if (count <= 0) {
+    parent.removeAttribute('data-gcsa-loading-number');
+    parent.classList.remove('gcsa-loading-parent--relative');
+    parent.classList.remove('gcsa-loading-parent--hidden');
+  } else {
+    parent.setAttribute('data-gcsa-loading-number', String(count));
+  }
+}
+
+function positionMask(
+  hostEl: HTMLElement,
+  options: { fullscreen?: boolean },
+  parent: HTMLElement,
+  target: HTMLElement
+) {
+  if (options.fullscreen) {
+    hostEl.style.position = 'fixed';
+    hostEl.style.inset = '0';
+    hostEl.style.zIndex = String(readOverlayLoadingZIndex());
+    return;
+  }
+
+  if (parent === document.body && target !== document.body) {
+    const rect = target.getBoundingClientRect();
+    const scrollTop = document.documentElement.scrollTop || document.body.scrollTop;
+    const scrollLeft = document.documentElement.scrollLeft || document.body.scrollLeft;
+    hostEl.style.position = 'absolute';
+    hostEl.style.top = `${rect.top + scrollTop}px`;
+    hostEl.style.left = `${rect.left + scrollLeft}px`;
+    hostEl.style.width = `${rect.width}px`;
+    hostEl.style.height = `${rect.height}px`;
+    hostEl.style.zIndex = String(readOverlayLoadingZIndex());
+    return;
+  }
+
+  hostEl.style.position = 'absolute';
+  hostEl.style.inset = '0';
+  hostEl.style.zIndex = String(readOverlayLoadingZIndex());
+}
+
+function LoadingService(options: GcsaLoadingOptions = {}): GcsaLoadingInstance | undefined {
+  if (typeof window === 'undefined') return undefined;
+
+  const { target, parent, fullscreen } = resolveTarget(options);
+  const lock = options.lock ?? false;
+
+  if (fullscreen && fullscreenInstance) {
+    return fullscreenInstance;
+  }
+
+  const mountNode = document.createElement('div');
+  mountNode.classList.add('gcsa-loading-host');
+  if (fullscreen) {
+    mountNode.classList.add('gcsa-loading-host--fullscreen');
+  }
+
+  const root = createRoot(mountNode);
+  const state: ServiceState = {
+    visible: false,
+    text: options.text || '',
+    background: options.background,
+    customClass: options.customClass,
+    fullscreen
+  };
+
+  const paint = () => {
+    root.render(
+      createElement(GcsaLoadingMask, {
+        text: state.text,
+        background: state.background,
+        customClass: state.customClass,
+        fullscreen: state.fullscreen,
+        visible: state.visible
+      })
+    );
+  };
+
+  paint();
+
+  const instance: GcsaLoadingInstance = {
+    get visible() {
+      return state.visible;
+    },
+    get text() {
+      return state.text;
+    },
+    get $el() {
+      return mountNode;
+    },
+    setText(value: string) {
+      state.text = value;
+      paint();
+    },
+    close() {
+      state.visible = false;
+      paint();
+      window.setTimeout(() => {
+        root.unmount();
+        mountNode.remove();
+        removeParentClass(parent);
+        if (fullscreen) {
+          fullscreenInstance = undefined;
+        }
+        options.closed?.();
+      }, 260);
+    }
+  };
+
+  addParentClass(parent, lock, fullscreen);
+  parent.appendChild(mountNode);
+  positionMask(mountNode, { fullscreen }, parent, target);
+
+  window.requestAnimationFrame(() => {
+    state.visible = true;
+    paint();
+  });
+
+  if (fullscreen) {
+    fullscreenInstance = instance;
+  }
+
+  return instance;
+}
+
+/** Imperative loading API（对齐 Element Plus / panel-web `Loading.service`） */
+export const GcsaLoading = {
+  service: LoadingService
+};
+
+export default LoadingService;