@vc-shell/framework 1.2.3-beta.1 → 1.2.4-beta.1

package/ui/components/organisms/vc-table/components/mobile/PullToRefresh.vue

@@ -0,0 +1,353 @@
+<template>
+  <div
+    ref="containerRef"
+    class="vc-pull-to-refresh"
+    @touchstart.passive="onTouchStart"
+    @touchmove.passive="onTouchMove"
+    @touchend="onTouchEnd"
+  >
+    <!-- Refresh indicator (hidden above content) -->
+    <div
+      class="vc-pull-to-refresh__indicator"
+      :style="indicatorStyle"
+    >
+      <div class="vc-pull-to-refresh__indicator-content">
+        <VcIcon
+          :icon="indicatorIcon"
+          class="vc-pull-to-refresh__icon"
+          :class="iconClasses"
+        />
+        <span class="vc-pull-to-refresh__text">{{ statusText }}</span>
+      </div>
+    </div>
+
+    <!-- Content with spring animation -->
+    <div
+      class="vc-pull-to-refresh__content"
+      :style="contentStyle"
+    >
+      <slot />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+/**
+ * PullToRefresh - Pull-to-refresh component with spring animation
+ *
+ * Provides iOS-like pull-to-refresh functionality for mobile views.
+ * Uses spring physics animation for natural feel.
+ *
+ * Features:
+ * - Spring physics animation (matching swipe actions)
+ * - Icon rotates 180° when threshold passed
+ * - Only active on mobile
+ * - Disabled when content is scrolled down (scrollTop > 0)
+ * - Disabled when refreshing=true
+ */
+import { ref, computed, inject, type Ref } from "vue";
+import { useI18n } from "vue-i18n";
+
+export interface PullToRefreshProps {
+  /** Enable/disable pull-to-refresh */
+  enabled?: boolean;
+  /** Distance threshold to trigger refresh (px) */
+  threshold?: number;
+  /** Loading state - parent controls when refresh is complete */
+  refreshing?: boolean;
+  /** Custom text for "pull" state (overrides i18n) */
+  pullText?: string;
+  /** Custom text for "release" state (overrides i18n) */
+  releaseText?: string;
+  /** Custom text for "refreshing" state (overrides i18n) */
+  refreshingText?: string;
+}
+
+const props = withDefaults(defineProps<PullToRefreshProps>(), {
+  enabled: true,
+  threshold: 60,
+  refreshing: false,
+  pullText: undefined,
+  releaseText: undefined,
+  refreshingText: undefined,
+});
+
+// i18n
+const { t } = useI18n({ useScope: "global" });
+
+const emit = defineEmits<{
+  /** Triggered when user releases after passing threshold */
+  refresh: [];
+}>();
+
+// Check if mobile via inject (provided by VcDataTable or parent)
+const isMobile = inject<Ref<boolean>>("isMobile", ref(true));
+
+// Refs
+const containerRef = ref<HTMLElement | null>(null);
+
+// Pull state
+const pullDistance = ref(0);
+const isPulling = ref(false);
+const canRelease = ref(false);
+const isAnimating = ref(false);
+const animationId = ref<number | null>(null);
+
+// Touch tracking
+const startY = ref(0);
+const velocity = ref(0);
+const lastTime = ref(0);
+const lastY = ref(0);
+
+// Spring animation constants (matching swipe actions)
+const SPRING_STIFFNESS = 0.08;
+const SPRING_DAMPING = 0.7;
+const SPRING_MASS = 1;
+
+// Indicator height
+const INDICATOR_HEIGHT = 60;
+
+// Computed states
+const isActive = computed(() => {
+  return props.enabled && isMobile.value && !props.refreshing;
+});
+
+const indicatorIcon = computed(() => {
+  if (props.refreshing) {
+    return "fas fa-sync";
+  }
+  return "fas fa-arrow-down";
+});
+
+const iconClasses = computed(() => ({
+  "vc-pull-to-refresh__icon--rotate": canRelease.value && !props.refreshing,
+  "vc-pull-to-refresh__icon--spin": props.refreshing,
+}));
+
+const statusText = computed(() => {
+  if (props.refreshing) {
+    return props.refreshingText ?? t("COMPONENTS.ORGANISMS.VC_TABLE.REFRESHING");
+  }
+  if (canRelease.value) {
+    return props.releaseText ?? t("COMPONENTS.ORGANISMS.VC_TABLE.RELEASE_TO_REFRESH");
+  }
+  return props.pullText ?? t("COMPONENTS.ORGANISMS.VC_TABLE.PULL_TO_REFRESH");
+});
+
+const indicatorStyle = computed(() => {
+  const offset = Math.min(pullDistance.value, INDICATOR_HEIGHT + 20);
+  return {
+    transform: `translateY(${offset - INDICATOR_HEIGHT}px)`,
+    opacity: Math.min(pullDistance.value / props.threshold, 1),
+  };
+});
+
+const contentStyle = computed(() => {
+  return {
+    transform: `translateY(${pullDistance.value}px)`,
+  };
+});
+
+// Check if container is scrolled to top
+function isAtTop(): boolean {
+  if (!containerRef.value) return true;
+
+  // Check if container or any scrollable parent is scrolled
+  let element: HTMLElement | null = containerRef.value;
+  while (element) {
+    if (element.scrollTop > 0) {
+      return false;
+    }
+    element = element.parentElement;
+  }
+  return true;
+}
+
+// Spring animation
+function springAnimation(targetValue: number, duration = 300) {
+  if (animationId.value !== null) {
+    cancelAnimationFrame(animationId.value);
+  }
+
+  const startValue = pullDistance.value;
+  const startTime = performance.now();
+  let springVelocity = velocity.value;
+  let currentValue = startValue;
+
+  isAnimating.value = true;
+
+  function animate(time: number) {
+    const elapsed = time - startTime;
+
+    if (elapsed < duration) {
+      const springForce = (targetValue - currentValue) * SPRING_STIFFNESS;
+      const dampingForce = springVelocity * SPRING_DAMPING;
+      const acceleration = (springForce - dampingForce) / SPRING_MASS;
+
+      springVelocity += acceleration;
+      currentValue += springVelocity;
+
+      pullDistance.value = Math.max(0, currentValue);
+
+      animationId.value = requestAnimationFrame(animate);
+    } else {
+      pullDistance.value = targetValue;
+      isAnimating.value = false;
+      animationId.value = null;
+    }
+  }
+
+  animationId.value = requestAnimationFrame(animate);
+}
+
+// Touch handlers
+function onTouchStart(e: TouchEvent) {
+  if (!isActive.value || isAnimating.value) return;
+  if (!isAtTop()) return;
+
+  const touch = e.touches[0];
+  startY.value = touch.clientY;
+  velocity.value = 0;
+  lastTime.value = Date.now();
+  lastY.value = touch.clientY;
+  isPulling.value = true;
+}
+
+function onTouchMove(e: TouchEvent) {
+  if (!isActive.value || !isPulling.value || isAnimating.value) return;
+
+  const touch = e.touches[0];
+  const currentY = touch.clientY;
+  const deltaY = currentY - startY.value;
+
+  // Only handle pull down
+  if (deltaY < 0) {
+    isPulling.value = false;
+    pullDistance.value = 0;
+    return;
+  }
+
+  // Calculate velocity for inertia
+  const now = Date.now();
+  const dt = now - lastTime.value;
+  if (dt > 0) {
+    velocity.value = (currentY - lastY.value) / dt;
+  }
+  lastTime.value = now;
+  lastY.value = currentY;
+
+  // Apply resistance as user pulls further
+  const resistance = Math.max(0.4, 1 - deltaY / 300);
+  let newPullDistance = deltaY * resistance;
+
+  // Cap at max pull distance
+  const maxPull = props.threshold * 2.5;
+  newPullDistance = Math.min(newPullDistance, maxPull);
+
+  pullDistance.value = newPullDistance;
+  canRelease.value = newPullDistance >= props.threshold;
+}
+
+function onTouchEnd() {
+  if (!isPulling.value) return;
+
+  isPulling.value = false;
+
+  if (canRelease.value && !props.refreshing) {
+    // Trigger refresh
+    emit("refresh");
+    // Animate to threshold height (show indicator while refreshing)
+    springAnimation(INDICATOR_HEIGHT);
+  } else {
+    // Animate back to 0
+    springAnimation(0);
+  }
+
+  canRelease.value = false;
+}
+
+// Watch for refreshing prop to animate back when done
+import { watch } from "vue";
+
+watch(
+  () => props.refreshing,
+  (newValue, oldValue) => {
+    if (oldValue && !newValue) {
+      // Refreshing finished, animate back to 0
+      springAnimation(0);
+    }
+  }
+);
+
+// Cleanup on unmount
+import { onUnmounted } from "vue";
+
+onUnmounted(() => {
+  if (animationId.value !== null) {
+    cancelAnimationFrame(animationId.value);
+  }
+});
+
+// Expose for testing
+defineExpose({
+  pullDistance,
+  canRelease,
+  isPulling,
+});
+</script>
+
+<style lang="scss">
+:root {
+  --ptr-indicator-bg: var(--additional-50);
+  --ptr-indicator-text: var(--neutrals-600);
+  --ptr-indicator-icon: var(--primary-500);
+}
+
+.vc-pull-to-refresh {
+  // overflow: clip (not hidden!) — clips the pull indicator visually
+  // but does NOT create a scroll container. With `hidden`, touch scroll events
+  // get trapped and never reach the parent overflow-y: auto element.
+  @apply tw-relative;
+  overflow: clip;
+
+  &__indicator {
+    @apply tw-absolute tw-left-0 tw-right-0 tw-top-0 tw-flex tw-items-center tw-justify-center;
+    @apply tw-bg-[var(--ptr-indicator-bg)] tw-text-[var(--ptr-indicator-text)];
+    height: 60px;
+    z-index: 10;
+  }
+
+  &__indicator-content {
+    @apply tw-flex tw-items-center tw-gap-2;
+  }
+
+  &__icon {
+    @apply tw-text-xl tw-text-[var(--ptr-indicator-icon)] tw-transition-transform tw-duration-200;
+
+    &--rotate {
+      transform: rotate(180deg);
+    }
+
+    &--spin {
+      animation: ptr-spin 1s linear infinite;
+    }
+  }
+
+  &__text {
+    @apply tw-text-sm tw-font-medium;
+  }
+
+  &__content {
+    @apply tw-relative tw-will-change-transform;
+  }
+}
+
+@keyframes ptr-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+</style>

package/ui/components/organisms/vc-table/components/mobile/index.ts

@@ -0,0 +1,6 @@
+// Mobile components for VcDataTable
+export { default as MobileCellRenderer } from "./MobileCellRenderer.vue";
+export { default as MobileActionSheet } from "./MobileActionSheet.vue";
+export { default as DataTableMobileCard } from "./DataTableMobileCard.vue";
+export { default as DataTableMobileView } from "./DataTableMobileView.vue";
+export { default as PullToRefresh } from "./PullToRefresh.vue";

package/ui/components/organisms/vc-table/composables/index.ts

@@ -0,0 +1,49 @@
+// === PUBLIC API ===
+export { useTableContext } from "./useTableContext";
+// useTableSelection — exported from shared/composables (not from this directory)
+export { useTableColumnsResize } from "./useTableColumnsResize";
+export { useTableColumnsReorder } from "./useTableColumnsReorder";
+export { useTableRowReorder } from "./useTableRowReorder";
+export { useTableInlineEdit } from "./useTableInlineEdit";
+export { useVirtualScroll } from "./useVirtualScroll";
+export type { VirtualScrollOptions, VirtualScrollItem, VirtualScrollReturn } from "./useVirtualScroll";
+export { useTableRowGrouping } from "./useTableRowGrouping";
+export type { RowGroupingOptions, GroupedData, UseTableRowGroupingReturn } from "./useTableRowGrouping";
+export { useFilterState } from "./useTableFilter";
+export type { UseFilterStateOptions, UseFilterStateReturn } from "./useTableFilter";
+export { useColumnFilter } from "./useColumnFilter";
+export type { UseColumnFilterReturn } from "./useColumnFilter";
+
+// === NEW COMPOSABLES (PrimeVue-style) ===
+export { useTableSort } from "./useTableSort";
+export type { UseTableSortOptions, UseTableSortReturn, SortEvent } from "./useTableSort";
+export { useTableEditing } from "./useTableEditing";
+export type {
+  UseTableEditingOptions,
+  UseTableEditingReturn,
+  CellEditEvent,
+  CellEditCompleteEvent,
+  RowEditEvent,
+  RowEditSaveEvent,
+} from "./useTableEditing";
+export { useTableExpansion } from "./useTableExpansion";
+export type { UseTableExpansionOptions, UseTableExpansionReturn, RowExpandEvent } from "./useTableExpansion";
+export { useTableSelectionV2 } from "./useTableSelectionV2";
+export type {
+  UseTableSelectionV2Options,
+  UseTableSelectionV2Return,
+  RowSelectEvent,
+  RowSelectAllEvent,
+} from "./useTableSelectionV2";
+export { useDataProcessing } from "./useDataProcessing";
+export type { UseDataProcessingOptions, UseDataProcessingReturn } from "./useDataProcessing";
+export { useTableColumns } from "./useTableColumns";
+export type { UseTableColumnsOptions, UseTableColumnsReturn } from "./useTableColumns";
+export { useMobileCardLayout } from "./useMobileCardLayout";
+export type { UseMobileCardLayoutOptions, UseMobileCardLayoutReturn } from "./useMobileCardLayout";
+export { useDataTableState } from "./useDataTableState";
+export type { UseDataTableStateOptions, UseDataTableStateReturn, DataTablePersistedState } from "./useDataTableState";
+
+// === SWIPE (used by mobile components) ===
+export { useTableSwipe, provideTableSwipe } from "./useTableSwipe";
+

package/ui/components/organisms/vc-table/composables/useCellBase.ts

@@ -0,0 +1,114 @@
+import { computed, type Ref, toRef } from "vue";
+
+/**
+ * Common props for all editable cell components
+ */
+export interface CellBaseProps {
+  /** Cell value */
+  value?: unknown;
+  /** Whether cell is editable */
+  editable?: boolean;
+  /** Label for the field (used in validation) */
+  label?: string;
+  /** Field name for validation */
+  fieldName?: string;
+  /** Field ID for identifying the cell */
+  fieldId?: string;
+  /** Validation rules */
+  rules?: Record<string, unknown>;
+  /** Row index for identifying the row */
+  rowIndex?: number;
+}
+
+/**
+ * Common emits for all editable cell components
+ */
+export interface CellBaseEmits {
+  (e: "update", payload: { field: string; value: unknown }): void;
+  (e: "blur", payload: { row: number | undefined; field: string }): void;
+}
+
+/**
+ * Options for useCellBase composable
+ */
+export interface UseCellBaseOptions<T = unknown> {
+  /** Props from the component */
+  props: CellBaseProps;
+  /** Emit function from the component */
+  emit: CellBaseEmits;
+  /** Formatter function to format display value */
+  formatter?: (value: T) => string;
+  /** Check if value is empty (for "Not Set" display) */
+  isEmpty?: (value: T) => boolean;
+}
+
+/**
+ * Base composable for cell components.
+ * Provides common logic for editable cells: blur handling, value formatting, empty state.
+ *
+ * @example
+ * ```ts
+ * const { onBlur, displayValue, isValueEmpty } = useCellBase({
+ *   props,
+ *   emit,
+ *   formatter: (val) => formatMoney(val, props.currency),
+ *   isEmpty: (val) => val == null || val === 0,
+ * });
+ * ```
+ */
+export function useCellBase<T = unknown>(options: UseCellBaseOptions<T>) {
+  const { props, emit, formatter, isEmpty: isEmptyFn } = options;
+
+  /**
+   * Handle blur event from input.
+   * Only emits blur if there are no validation errors.
+   */
+  const onBlur = (errors: string[]) => {
+    if (errors && errors.length > 0) return;
+    emit("blur", { row: props.rowIndex, field: props.fieldId || "" });
+  };
+
+  /**
+   * Handle value update from input
+   */
+  const onUpdate = (newValue: unknown) => {
+    emit("update", { field: props.fieldId || "", value: newValue });
+  };
+
+  /**
+   * Formatted display value
+   */
+  const displayValue = computed(() => {
+    const val = props.value as T;
+    if (val == null) return "";
+    if (formatter) return formatter(val);
+    return String(val);
+  });
+
+  /**
+   * Whether value is considered empty (for "Not Set" display)
+   */
+  const isValueEmpty = computed(() => {
+    const val = props.value as T;
+    if (isEmptyFn) return isEmptyFn(val);
+    return val == null;
+  });
+
+  /**
+   * Common editable wrapper props
+   */
+  const editableWrapperProps = computed(() => ({
+    label: props.label || "",
+    fieldName: props.fieldName || "",
+    modelValue: props.value,
+    rules: props.rules,
+  }));
+
+  return {
+    onBlur,
+    onUpdate,
+    displayValue,
+    isValueEmpty,
+    editableWrapperProps,
+  };
+}

package/ui/components/organisms/vc-table/composables/useCellRegistry.ts

@@ -0,0 +1,130 @@
+import { shallowReactive, type Component, type DefineComponent } from "vue";
+
+/**
+ * Supported cell types for VcDataTable columns.
+ * Maps to cell formatter components.
+ */
+export type CellType =
+  | "text"
+  | "number"
+  | "money"
+  | "date"
+  | "date-ago"
+  | "time"
+  | "datetime"
+  | "image"
+  | "link"
+  | "html"
+  | "status"
+  | "status-icon";
+
+/**
+ * Configuration for cell type-specific props.
+ * Different cell types may require additional props beyond the common ones.
+ */
+export interface CellTypeConfig {
+  /** Whether this cell type supports inline editing */
+  editable?: boolean;
+  /** Additional props to pass to the cell component */
+  additionalProps?: string[];
+}
+
+/**
+ * Registration entry for a cell component in the registry.
+ */
+export interface CellRegistration {
+  /** The cell type identifier */
+  type: CellType | string;
+  /** The Vue component to render for this cell type */
+  component: Component | DefineComponent<any, any, any>;
+  /** Optional configuration for this cell type */
+  config?: CellTypeConfig;
+}
+
+// Reactive registry - changes trigger Vue reactivity
+const registry = shallowReactive(new Map<string, CellRegistration>());
+
+/**
+ * useCellRegistry - Composable for managing cell type components.
+ *
+ * Implements the Registry pattern with Vue 3 reactivity:
+ * 1. Decouples cell type definitions from the renderer
+ * 2. Easy registration of custom cell types
+ * 3. Open/Closed Principle: extend without modifying DataTableCellRenderer
+ * 4. Reactive: changes trigger component updates
+ *
+ * @example
+ * ```ts
+ * const { register, get, has } = useCellRegistry();
+ *
+ * // Register a custom cell type
+ * register({
+ *   type: "rating",
+ *   component: CellRating,
+ *   config: { editable: false }
+ * });
+ *
+ * // Get component for a type
+ * const registration = get("rating");
+ * ```
+ */
+export function useCellRegistry() {
+  /**
+   * Register a cell type with its component.
+   * @param registration - The cell registration entry
+   */
+  const register = (registration: CellRegistration): void => {
+    registry.set(registration.type, registration);
+  };
+
+  /**
+   * Get the registration for a cell type.
+   * @param type - The cell type to look up
+   * @returns The registration entry or undefined if not found
+   */
+  const get = (type: string): CellRegistration | undefined => {
+    return registry.get(type);
+  };
+
+  /**
+   * Check if a cell type is registered.
+   * @param type - The cell type to check
+   */
+  const has = (type: string): boolean => {
+    return registry.has(type);
+  };
+
+  /**
+   * Get all registered cell types.
+   * @returns Array of registered type names
+   */
+  const getRegisteredTypes = (): string[] => {
+    return Array.from(registry.keys());
+  };
+
+  /**
+   * Unregister a cell type.
+   * @param type - The cell type to remove
+   */
+  const unregister = (type: string): boolean => {
+    return registry.delete(type);
+  };
+
+  /**
+   * Clear all registrations.
+   */
+  const clear = (): void => {
+    registry.clear();
+  };
+
+  return {
+    register,
+    get,
+    has,
+    getRegisteredTypes,
+    unregister,
+    clear,
+  };
+}
+
+export type UseCellRegistryReturn = ReturnType<typeof useCellRegistry>;