@gcsa/console-react 0.1.0

package/src/GcsaDateTimePicker.tsx

@@ -0,0 +1,407 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { DatePicker, parseDate, type DateValue } from '@ark-ui/react/date-picker';
+import { Portal } from '@ark-ui/react/portal';
+import {
+  createGcsaPopupPositioning,
+  gcsaTimePickerScrollIndex,
+  gcsaTimePickerScrollTop,
+  getGcsaLocaleMessages,
+  getGcsaStartOfWeek,
+  type GcsaConsoleLocale
+} from '@gcsa/console-core';
+import { useGcsaLocale } from './hooks/useGcsaLocale';
+import {
+  gcsaDatePickerFormat,
+  gcsaDatePickerParse,
+  gcsaDateValueToOutputString,
+  gcsaJoinDateTime,
+  gcsaNormalizeDateBoundary,
+  gcsaSplitDateTime,
+  gcsaStringToDateValues
+} from './utils/gcsaDateValue';
+
+export type GcsaDateTimePickerProps = {
+  value?: string;
+  placeholder?: string;
+  locale?: GcsaConsoleLocale;
+  disabled?: boolean;
+  invalid?: boolean;
+  min?: string;
+  max?: string;
+  className?: string;
+  onValueChange?: (value: string) => void;
+};
+
+const HOURS = Array.from({ length: 24 }, (_, index) => String(index).padStart(2, '0'));
+const MINUTES = Array.from({ length: 60 }, (_, index) => String(index).padStart(2, '0'));
+const SECONDS = Array.from({ length: 60 }, (_, index) => String(index).padStart(2, '0'));
+
+function formatMonthTitle(value: DateValue) {
+  return `${value.year} - ${String(value.month).padStart(2, '0')}`;
+}
+
+export function GcsaDateTimePicker({
+  value,
+  placeholder,
+  locale: localeProp,
+  disabled,
+  invalid,
+  min,
+  max,
+  className,
+  onValueChange
+}: GcsaDateTimePickerProps) {
+  const configLocale = useGcsaLocale();
+  const resolvedLocale = localeProp ?? configLocale;
+  const messages = getGcsaLocaleMessages(resolvedLocale).datePicker;
+  const globalMessages = getGcsaLocaleMessages(resolvedLocale);
+  const startOfWeek = getGcsaStartOfWeek(resolvedLocale);
+  const resolvedPlaceholder = placeholder ?? messages.placeholderDateTime;
+
+  const [open, setOpen] = useState(false);
+  const [draftDate, setDraftDate] = useState('');
+  const [draftHour, setDraftHour] = useState('00');
+  const [draftMinute, setDraftMinute] = useState('00');
+  const [draftSecond, setDraftSecond] = useState('00');
+
+  const hourColumn = useRef<HTMLDivElement>(null);
+  const minuteColumn = useRef<HTMLDivElement>(null);
+  const secondColumn = useRef<HTMLDivElement>(null);
+  const timers = useRef<{
+    hour?: ReturnType<typeof setTimeout>;
+    minute?: ReturnType<typeof setTimeout>;
+    second?: ReturnType<typeof setTimeout>;
+  }>({});
+
+  const draftTimeValue = () => `${draftHour}:${draftMinute}:${draftSecond}`;
+
+  const applyTimeParts = useCallback((time: string) => {
+    const [hour = '00', minute = '00', second = '00'] = time.split(':');
+    setDraftHour(hour.padStart(2, '0'));
+    setDraftMinute(minute.padStart(2, '0'));
+    setDraftSecond(second.padStart(2, '0').slice(0, 2));
+  }, []);
+
+  const syncDraftFromValue = useCallback(
+    (nextValue = value) => {
+      const { date, time } = gcsaSplitDateTime(nextValue);
+      setDraftDate(date);
+      applyTimeParts(time);
+    },
+    [applyTimeParts, value]
+  );
+
+  const scrollColumns = useCallback(() => {
+    requestAnimationFrame(() => {
+      if (hourColumn.current) {
+        hourColumn.current.scrollTop = gcsaTimePickerScrollTop(HOURS.indexOf(draftHour));
+      }
+      if (minuteColumn.current) {
+        minuteColumn.current.scrollTop = gcsaTimePickerScrollTop(MINUTES.indexOf(draftMinute));
+      }
+      if (secondColumn.current) {
+        secondColumn.current.scrollTop = gcsaTimePickerScrollTop(SECONDS.indexOf(draftSecond));
+      }
+    });
+  }, [draftHour, draftMinute, draftSecond]);
+
+  useEffect(() => {
+    if (!open) syncDraftFromValue();
+  }, [open, syncDraftFromValue]);
+
+  const pickerValue = useMemo(() => gcsaStringToDateValues(draftDate, 'date'), [draftDate]);
+  const minDateValue = useMemo(() => {
+    const normalized = gcsaNormalizeDateBoundary(gcsaSplitDateTime(min).date, 'date');
+    return normalized ? parseDate(normalized) : undefined;
+  }, [min]);
+  const maxDateValue = useMemo(() => {
+    const normalized = gcsaNormalizeDateBoundary(gcsaSplitDateTime(max).date, 'date');
+    return normalized ? parseDate(normalized) : undefined;
+  }, [max]);
+
+  const formatValue = useCallback(
+    (date: DateValue, details: { locale: string; timeZone: string }) => {
+      const datePart = gcsaDatePickerFormat(date, details, 'date');
+      if (!datePart) return value ?? '';
+      return gcsaJoinDateTime(datePart, draftTimeValue());
+    },
+    [draftHour, draftMinute, draftSecond, value]
+  );
+
+  const parseValue = useCallback(
+    (input: string, details: { locale: string; timeZone: string }) => {
+      const { date, time } = gcsaSplitDateTime(input);
+      if (time) applyTimeParts(time);
+      return gcsaDatePickerParse(date, details, 'date');
+    },
+    [applyTimeParts]
+  );
+
+  const onOpenChange = (details: { open: boolean }) => {
+    if (disabled) return;
+    setOpen(details.open);
+    if (details.open) {
+      syncDraftFromValue();
+      scrollColumns();
+    }
+  };
+
+  const selectHour = (hour: string) => {
+    setDraftHour(hour);
+    scrollColumns();
+  };
+
+  const selectMinute = (minute: string) => {
+    setDraftMinute(minute);
+    scrollColumns();
+  };
+
+  const selectSecond = (second: string) => {
+    setDraftSecond(second);
+    scrollColumns();
+  };
+
+  const onColumnScroll = (type: 'hour' | 'minute' | 'second', element: HTMLDivElement) => {
+    clearTimeout(timers.current[type]);
+    timers.current[type] = setTimeout(() => {
+      const values = type === 'hour' ? HOURS : type === 'minute' ? MINUTES : SECONDS;
+      const index = gcsaTimePickerScrollIndex(element.scrollTop, values.length);
+      const nextValue = values[index];
+      if (type === 'hour' && nextValue) selectHour(nextValue);
+      if (type === 'minute' && nextValue) selectMinute(nextValue);
+      if (type === 'second' && nextValue) selectSecond(nextValue);
+    }, 80);
+  };
+
+  const selectNow = () => {
+    const now = new Date();
+    setDraftDate(
+      `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+    );
+    setDraftHour(String(now.getHours()).padStart(2, '0'));
+    setDraftMinute(String(now.getMinutes()).padStart(2, '0'));
+    setDraftSecond(String(now.getSeconds()).padStart(2, '0'));
+    scrollColumns();
+  };
+
+  const confirm = () => {
+    if (!draftDate) return;
+    onValueChange?.(gcsaJoinDateTime(draftDate, draftTimeValue()));
+    setOpen(false);
+  };
+
+  return (
+    <DatePicker.Root
+      open={open}
+      value={pickerValue}
+      locale={resolvedLocale}
+      startOfWeek={startOfWeek}
+      positioning={createGcsaPopupPositioning({ fitViewport: true })}
+      closeOnSelect={false}
+      disabled={disabled}
+      invalid={invalid}
+      min={minDateValue}
+      max={maxDateValue}
+      format={formatValue}
+      parse={parseValue}
+      className={className}
+      onOpenChange={onOpenChange}
+      onValueChange={details => {
+        setDraftDate(gcsaDateValueToOutputString(details.value?.[0], 'date'));
+      }}
+    >
+      <DatePicker.Control className="gcsa-date-picker__control" data-invalid={invalid || undefined}>
+        <DatePicker.Input
+          className="gcsa-date-picker__input gcsa-input"
+          placeholder={resolvedPlaceholder}
+          readOnly
+        />
+        <DatePicker.Trigger
+          className="gcsa-date-picker__trigger gcsa-focus-ring"
+          aria-label={messages.openCalendar}
+        >
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+            <rect x="2" y="3" width="12" height="11" rx="1.5" stroke="currentColor" strokeWidth="1.2" />
+            <path
+              d="M2 6.5h12M5.5 1.5v2M10.5 1.5v2"
+              stroke="currentColor"
+              strokeWidth="1.2"
+              strokeLinecap="round"
+            />
+          </svg>
+        </DatePicker.Trigger>
+      </DatePicker.Control>
+      <Portal>
+        <DatePicker.Positioner className="gcsa-date-picker__positioner">
+          <DatePicker.Content className="gcsa-date-picker__content gcsa-datetime-picker__content gcsa-ui-surface">
+            <div className="gcsa-datetime-picker__body">
+              <div className="gcsa-datetime-picker__calendar">
+                <DatePicker.View view="day">
+                  <DatePicker.Context>
+                    {dp => (
+                      <>
+                        <div className="gcsa-datetime-picker__header">
+                          <button
+                            type="button"
+                            className="gcsa-datetime-picker__nav gcsa-focus-ring"
+                            aria-label={messages.prevYear}
+                            onMouseDown={event => event.preventDefault()}
+                            onClick={() => dp.focusYear(dp.focusedValue.year - 1)}
+                          >
+                            «
+                          </button>
+                          <DatePicker.PrevTrigger
+                            className="gcsa-datetime-picker__nav gcsa-focus-ring"
+                            aria-label={messages.prevMonth}
+                          >
+                            ‹
+                          </DatePicker.PrevTrigger>
+                          <div className="gcsa-datetime-picker__title">
+                            {formatMonthTitle(dp.focusedValue)}
+                          </div>
+                          <DatePicker.NextTrigger
+                            className="gcsa-datetime-picker__nav gcsa-focus-ring"
+                            aria-label={messages.nextMonth}
+                          >
+                            ›
+                          </DatePicker.NextTrigger>
+                          <button
+                            type="button"
+                            className="gcsa-datetime-picker__nav gcsa-focus-ring"
+                            aria-label={messages.nextYear}
+                            onMouseDown={event => event.preventDefault()}
+                            onClick={() => dp.focusYear(dp.focusedValue.year + 1)}
+                          >
+                            »
+                          </button>
+                        </div>
+                        <DatePicker.Table className="gcsa-date-picker__table">
+                          <DatePicker.TableHead>
+                            <DatePicker.TableRow>
+                              {dp.weekDays.map((weekDay, weekDayIndex) => (
+                                <DatePicker.TableHeader
+                                  key={weekDay.short ?? weekDayIndex}
+                                  className="gcsa-date-picker__weekday"
+                                >
+                                  {weekDay.short}
+                                </DatePicker.TableHeader>
+                              ))}
+                            </DatePicker.TableRow>
+                          </DatePicker.TableHead>
+                          <DatePicker.TableBody>
+                            {dp.weeks.map((week, weekIndex) => (
+                              <DatePicker.TableRow key={weekIndex}>
+                                {week.map(day => (
+                                  <DatePicker.TableCell
+                                    key={day.toString()}
+                                    value={day}
+                                    className="gcsa-date-picker__cell"
+                                  >
+                                    <DatePicker.TableCellTrigger className="gcsa-date-picker__day gcsa-focus-ring">
+                                      {day.day}
+                                    </DatePicker.TableCellTrigger>
+                                  </DatePicker.TableCell>
+                                ))}
+                              </DatePicker.TableRow>
+                            ))}
+                          </DatePicker.TableBody>
+                        </DatePicker.Table>
+                      </>
+                    )}
+                  </DatePicker.Context>
+                </DatePicker.View>
+              </div>
+              <div className="gcsa-datetime-picker__time">
+                <div className="gcsa-datetime-picker__time-title">{messages.selectTime}</div>
+                <div className="gcsa-time-picker__spinner gcsa-datetime-picker__spinner">
+                  <div
+                    ref={hourColumn}
+                    className="gcsa-time-picker__column"
+                    role="listbox"
+                    aria-label={globalMessages.timeHour}
+                    onScroll={event => onColumnScroll('hour', event.currentTarget)}
+                  >
+                    {HOURS.map(hour => (
+                      <button
+                        key={hour}
+                        type="button"
+                        className={`gcsa-time-picker__cell${hour === draftHour ? ' gcsa-time-picker__cell--selected' : ''}`}
+                        role="option"
+                        aria-selected={hour === draftHour}
+                        onMouseDown={event => event.preventDefault()}
+                        onClick={() => selectHour(hour)}
+                      >
+                        {hour}
+                      </button>
+                    ))}
+                  </div>
+                  <div
+                    ref={minuteColumn}
+                    className="gcsa-time-picker__column"
+                    role="listbox"
+                    aria-label={globalMessages.timeMinute}
+                    onScroll={event => onColumnScroll('minute', event.currentTarget)}
+                  >
+                    {MINUTES.map(minute => (
+                      <button
+                        key={minute}
+                        type="button"
+                        className={`gcsa-time-picker__cell${minute === draftMinute ? ' gcsa-time-picker__cell--selected' : ''}`}
+                        role="option"
+                        aria-selected={minute === draftMinute}
+                        onMouseDown={event => event.preventDefault()}
+                        onClick={() => selectMinute(minute)}
+                      >
+                        {minute}
+                      </button>
+                    ))}
+                  </div>
+                  <div
+                    ref={secondColumn}
+                    className="gcsa-time-picker__column"
+                    role="listbox"
+                    aria-label={globalMessages.timeSecond}
+                    onScroll={event => onColumnScroll('second', event.currentTarget)}
+                  >
+                    {SECONDS.map(second => (
+                      <button
+                        key={second}
+                        type="button"
+                        className={`gcsa-time-picker__cell${second === draftSecond ? ' gcsa-time-picker__cell--selected' : ''}`}
+                        role="option"
+                        aria-selected={second === draftSecond}
+                        onMouseDown={event => event.preventDefault()}
+                        onClick={() => selectSecond(second)}
+                      >
+                        {second}
+                      </button>
+                    ))}
+                  </div>
+                  <div className="gcsa-time-picker__selection" aria-hidden="true" />
+                </div>
+              </div>
+            </div>
+            <div className="gcsa-datetime-picker__footer">
+              <button
+                type="button"
+                className="gcsa-datetime-picker__now"
+                onMouseDown={event => event.preventDefault()}
+                onClick={selectNow}
+              >
+                {messages.now}
+              </button>
+              <button
+                type="button"
+                className="gcsa-datetime-picker__confirm"
+                onMouseDown={event => event.preventDefault()}
+                onClick={confirm}
+              >
+                {globalMessages.confirm}
+              </button>
+            </div>
+          </DatePicker.Content>
+        </DatePicker.Positioner>
+      </Portal>
+    </DatePicker.Root>
+  );
+}

package/src/GcsaDescriptions.tsx

@@ -0,0 +1,22 @@
+export type GcsaDescriptionsItem = {
+  label: string;
+  value: string;
+};
+
+export type GcsaDescriptionsProps = {
+  items: GcsaDescriptionsItem[];
+  className?: string;
+};
+
+export function GcsaDescriptions({ items, className }: GcsaDescriptionsProps) {
+  return (
+    <div className={`gcsa-descriptions gcsa-ui-surface${className ? ` ${className}` : ''}`}>
+      {items.map(item => (
+        <div key={item.label} className="gcsa-descriptions__row">
+          <div className="gcsa-descriptions__label">{item.label}</div>
+          <div className="gcsa-descriptions__value">{item.value}</div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/GcsaDivider.tsx

@@ -0,0 +1,7 @@
+export type GcsaDividerProps = {
+  className?: string;
+};
+
+export function GcsaDivider({ className }: GcsaDividerProps) {
+  return <hr className={`gcsa-divider${className ? ` ${className}` : ''}`} />;
+}

package/src/GcsaDrawer.tsx

@@ -0,0 +1,87 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import type { GcsaDrawerPlacement } from '@gcsa/console-core';
+import { Dialog } from '@ark-ui/react/dialog';
+import { Portal } from '@ark-ui/react/portal';
+import { useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+import { useGcsaOverlayZIndex } from './hooks/useOverlayZIndex';
+import { usePreserveScrollOnFocus } from './hooks/usePreventHiddenInputScroll';
+
+export type GcsaDrawerSize = 'default' | 'lg';
+
+export type GcsaDrawerProps = {
+  open: boolean;
+  title?: string;
+  closable?: boolean;
+  placement?: GcsaDrawerPlacement;
+  /** default=720px, lg=960px（复杂表单） */
+  size?: GcsaDrawerSize;
+  footer?: ReactNode;
+  onOpenChange?: (open: boolean) => void;
+  children?: ReactNode;
+};
+
+export function GcsaDrawer({
+  open,
+  title,
+  closable = true,
+  placement = 'right',
+  size = 'default',
+  footer,
+  onOpenChange,
+  children
+}: GcsaDrawerProps) {
+  const messages = useGcsaLocaleMessages();
+  const bodyRef = usePreserveScrollOnFocus(open);
+  const { backdropZ, positionerZ } = useGcsaOverlayZIndex(open);
+  const backdropStyle = (backdropZ == null ? undefined : { zIndex: backdropZ }) as CSSProperties | undefined;
+  const positionerStyle = (positionerZ == null ? undefined : { zIndex: positionerZ }) as CSSProperties | undefined;
+  const sizeClass = size === 'lg' ? ' gcsa-drawer__panel--size-lg' : '';
+
+  return (
+    <Dialog.Root
+      open={open}
+      lazyMount
+      unmountOnExit
+      onOpenChange={details => onOpenChange?.(details.open)}
+    >
+      <Portal>
+        <Dialog.Backdrop className="gcsa-drawer__backdrop" style={backdropStyle} />
+        <Dialog.Positioner
+          className={`gcsa-drawer__positioner gcsa-drawer__positioner--${placement}`}
+          style={positionerStyle}
+        >
+          <Dialog.Content
+            className={`gcsa-drawer__panel gcsa-ui-surface gcsa-drawer__panel--${placement}${sizeClass}`}
+          >
+            {closable ? (
+              <Dialog.CloseTrigger className="gcsa-drawer__close" aria-label={messages.close}>
+                <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+                  <path
+                    d="M2 2l10 10M12 2L2 12"
+                    stroke="currentColor"
+                    strokeWidth="1.5"
+                    strokeLinecap="round"
+                  />
+                </svg>
+              </Dialog.CloseTrigger>
+            ) : null}
+            {title ? (
+              <header className="gcsa-drawer__header">
+                <Dialog.Title asChild>
+                  <div className="gcsa-drawer__title">{title}</div>
+                </Dialog.Title>
+              </header>
+            ) : null}
+            <div
+              ref={bodyRef}
+              className={`gcsa-drawer__body${title ? ' gcsa-drawer__body--titled' : ''}`}
+            >
+              {children}
+            </div>
+            {footer ? <div className="gcsa-drawer__footer">{footer}</div> : null}
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Portal>
+    </Dialog.Root>
+  );
+}

package/src/GcsaDropdown.tsx

@@ -0,0 +1,84 @@
+import type { CSSProperties, ReactNode } from 'react';
+import { Menu } from '@ark-ui/react/menu';
+import { Portal } from '@ark-ui/react/portal';
+import { createGcsaPopupPositioning, type GcsaPopupPlacement } from '@gcsa/console-core';
+import { GcsaButton } from './GcsaButton';
+import { useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+import { useGcsaPopupZIndex } from './hooks/useGcsaPopupZIndex';
+
+export type GcsaDropdownPlacement = GcsaPopupPlacement;
+
+export type GcsaDropdownItem = {
+  key: string;
+  label: string;
+  disabled?: boolean;
+};
+
+export type GcsaDropdownProps = {
+  items: GcsaDropdownItem[];
+  triggerLabel?: string;
+  trigger?: ReactNode;
+  placement?: GcsaDropdownPlacement;
+  /** 挂载到 body，避免表格等 overflow 容器裁切 */
+  portalled?: boolean;
+  gutter?: number;
+  className?: string;
+  onSelect?: (key: string) => void;
+};
+
+export function GcsaDropdown({
+  items,
+  triggerLabel,
+  trigger,
+  placement = 'bottom-start',
+  portalled = true,
+  gutter = 4,
+  className,
+  onSelect
+}: GcsaDropdownProps) {
+  const messages = useGcsaLocaleMessages();
+  const { zIndex, onOpenChange } = useGcsaPopupZIndex();
+  const resolvedTriggerLabel = triggerLabel ?? messages.menu;
+
+  const triggerNode = trigger ?? (
+    <GcsaButton variant="secondary">
+      {resolvedTriggerLabel}
+    </GcsaButton>
+  );
+
+  const positionerStyle = (zIndex == null ? undefined : { zIndex }) as CSSProperties | undefined;
+  const contentStyle = (zIndex == null ? undefined : { zIndex }) as CSSProperties | undefined;
+  const positioning = createGcsaPopupPositioning({ placement, gutter });
+
+  const menuContent = (
+    <Menu.Positioner className="gcsa-dropdown-positioner" style={positionerStyle}>
+      <Menu.Content className="gcsa-dropdown gcsa-ui-surface" style={contentStyle}>
+        {items.map(item => (
+          <Menu.Item
+            key={item.key}
+            value={item.key}
+            disabled={item.disabled}
+            className="gcsa-dropdown__item"
+          >
+            <Menu.ItemText>{item.label}</Menu.ItemText>
+          </Menu.Item>
+        ))}
+      </Menu.Content>
+    </Menu.Positioner>
+  );
+
+  return (
+    <span className={`gcsa-dropdown-anchor${className ? ` ${className}` : ''}`}>
+      <Menu.Root
+        positioning={positioning}
+        onOpenChange={details => onOpenChange(details.open)}
+        onSelect={details => {
+          onSelect?.(details.value);
+        }}
+      >
+        <Menu.Trigger asChild>{triggerNode}</Menu.Trigger>
+        {portalled ? <Portal>{menuContent}</Portal> : menuContent}
+      </Menu.Root>
+    </span>
+  );
+}

package/src/GcsaEmpty.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+import { GcsaIcon } from './GcsaIcon';
+import { useGcsaLocaleMessages } from './hooks/useGcsaLocale';
+
+export type GcsaEmptyProps = {
+  title?: string;
+  description?: string;
+  icon?: ReactNode;
+  action?: ReactNode;
+  className?: string;
+};
+
+export function GcsaEmpty({ title, description, icon, action, className }: GcsaEmptyProps) {
+  const messages = useGcsaLocaleMessages();
+  const resolvedTitle = title ?? messages.emptyDefault;
+
+  return (
+    <div className={`gcsa-empty gcsa-ui-surface${className ? ` ${className}` : ''}`}>
+      <div className="gcsa-empty__icon" aria-hidden="true">
+        {icon ?? <GcsaIcon name="resultEmpty" />}
+      </div>
+      <div className="gcsa-empty__title">{resolvedTitle}</div>
+      {description ? <div className="gcsa-empty__desc">{description}</div> : null}
+      {action ? <div className="gcsa-empty__action">{action}</div> : null}
+    </div>
+  );
+}

package/src/GcsaField.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react';
+import { Field } from '@ark-ui/react/field';
+
+export type GcsaFieldProps = {
+  label?: string;
+  hint?: string;
+  error?: string;
+  invalid?: boolean;
+  required?: boolean;
+  className?: string;
+  children?: ReactNode;
+};
+
+export function GcsaField({
+  label,
+  hint,
+  error,
+  invalid,
+  required,
+  className,
+  children
+}: GcsaFieldProps) {
+  const isInvalid = invalid ?? Boolean(error);
+
+  return (
+    <Field.Root className={`gcsa-field${className ? ` ${className}` : ''}`} invalid={isInvalid}>
+      {label ? (
+        <Field.Label className="gcsa-field__label">
+          {label}
+          {required ? (
+            <span className="gcsa-field__required" aria-hidden="true">
+              *
+            </span>
+          ) : null}
+        </Field.Label>
+      ) : null}
+      {children}
+      {hint && !error ? (
+        <Field.HelperText className="gcsa-field__hint" role="note">
+          {hint}
+        </Field.HelperText>
+      ) : null}
+      {error ? (
+        <Field.ErrorText className="gcsa-field__error" role="alert">
+          {error}
+        </Field.ErrorText>
+      ) : null}
+    </Field.Root>
+  );
+}