@gcsa/console-core 0.1.0

package/src/gcsaPopupPositioning.ts

@@ -0,0 +1,57 @@
+/** Ark UI / Zag Popper 通用方位（与 Floating UI placement 对齐） */
+export type GcsaPopupPlacement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end';
+
+export type GcsaPopupPositioningOptions = {
+  placement?: GcsaPopupPlacement;
+  gutter?: number;
+  strategy?: 'fixed' | 'absolute';
+  sameWidth?: boolean;
+  fitViewport?: boolean;
+  flip?: boolean;
+  slide?: boolean;
+  /** zag 用 overlap 开启横向 shift，避免贴边触发器时面板溢出视口 */
+  overlap?: boolean;
+  overflowPadding?: number;
+};
+
+/**
+ * 统一浮层定位：flip / slide / overlap 默认开启，减少贴边溢出。
+ * 供 Select、Menu、Popover、Tooltip、DatePicker 等复用。
+ */
+export function createGcsaPopupPositioning(options: GcsaPopupPositioningOptions = {}) {
+  const {
+    placement = 'bottom-start',
+    gutter = 8,
+    strategy = 'fixed',
+    sameWidth,
+    fitViewport,
+    flip = true,
+    slide = true,
+    overlap = true,
+    overflowPadding = 8
+  } = options;
+
+  return {
+    placement,
+    gutter,
+    strategy,
+    flip,
+    slide,
+    overlap,
+    overflowPadding,
+    ...(sameWidth === undefined ? {} : { sameWidth }),
+    ...(fitViewport === undefined ? {} : { fitViewport })
+  };
+}

package/src/gcsaPopupStyles.ts

@@ -0,0 +1,137 @@
+/**
+ * 浮层样式契约：与 packages/styles/src/console-ui.css 保持同步。
+ * 测试会校验 CSS 中是否仍包含这些规则，防止 padding / 碰撞变量被改坏。
+ */
+export const GCSA_POPUP_OVERFLOW_PADDING = 8;
+export const GCSA_POPUP_VIEWPORT_CSS_INSET = 16;
+
+export const GCSA_POPUP_STYLE_CONTRACT = {
+  selectContent: {
+    selector: '.gcsa-select-content',
+    maxWidth: 'var(--available-width, 100vw)',
+    minWidth: 'min(160px, var(--reference-width, 160px))'
+  },
+  selectList: {
+    selector: '.gcsa-select-list',
+    padding: '4px'
+  },
+  selectItem: {
+    selector: '.gcsa-select-item',
+    padding: '8px 10px'
+  },
+  tooltip: {
+    selector: '.gcsa-tooltip',
+    padding: '6px 12px',
+    maxWidth: 'min(240px, var(--available-width, calc(100vw - 16px)))'
+  },
+  popover: {
+    selector: '.gcsa-popover',
+    padding: '12px 14px',
+    maxWidth: 'min(320px, var(--available-width, calc(100vw - 16px)))'
+  },
+  dropdown: {
+    selector: '.gcsa-dropdown',
+    maxWidth: 'var(--available-width, calc(100vw - 16px))'
+  },
+  dateTimePicker: {
+    selector: '.gcsa-date-picker__content.gcsa-datetime-picker__content',
+    maxWidth: 'var(--available-width, calc(100vw - 16px))'
+  }
+} as const;
+
+export type GcsaPopupStyleRule = {
+  selector: string;
+  padding?: string;
+  minWidth?: string;
+  maxWidth?: string;
+};
+
+export function stripCssComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+export function extractCssRuleBlocks(css: string, selector: string): string[] {
+  const normalized = stripCssComments(css);
+  const blocks: string[] = [];
+  let depth = 0;
+  let index = 0;
+
+  while (index < normalized.length) {
+    const char = normalized[index];
+
+    if (char === '{') {
+      depth += 1;
+      index += 1;
+      continue;
+    }
+
+    if (char === '}') {
+      depth = Math.max(0, depth - 1);
+      index += 1;
+      continue;
+    }
+
+    if (depth !== 0 || char === '@') {
+      index += 1;
+      continue;
+    }
+
+    const braceStart = normalized.indexOf('{', index);
+    if (braceStart === -1) {
+      break;
+    }
+
+    const selectorPart = normalized.slice(index, braceStart).trim();
+    let ruleDepth = 1;
+    let cursor = braceStart + 1;
+    while (cursor < normalized.length && ruleDepth > 0) {
+      if (normalized[cursor] === '{') {
+        ruleDepth += 1;
+      }
+      if (normalized[cursor] === '}') {
+        ruleDepth -= 1;
+      }
+      cursor += 1;
+    }
+
+    const block = normalized.slice(braceStart + 1, cursor - 1);
+    const selectors = selectorPart.split(',').map((part) => part.trim());
+    if (selectors.includes(selector)) {
+      blocks.push(block);
+    }
+
+    index = cursor;
+  }
+
+  return blocks;
+}
+
+export function extractCssRuleBlock(css: string, selector: string): string | null {
+  const blocks = extractCssRuleBlocks(css, selector);
+  return blocks.length ? blocks.join('\n') : null;
+}
+
+export function cssBlockIncludes(block: string, declaration: string): boolean {
+  return block.replace(/\s+/g, ' ').includes(declaration.replace(/\s+/g, ' '));
+}
+
+export function validatePopupStyleContract(css: string, contract: Record<string, GcsaPopupStyleRule>) {
+  const failures: string[] = [];
+  for (const [name, rule] of Object.entries(contract)) {
+    const block = extractCssRuleBlock(css, rule.selector);
+    if (!block) {
+      failures.push(`${name}: missing selector ${rule.selector}`);
+      continue;
+    }
+    if (rule.padding && !cssBlockIncludes(block, `padding: ${rule.padding}`)) {
+      failures.push(`${name}: expected padding ${rule.padding}`);
+    }
+    if (rule.minWidth && !cssBlockIncludes(block, `min-width: ${rule.minWidth}`)) {
+      failures.push(`${name}: expected min-width ${rule.minWidth}`);
+    }
+    if (rule.maxWidth && !cssBlockIncludes(block, `max-width: ${rule.maxWidth}`)) {
+      failures.push(`${name}: expected max-width ${rule.maxWidth}`);
+    }
+  }
+  return failures;
+}

package/src/gcsaSize.ts

@@ -0,0 +1,29 @@
+import type { GcsaButtonSize } from './index';
+
+/** 表单/控件密度，对齐 Ant Design：small / middle / large */
+export type GcsaComponentSize = 'sm' | 'md' | 'lg';
+
+export const GCSA_DEFAULT_COMPONENT_SIZE: GcsaComponentSize = 'md';
+
+export function resolveGcsaComponentSize(
+  propSize: GcsaComponentSize | undefined,
+  configSize: GcsaComponentSize = GCSA_DEFAULT_COMPONENT_SIZE
+): GcsaComponentSize {
+  return propSize ?? configSize;
+}
+
+export function resolveGcsaButtonSize(
+  propSize: GcsaButtonSize | undefined,
+  configSize: GcsaComponentSize = GCSA_DEFAULT_COMPONENT_SIZE
+): GcsaButtonSize {
+  if (propSize) return propSize;
+  return configSize;
+}
+
+/** e.g. gcsaControlSizeClass('gcsa-text-control', 'md') → 'gcsa-text-control--md' */
+export function gcsaControlSizeClass(
+  prefix: string,
+  size: GcsaComponentSize = GCSA_DEFAULT_COMPONENT_SIZE
+): string {
+  return `${prefix}--${size}`;
+}

package/src/gcsaTableEvents.ts

@@ -0,0 +1,36 @@
+export type GcsaTableSortingEntry = { id: string; desc: boolean };
+
+export type GcsaTableSortOrder = 'ascending' | 'descending' | null;
+
+export type GcsaTableSortChange = {
+  prop: string | null;
+  order: GcsaTableSortOrder;
+};
+
+/** Stable column metadata exposed by legacy-compatible row/cell events. */
+export type GcsaTableColumnInfo = {
+  id: string;
+  prop: string;
+  label: string;
+  width?: string;
+  minWidth?: string;
+  fixed?: 'left' | 'right' | true;
+};
+
+export type GcsaTableHeaderEvent = {
+  column: GcsaTableColumnInfo;
+  event: MouseEvent;
+};
+
+/** Maps the first TanStack sort entry to the payload used by Element tables. */
+export function getGcsaTableSortChange(sorting: GcsaTableSortingEntry[]): GcsaTableSortChange {
+  const primary = sorting[0];
+  if (!primary) return { prop: null, order: null };
+  return { prop: primary.id, order: primary.desc ? 'descending' : 'ascending' };
+}
+
+/** Maps Element-style imperative sorting arguments to TanStack state. */
+export function getGcsaTableSorting(prop: string, order: GcsaTableSortOrder): GcsaTableSortingEntry[] {
+  if (!prop || !order) return [];
+  return [{ id: prop, desc: order === 'descending' }];
+}

package/src/gcsaTableLayout.ts

@@ -0,0 +1,69 @@
+export const GCSA_TABLE_EXPAND_COLUMN_WIDTH = 44;
+export const GCSA_TABLE_SELECTION_COLUMN_WIDTH = 48;
+export const GCSA_TABLE_DEFAULT_COLUMN_MIN_WIDTH = 120;
+export const GCSA_TABLE_MIN_WIDTH_FLOOR = 640;
+
+export type GcsaTableLayoutColumn = {
+  id: string;
+  fixed?: 'left' | 'right' | true;
+  width?: string;
+  minWidth?: string;
+};
+
+export type GcsaTableFixedOffsetOptions = {
+  expandable?: boolean;
+  selectable?: boolean;
+  fixedSelection?: boolean;
+  expandColumnWidth?: number;
+  selectionColumnWidth?: number;
+  columnWidths?: Record<string, number>;
+};
+
+function controlWidth(value: number | undefined, fallback: number) {
+  return Number.isFinite(value) && value! > 0 ? value! : fallback;
+}
+
+function columnWidth(column: GcsaTableLayoutColumn, widths: Record<string, number>) {
+  const override = widths[column.id];
+  if (Number.isFinite(override) && override > 0) return override;
+  const parsed = Number.parseFloat(column.width ?? column.minWidth ?? '');
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export function getGcsaTableMinWidth(
+  columns: GcsaTableLayoutColumn[],
+  options: GcsaTableFixedOffsetOptions & { defaultColumnMinWidth?: number } = {}
+): number {
+  const defaultColumnMinWidth = options.defaultColumnMinWidth ?? GCSA_TABLE_DEFAULT_COLUMN_MIN_WIDTH;
+  const dataWidth = columns.reduce(
+    (sum, column) => sum + (columnWidth(column, options.columnWidths ?? {}) || defaultColumnMinWidth),
+    0
+  );
+  const leadingControls =
+    (options.expandable ? controlWidth(options.expandColumnWidth, GCSA_TABLE_EXPAND_COLUMN_WIDTH) : 0) +
+    (options.selectable ? controlWidth(options.selectionColumnWidth, GCSA_TABLE_SELECTION_COLUMN_WIDTH) : 0);
+
+  return Math.max(GCSA_TABLE_MIN_WIDTH_FLOOR, dataWidth + leadingControls);
+}
+
+export function getGcsaTableFixedOffset(
+  columns: GcsaTableLayoutColumn[],
+  id: string,
+  direction: 'left' | 'right',
+  options: GcsaTableFixedOffsetOptions = {}
+) {
+  const targetIndex = columns.findIndex(column => column.id === id);
+  if (targetIndex < 0) return 0;
+
+  const leadingControlWidth = direction === 'left' && options.selectable && options.fixedSelection
+    ? controlWidth(options.selectionColumnWidth, GCSA_TABLE_SELECTION_COLUMN_WIDTH) +
+      (options.expandable ? controlWidth(options.expandColumnWidth, GCSA_TABLE_EXPAND_COLUMN_WIDTH) : 0)
+    : 0;
+  const candidates = direction === 'left'
+    ? columns.slice(0, targetIndex)
+    : columns.slice(targetIndex + 1);
+
+  return candidates
+    .filter(column => (column.fixed === true ? 'left' : column.fixed) === direction)
+    .reduce((offset, column) => offset + columnWidth(column, options.columnWidths ?? {}), leadingControlWidth);
+}

package/src/gcsaTableMigration.ts

@@ -0,0 +1,104 @@
+import type { GcsaTableColumn, GcsaTableColumnFixed } from './index';
+
+export type GcsaLegacyTableColumn<T> = Omit<Partial<GcsaTableColumn<T>>, 'sortable' | 'width' | 'minWidth' | 'id' | 'formatter' | 'columns'> & {
+  id?: string;
+  prop?: keyof T & string;
+  label?: string;
+  type?: 'selection' | 'index' | 'expand';
+  index?: number | ((index: number) => number | string);
+  selectable?: (row: T, index: number) => boolean;
+  sortable?: boolean | 'custom';
+  width?: string | number;
+  minWidth?: string | number;
+  'min-width'?: string | number;
+  showOverflowTooltip?: boolean;
+  'show-overflow-tooltip'?: boolean;
+  sortMethod?: (a: T, b: T) => number;
+  'sort-method'?: (a: T, b: T) => number;
+  formatter?: (row: T, column: GcsaLegacyTableColumn<T>, value: unknown, index: number) => unknown;
+  children?: GcsaLegacyTableColumn<T>[];
+  fixed?: GcsaTableColumnFixed;
+};
+
+export type GcsaTableMigration<T> = {
+  columns: GcsaTableColumn<T>[];
+  selectable: boolean | ((row: T, index: number) => boolean);
+  expandable: boolean;
+  fixedSelection: boolean;
+  selectionColumnWidth?: number;
+  expandColumnWidth?: number;
+};
+
+export type GcsaTableMigrationOptions = {
+  page?: number;
+  pageSize?: number;
+};
+
+export function normalizeGcsaTableColumns<T extends Record<string, unknown>>(
+  columns: GcsaLegacyTableColumn<T>[],
+  options: GcsaTableMigrationOptions = {}
+): GcsaTableMigration<T> {
+  let selectable: GcsaTableMigration<T>['selectable'] = false;
+  let expandable = false;
+  let fixedSelection = false;
+  let selectionColumnWidth: number | undefined;
+  let expandColumnWidth: number | undefined;
+  const normalized: GcsaTableColumn<T>[] = [];
+  const page = Math.max(1, options.page ?? 1);
+  const pageSize = Math.max(1, options.pageSize ?? 10);
+  const indexOffset = (page - 1) * pageSize;
+
+  columns.forEach((column, index) => {
+    const { formatter: legacyFormatter, children: legacyChildren, ...columnRest } = column;
+    const type = column.type;
+    const width = normalizeColumnWidth(column.width);
+    const minWidth = normalizeColumnWidth(column.minWidth ?? column['min-width']);
+    const showOverflowTooltip = column.showOverflowTooltip ?? column['show-overflow-tooltip'];
+    const sortMethod = column.sortMethod ?? column['sort-method'];
+    if (type === 'selection') {
+      selectable = column.selectable ?? true;
+      fixedSelection ||= Boolean(column.fixed);
+      selectionColumnWidth ??= width ? Number.parseFloat(width) : undefined;
+      return;
+    }
+    if (type === 'expand') {
+      expandable = true;
+      expandColumnWidth ??= width ? Number.parseFloat(width) : undefined;
+      return;
+    }
+    const id = column.id ?? column.prop ?? (type === 'index' ? '__index' : `column-${index}`);
+    const header = column.header ?? column.label ?? (type === 'index' ? '#' : id);
+    const accessorKey = column.accessorKey ?? (column.prop as keyof T & string | undefined);
+    const children = legacyChildren?.length
+      ? normalizeGcsaTableColumns(legacyChildren, options).columns
+      : undefined;
+    normalized.push({
+      ...columnRest,
+      id,
+      header,
+      ...(accessorKey ? { accessorKey } : {}),
+      ...(children ? { columns: children } : {}),
+      sortable: column.sortable === 'custom' ? true : column.sortable,
+      ...(sortMethod ? { sortCompare: sortMethod } : {}),
+      ...(legacyFormatter ? { formatter: (value: unknown, row: T, rowIndex: number) => legacyFormatter(row, column, value, rowIndex) } : {}),
+      width,
+      minWidth,
+      showOverflowTooltip,
+      ...(type === 'index' ? {
+        formatter: (_value: unknown, _row: T, rowIndex: number) => {
+          const absoluteIndex = indexOffset + rowIndex;
+          if (typeof column.index === 'function') return column.index(absoluteIndex);
+          if (typeof column.index === 'number') return column.index + absoluteIndex;
+          return absoluteIndex + 1;
+        }
+      } : {})
+    });
+  });
+
+  return { columns: normalized, selectable, expandable, fixedSelection, selectionColumnWidth, expandColumnWidth };
+}
+
+function normalizeColumnWidth(value: string | number | undefined) {
+  if (value === undefined || value === null || value === '') return undefined;
+  return typeof value === 'number' ? `${value}px` : /^\d+(?:\.\d+)?$/.test(value) ? `${value}px` : value;
+}

package/src/gcsaTablePreferences.ts

@@ -0,0 +1,61 @@
+export type GcsaTableSortingPreference = { id: string; desc: boolean };
+
+export type GcsaTablePreferences = {
+  columnVisibility?: Record<string, boolean>;
+  columnWidths?: Record<string, number>;
+  sorting?: GcsaTableSortingPreference[];
+  pageSize?: number;
+};
+
+export type GcsaTablePreferenceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeRecord<T>(value: unknown, predicate: (entry: unknown) => entry is T): Record<string, T> | undefined {
+  if (!isRecord(value)) return undefined;
+  const entries = Object.entries(value).filter(([, entry]) => predicate(entry));
+  return entries.length ? Object.fromEntries(entries) as Record<string, T> : undefined;
+}
+
+export function normalizeGcsaTablePreferences(value: unknown): GcsaTablePreferences {
+  if (!isRecord(value)) return {};
+  const columnVisibility = normalizeRecord(value.columnVisibility, (entry): entry is boolean => typeof entry === 'boolean');
+  const columnWidths = normalizeRecord(value.columnWidths, (entry): entry is number => typeof entry === 'number' && Number.isFinite(entry) && entry > 0);
+  const sorting = Array.isArray(value.sorting)
+    ? value.sorting.filter(isRecord).filter(entry => typeof entry.id === 'string' && typeof entry.desc === 'boolean').map(entry => ({ id: entry.id as string, desc: entry.desc as boolean }))
+    : undefined;
+  const pageSize = typeof value.pageSize === 'number' && Number.isInteger(value.pageSize) && value.pageSize > 0 ? value.pageSize : undefined;
+  return { columnVisibility, columnWidths, sorting: sorting?.length ? sorting : undefined, pageSize };
+}
+
+export function readGcsaTablePreferences(storage: GcsaTablePreferenceStorage | undefined, key: string): GcsaTablePreferences {
+  if (!storage || !key) return {};
+  try {
+    const raw = storage.getItem(key);
+    return raw ? normalizeGcsaTablePreferences(JSON.parse(raw)) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function writeGcsaTablePreferences(storage: GcsaTablePreferenceStorage | undefined, key: string, value: GcsaTablePreferences): boolean {
+  if (!storage || !key) return false;
+  try {
+    storage.setItem(key, JSON.stringify(normalizeGcsaTablePreferences(value)));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function clearGcsaTablePreferences(storage: GcsaTablePreferenceStorage | undefined, key: string): boolean {
+  if (!storage || !key) return false;
+  try {
+    storage.removeItem(key);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/gcsaTableRows.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolves the row id used by TanStack Table and the legacy table API.
+ * TanStack's default fallback is relative to the parent row; keeping that
+ * behavior here prevents parent and child rows from sharing an id in trees.
+ */
+export function getGcsaTableRowId<T extends Record<string, unknown>>(
+  row: T,
+  index: number,
+  rowKey?: keyof T & string | ((row: T, index: number) => string),
+  parentId?: string
+) {
+  if (typeof rowKey === 'function') return rowKey(row, index);
+  if (rowKey) return String(row[rowKey]);
+  return parentId ? `${parentId}.${index}` : String(index);
+}
+
+export function getGcsaTableDefaultExpandedKeys<T extends Record<string, unknown>>(
+  rows: T[],
+  treeData: boolean,
+  childrenKey: keyof T & string,
+  rowKey?: keyof T & string | ((row: T, index: number) => string)
+) {
+  if (!treeData) return rows.map((row, index) => getGcsaTableRowId(row, index, rowKey));
+  const keys: string[] = [];
+  const visit = (items: T[], parentPath = '') => {
+    items.forEach((row, index) => {
+      const children = (row as Record<string, unknown>)[childrenKey];
+      if (!Array.isArray(children) || !children.length) return;
+      const path = parentPath ? `${parentPath}.${index}` : String(index);
+      keys.push(rowKey ? getGcsaTableRowId(row, index, rowKey) : path);
+      visit(children as T[], path);
+    });
+  };
+  visit(rows);
+  return keys;
+}

package/src/gcsaTime.ts

@@ -0,0 +1,83 @@
+/** 24 小时制时间字符串 HH:mm */
+export type GcsaTimeString = string;
+
+export type GcsaTimePickerOptions = {
+  min?: GcsaTimeString;
+  max?: GcsaTimeString;
+  /** 步长，单位秒，默认 60 */
+  step?: number;
+};
+
+export const GCSA_TIME_STRING_PATTERN = /^\d{2}:\d{2}$/;
+export const GCSA_TIME_PICKER_CELL_HEIGHT = 32;
+
+export function isGcsaTimeString(value: string): value is GcsaTimeString {
+  return GCSA_TIME_STRING_PATTERN.test(value);
+}
+
+export function gcsaTimeToMinutes(value?: string): number | undefined {
+  if (!value || !GCSA_TIME_STRING_PATTERN.test(value)) return undefined;
+  const [hours, minutes] = value.split(':').map(Number);
+  return hours * 60 + minutes;
+}
+
+export function gcsaMinutesToTime(totalMinutes: number): GcsaTimeString {
+  const normalized = Math.max(0, Math.min(1439, totalMinutes));
+  const hours = Math.floor(normalized / 60);
+  const minutes = normalized % 60;
+  return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}`;
+}
+
+export function gcsaNormalizeTimeStep(step?: number): number {
+  const seconds = Number(step);
+  if (!Number.isFinite(seconds) || seconds <= 0) return 60;
+  return Math.max(60, Math.round(seconds / 60) * 60);
+}
+
+export function gcsaBuildTimeOptions({ min, max, step }: GcsaTimePickerOptions = {}): GcsaTimeString[] {
+  const incrementMinutes = gcsaNormalizeTimeStep(step) / 60;
+  const start = Math.max(0, gcsaTimeToMinutes(min) ?? 0);
+  const end = Math.min(1439, gcsaTimeToMinutes(max) ?? 1439);
+  const result: GcsaTimeString[] = [];
+
+  for (let value = start; value <= end; value += incrementMinutes) {
+    result.push(gcsaMinutesToTime(value));
+  }
+
+  return result.length ? result : [gcsaMinutesToTime(start)];
+}
+
+export function gcsaTimePickerHours(options: GcsaTimeString[]): string[] {
+  return [...new Set(options.map(option => option.slice(0, 2)))];
+}
+
+export function gcsaTimePickerMinutes(options: GcsaTimeString[], hour: string): string[] {
+  return options.filter(option => option.startsWith(`${hour}:`)).map(option => option.slice(3));
+}
+
+export function gcsaResolveTimeDraft(value: string | undefined, options: GcsaTimeString[]): GcsaTimeString {
+  if (value && options.includes(value)) return value;
+  return options[0] ?? '00:00';
+}
+
+export function gcsaNearestTimeOption(options: GcsaTimeString[], targetMinutes: number): GcsaTimeString {
+  return options.reduce((best, option) => {
+    const optionMinutes = gcsaTimeToMinutes(option) ?? 0;
+    const bestMinutes = gcsaTimeToMinutes(best) ?? 0;
+    return Math.abs(optionMinutes - targetMinutes) < Math.abs(bestMinutes - targetMinutes) ? option : best;
+  }, options[0] ?? '00:00');
+}
+
+export function gcsaCurrentTimeOption(options: GcsaTimeString[]): GcsaTimeString {
+  const now = new Date();
+  return gcsaNearestTimeOption(options, now.getHours() * 60 + now.getMinutes());
+}
+
+export function gcsaTimePickerScrollTop(index: number): number {
+  return Math.max(0, index) * GCSA_TIME_PICKER_CELL_HEIGHT;
+}
+
+export function gcsaTimePickerScrollIndex(scrollTop: number, itemCount: number): number {
+  if (!itemCount) return 0;
+  return Math.max(0, Math.min(itemCount - 1, Math.round(scrollTop / GCSA_TIME_PICKER_CELL_HEIGHT)));
+}