@vc-shell/framework 1.2.4-beta.8 → 2.0.0-alpha.0

package/ui/composables/README.md

@@ -1,160 +0,0 @@
-# UI Composables
-
-This directory contains reusable composables for UI components.
-
-## Available Composables
-
-### useAdaptiveItems
-
-A composable for adaptive rendering of elements in a container that automatically determines which elements fit in the available space without using hidden "measure" containers.
-
-#### Features
-
-- **Automatic size measurement** — precise element size detection using ResizeObserver
-- **Size caching** — improves performance by storing element dimensions
-- **Support for different display strategies** — choose between displaying from the beginning or end of the list
-- **Reactivity** — automatic recalculation when container or element sizes change
-- **Performance** — optimized algorithm with minimal DOM operations
-
-#### Usage
-
-```vue
-<template>
-  <div ref="containerRef">
-    <!-- Visible elements -->
-    <div 
-      v-for="item in visibleItems" 
-      :key="item.id"
-      :data-item-key="item.id"
-    >
-      {{ item.content }}
-    </div>
-    
-    <!-- Dropdown menu for hidden elements -->
-    <dropdown-menu 
-      v-if="showMoreButton"
-      :items="hiddenItems"
-    />
-  </div>
-</template>
-
-<script setup>
-import { ref, computed } from 'vue';
-import { useAdaptiveItems } from 'framework/ui/composables/useAdaptiveItems';
-
-const containerRef = ref(null);
-const items = ref([
-  { id: '1', content: 'Item 1' },
-  { id: '2', content: 'Item 2' },
-  // ...
-]);
-
-const { 
-  visibleItems,      // Elements that fit in the container
-  hiddenItems,       // Elements that don't fit
-  showMoreButton,    // Flag indicating if "More" button should be shown
-  recalculate,       // Function for manual recalculation
-  updateObserver     // Function to update the observer
-} = useAdaptiveItems({
-  containerRef,
-  items,
-  getItemKey: (item) => item.id,             // Function to get unique element key
-  moreButtonWidth: 80,                       // Width of the "More" button
-  calculationStrategy: 'forward',            // Strategy: 'forward' or 'reverse'
-  initialItemWidth: 100                      // Initial estimate of element width
-});
-</script>
-```
-
-#### Important: data-item-key Attribute
-
-For the composable to work correctly, you need to add the `data-item-key` attribute to each element:
-
-```vue
-<div 
-  v-for="item in visibleItems" 
-  :key="item.id"
-  :data-item-key="item.id" <!-- Required for size measurement -->
->
-  {{ item.content }}
-</div>
-```
-
-#### API
-
-```typescript
-function useAdaptiveItems<T>(options: {
-  // Reference to the container
-  containerRef: Ref<HTMLElement | null>;
-  
-  // List of items
-  items: Ref<T[]> | ComputedRef<T[]>;
-  
-  // Function to get unique key for an item
-  getItemKey: (item: T) => string;
-  
-  // Width of the "More" button
-  moreButtonWidth: number;
-  
-  // Calculation strategy: 'forward' (from beginning) or 'reverse' (from end)
-  calculationStrategy?: 'forward' | 'reverse';
-  
-  // Initial estimate of item width (before measurement)
-  initialItemWidth?: number;
-}): {
-  // Elements that fit in the container
-  visibleItems: Ref<T[]>;
-  
-  // Elements that don't fit
-  hiddenItems: Ref<T[]>;
-  
-  // Flag indicating if "More" button should be shown
-  showMoreButton: Ref<boolean>;
-  
-  // Function for manual recalculation
-  recalculate: () => void;
-  
-  // Function to update the observer (if the list of elements has changed)
-  updateObserver: () => void;
-}
-```
-
-#### Calculation Strategies
-
-- **forward** (default) — elements are displayed from the beginning of the list, remaining ones are hidden
-- **reverse** — elements are displayed from the end of the list, first elements are hidden
-
-#### Usage Examples
-
-##### Breadcrumbs (with reverse strategy)
-
-```typescript
-const { visibleItems, hiddenItems, showMoreButton } = useAdaptiveItems({
-  containerRef: el,
-  items: toRef(props, "items"),
-  getItemKey: (item) => item.id,
-  moreButtonWidth: 100,
-  calculationStrategy: "reverse", // Show last elements, hide first ones
-  initialItemWidth: 100
-});
-```
-
-##### Toolbar
-
-```typescript
-const { visibleItems, hiddenItems, showMoreButton } = useAdaptiveItems({
-  containerRef: toolbarRef,
-  items: computed(() => tools),
-  getItemKey: (item) => item.id,
-  moreButtonWidth: 70,
-  calculationStrategy: "forward", // Show first elements, hide last ones
-  initialItemWidth: 60
-});
-```
-
-#### Performance Optimization
-
-1. **Don't overuse recalculations** — use `recalculate()` only when truly necessary
-2. **Set accurate initialItemWidth** — this reduces the number of redraws during initial loading
-3. **Use updateObserver** — after adding new elements, call this function to update the observer
-4. **Let the composable do its job** — the automatic measurement mechanism is efficient, trust it

package/ui/composables/index.ts

@@ -1,6 +0,0 @@
-export * from "@ui/composables/useAdaptiveItems";
-export * from "@ui/composables/useCollapsible";
-export * from "@ui/composables/useFloatingPosition";
-export { useFormField } from "@ui/composables/useFormField";
-export * from "@ui/composables/useScrollArrows";
-export * from "@ui/composables/useTeleportTarget";

package/ui/composables/useAdaptiveItems.ts

@@ -1,347 +0,0 @@
-import { ref, computed, onMounted, onBeforeUnmount, nextTick, type Ref, watch } from "vue";
-import { useElementSize, useDebounceFn } from "@vueuse/core";
-
-/**
- * Measure the natural (unshrunk) width of an element.
- * Temporarily forces flex-shrink:0 so the browser reports the element's
- * preferred width rather than a compressed one.
- */
-function measureNaturalWidth(element: HTMLElement): number {
-  const originalFlexShrink = element.style.flexShrink;
-  element.style.flexShrink = "0";
-
-  const styles = getComputedStyle(element);
-  const width =
-    element.offsetWidth + parseFloat(styles.marginLeft || "0") + parseFloat(styles.marginRight || "0");
-
-  element.style.flexShrink = originalFlexShrink;
-  return width;
-}
-
-/**
- * Read the CSS gap value from a flex/grid container.
- */
-function readContainerGap(container: HTMLElement): number {
-  const styles = getComputedStyle(container);
-  // `gap` is the shorthand; `columnGap` is more specific for row layouts
-  const gap = styles.columnGap || styles.gap || "0px";
-  return parseFloat(gap) || 0;
-}
-
-export function useAdaptiveItems<T>(options: {
-  containerRef: Ref<HTMLElement | null>;
-  items: Ref<T[]>;
-  getItemKey: (item: T) => string;
-  /** Fallback width for the "more" button before it can be measured from DOM.
-   *  If the consumer marks its trigger element with `data-more-button`,
-   *  the composable will auto-measure the real width and use it instead. */
-  moreButtonWidth: number;
-  calculationStrategy?: "forward" | "reverse";
-  initialItemWidth?: number;
-}) {
-  const {
-    containerRef,
-    items,
-    getItemKey,
-    moreButtonWidth: moreButtonFallbackWidth,
-    calculationStrategy = "forward",
-    initialItemWidth = 50,
-  } = options;
-
-  // Container width tracking
-  const { width: containerWidth } = useElementSize(containerRef);
-
-  // Cache of natural element widths (key → px)
-  const itemSizes = ref<Map<string, number>>(new Map());
-
-  // Measured "more" button width (null = not yet measured, use fallback)
-  const measuredMoreWidth = ref<number | null>(null);
-
-  // Current CSS gap of the container
-  const containerGap = ref(0);
-
-  // Result arrays
-  const visibleItems = ref<T[]>([]);
-  const hiddenItems = ref<T[]>([]);
-  const showMoreButton = computed(() => hiddenItems.value.length > 0);
-
-  // Single persistent ResizeObserver
-  let elementsObserver: ResizeObserver | null = null;
-  // Track observed elements so we can unobserve stale ones
-  const observedElements = new Set<Element>();
-
-  /** Effective "more" button width: measured from DOM or fallback constant. */
-  const getMoreButtonWidth = (): number => {
-    return measuredMoreWidth.value ?? moreButtonFallbackWidth;
-  };
-
-  /**
-   * Try to measure the "more" button from the DOM.
-   * The consumer marks the trigger element with `data-more-button`.
-   */
-  const measureMoreButton = () => {
-    if (!containerRef.value) return;
-    const el = containerRef.value.querySelector("[data-more-button]") as HTMLElement | null;
-    if (el) {
-      const width = measureNaturalWidth(el);
-      if (width > 0) {
-        measuredMoreWidth.value = width;
-      }
-    }
-  };
-
-  /**
-   * Get element width by key.
-   * Falls back to initialItemWidth if not yet measured.
-   */
-  const getItemWidth = (item: T): number => {
-    const key = getItemKey(item);
-    return itemSizes.value.get(key) || initialItemWidth;
-  };
-
-  /**
-   * Distribute items into visible/hidden arrays for a given available width,
-   * accounting for CSS gap between items.
-   */
-  const distributeItems = (itemsToCheck: T[], availableWidth: number) => {
-    let currentWidth = 0;
-    const visible: T[] = [];
-    const hidden: T[] = [];
-    const gap = containerGap.value;
-
-    for (const item of itemsToCheck) {
-      const itemWidth = getItemWidth(item);
-      const gapBefore = visible.length > 0 ? gap : 0;
-
-      if (currentWidth + gapBefore + itemWidth <= availableWidth) {
-        visible.push(item);
-        currentWidth += gapBefore + itemWidth;
-      } else {
-        hidden.push(item);
-      }
-    }
-
-    return { visible, hidden };
-  };
-
-  /**
-   * Calculate which elements will be visible and which will be hidden.
-   *
-   * Uses a two-pass approach:
-   * 1st pass: calculate assuming no "more" button
-   * 2nd pass (if overflow): recalculate with "more" button width reserved
-   */
-  const calculateVisibleItems = () => {
-    if (!containerRef.value || !items.value.length) return;
-
-    // When container has no width yet, show all items so the container gains
-    // intrinsic size. ResizeObserver will trigger a recalculation once it does.
-    if (containerWidth.value <= 0) {
-      visibleItems.value = [...items.value];
-      hiddenItems.value = [];
-      return;
-    }
-
-    // Always read fresh gap (may change with responsive breakpoints)
-    containerGap.value = readContainerGap(containerRef.value);
-    const gap = containerGap.value;
-    const itemsToCheck = calculationStrategy === "reverse" ? [...items.value].reverse() : items.value;
-
-    // 1st pass: full container width (no "more" button)
-    let result = distributeItems(itemsToCheck, containerWidth.value);
-
-    // 2nd pass: if items overflowed, recalculate with "more" button space reserved
-    // Also account for the gap before/after the "more" button
-    if (result.hidden.length > 0) {
-      const effectiveMoreWidth = getMoreButtonWidth();
-      const gapBeforeMore = result.visible.length > 0 ? gap : 0;
-      result = distributeItems(itemsToCheck, containerWidth.value - effectiveMoreWidth - gapBeforeMore);
-    }
-
-    // Restore original order for reverse strategy
-    if (calculationStrategy === "reverse") {
-      visibleItems.value = result.visible.reverse();
-      hiddenItems.value = result.hidden.reverse();
-    } else {
-      visibleItems.value = result.visible;
-      hiddenItems.value = result.hidden;
-    }
-  };
-
-  /**
-   * Measure natural widths of all rendered items and update the cache.
-   * Also measures the "more" button if it's in the DOM.
-   */
-  const measureElementSizes = () => {
-    if (!containerRef.value) return;
-
-    // Update container gap
-    containerGap.value = readContainerGap(containerRef.value);
-
-    // Measure the "more" button if present
-    measureMoreButton();
-
-    const elements = containerRef.value.querySelectorAll("[data-item-key]");
-
-    elements.forEach((element) => {
-      const key = element.getAttribute("data-item-key");
-      if (key) {
-        const width = measureNaturalWidth(element as HTMLElement);
-        if (width > 0) {
-          itemSizes.value.set(key, width);
-        }
-      }
-    });
-
-    calculateVisibleItems();
-  };
-
-  /**
-   * Remove stale entries from the size cache when items are removed.
-   */
-  const cleanupSizeCache = () => {
-    const currentKeys = new Set(items.value.map(getItemKey));
-    for (const key of itemSizes.value.keys()) {
-      if (!currentKeys.has(key)) {
-        itemSizes.value.delete(key);
-      }
-    }
-  };
-
-  /**
-   * Setup ResizeObserver: observe current elements, unobserve removed ones.
-   * Uses a single persistent observer instance.
-   */
-  const setupElementsObserver = () => {
-    // Create observer lazily on first call
-    if (!elementsObserver) {
-      elementsObserver = new ResizeObserver((entries) => {
-        // Avoid DOM mutations inside ResizeObserver callback to prevent re-entry loops.
-        // Visible items should already be at natural width after calculateVisibleItems,
-        // so reading offsetWidth directly is safe here.
-        let hasChanges = false;
-
-        for (const entry of entries) {
-          const element = entry.target as HTMLElement;
-          if (!element.isConnected) continue;
-
-          const key = element.getAttribute("data-item-key");
-          if (!key) continue;
-
-          // Use borderBoxSize from the entry when available (avoids forced reflow),
-          // otherwise fall back to offsetWidth + margins.
-          const styles = getComputedStyle(element);
-          const borderBoxWidth = entry.borderBoxSize?.[0]?.inlineSize;
-          const baseWidth = borderBoxWidth != null ? borderBoxWidth : element.offsetWidth;
-          const width =
-            baseWidth + parseFloat(styles.marginLeft || "0") + parseFloat(styles.marginRight || "0");
-
-          if (width > 0 && itemSizes.value.get(key) !== width) {
-            itemSizes.value.set(key, width);
-            hasChanges = true;
-          }
-        }
-
-        if (hasChanges) {
-          calculateVisibleItems();
-        }
-      });
-    }
-
-    nextTick(() => {
-      if (!containerRef.value) return;
-
-      const elements = containerRef.value.querySelectorAll("[data-item-key]");
-      const newElements = new Set<Element>();
-
-      // Observe new elements
-      elements.forEach((element) => {
-        newElements.add(element);
-        if (!observedElements.has(element)) {
-          elementsObserver?.observe(element);
-          observedElements.add(element);
-        }
-      });
-
-      // Unobserve removed elements
-      for (const element of observedElements) {
-        if (!newElements.has(element)) {
-          elementsObserver?.unobserve(element);
-          observedElements.delete(element);
-        }
-      }
-
-      // Measure all current elements
-      measureElementSizes();
-    });
-  };
-
-  // Debounced recalculation for container width changes (avoid per-pixel recalcs during animation)
-  const debouncedCalculate = useDebounceFn(() => {
-    // Re-read gap in case container layout changed
-    if (containerRef.value) {
-      containerGap.value = readContainerGap(containerRef.value);
-    }
-    calculateVisibleItems();
-  }, 50);
-
-  // Recalculate when container width changes
-  watch(containerWidth, () => {
-    debouncedCalculate();
-  });
-
-  // When "more" button appears/disappears, measure it on the next tick
-  watch(showMoreButton, (visible) => {
-    if (visible) {
-      nextTick(() => {
-        const prevWidth = measuredMoreWidth.value;
-        measureMoreButton();
-        // If measured width differs from what we used, recalculate
-        if (measuredMoreWidth.value !== null && measuredMoreWidth.value !== prevWidth) {
-          calculateVisibleItems();
-        }
-      });
-    }
-  });
-
-  // Shallow watch: react to item count / identity changes, not deep property changes
-  watch(
-    () => items.value.map(getItemKey).join("\0"),
-    () => {
-      cleanupSizeCache();
-      nextTick(() => {
-        setupElementsObserver();
-      });
-    },
-  );
-
-  // Initialize when mounted
-  onMounted(() => {
-    nextTick(() => {
-      measureElementSizes();
-      setupElementsObserver();
-    });
-  });
-
-  // Cleanup resources when unmounted
-  onBeforeUnmount(() => {
-    if (elementsObserver) {
-      elementsObserver.disconnect();
-      elementsObserver = null;
-    }
-    observedElements.clear();
-  });
-
-  return {
-    visibleItems,
-    hiddenItems,
-    showMoreButton,
-    recalculate: () => {
-      nextTick(() => {
-        measureElementSizes();
-      });
-    },
-    // Export function for updating observer
-    updateObserver: setupElementsObserver,
-  };
-}

package/ui/composables/useCollapsible.ts

@@ -1,73 +0,0 @@
-import { ref, computed, watch, type Ref, type CSSProperties } from "vue";
-import { useResizeObserver } from "@vueuse/core";
-
-export interface UseCollapsibleOptions {
-  /** Height in px when collapsed. Default: 0 (fully hidden) */
-  collapsedHeight?: number;
-  /** Max height in px when expanded. Undefined = no limit */
-  maxExpandedHeight?: number;
-  /** Initial expanded state. Default: false */
-  expanded?: boolean;
-}
-
-export interface UseCollapsibleReturn {
-  /** Template ref — attach to the inner content element */
-  contentRef: Ref<HTMLElement | undefined>;
-  /** Whether the panel is currently expanded */
-  isExpanded: Ref<boolean>;
-  /** True when content overflows the collapsed height (i.e. expand is meaningful) */
-  hasOverflow: Readonly<Ref<boolean>>;
-  /** True when expanded content exceeds maxExpandedHeight (needs scroll) */
-  hasScroll: Readonly<Ref<boolean>>;
-  /** Bind to the wrapper element's :style */
-  wrapperStyle: Readonly<Ref<CSSProperties>>;
-  /** Measured content height in px */
-  contentHeight: Readonly<Ref<number>>;
-  /** Toggle expanded state */
-  toggle: () => void;
-}
-
-export function useCollapsible(options: UseCollapsibleOptions = {}): UseCollapsibleReturn {
-  const collapsedHeight = options.collapsedHeight ?? 0;
-  const maxExpandedHeight = options.maxExpandedHeight;
-
-  const contentRef = ref<HTMLElement>();
-  const contentHeight = ref(0);
-  const isExpanded = ref(options.expanded ?? false);
-
-  const hasOverflow = computed(() => contentHeight.value > collapsedHeight);
-
-  const hasScroll = computed(
-    () => maxExpandedHeight !== undefined && contentHeight.value > maxExpandedHeight,
-  );
-
-  const wrapperStyle = computed<CSSProperties>(() => {
-    if (isExpanded.value) {
-      if (maxExpandedHeight !== undefined && contentHeight.value > maxExpandedHeight) {
-        return { maxHeight: `${maxExpandedHeight}px` };
-      }
-      return { maxHeight: `${contentHeight.value}px` };
-    }
-    return { maxHeight: collapsedHeight > 0 ? `${collapsedHeight}px` : "0px" };
-  });
-
-  function toggle() {
-    isExpanded.value = !isExpanded.value;
-  }
-
-  useResizeObserver(contentRef, () => {
-    if (contentRef.value) {
-      contentHeight.value = contentRef.value.scrollHeight;
-    }
-  });
-
-  return {
-    contentRef,
-    isExpanded,
-    hasOverflow,
-    hasScroll,
-    wrapperStyle,
-    contentHeight,
-    toggle,
-  };
-}

package/ui/composables/useFloatingPosition.ts

@@ -1,94 +0,0 @@
-import {
-  autoUpdate,
-  flip,
-  offset as floatingOffset,
-  shift,
-  useFloating,
-  type Middleware,
-  type Placement,
-  type Strategy,
-} from "@floating-ui/vue";
-import { computed, toValue, type MaybeRefOrGetter, type Ref } from "vue";
-
-export interface FloatingOffset {
-  mainAxis?: number;
-  crossAxis?: number;
-  alignmentAxis?: number;
-}
-
-export interface UseFloatingPositionOptions {
-  placement?: MaybeRefOrGetter<Placement>;
-  strategy?: MaybeRefOrGetter<Strategy>;
-  offset?: MaybeRefOrGetter<FloatingOffset | number | undefined>;
-  middleware?: MaybeRefOrGetter<Middleware[] | undefined>;
-  enableFlip?: MaybeRefOrGetter<boolean>;
-  enableShift?: MaybeRefOrGetter<boolean>;
-  autoUpdate?: MaybeRefOrGetter<boolean>;
-  shiftPadding?: number;
-}
-
-/**
- * Shared floating-ui adapter with reactive placement/offset defaults.
- */
-export function useFloatingPosition(
-  referenceEl: Ref<HTMLElement | null>,
-  floatingEl: Ref<HTMLElement | null>,
-  options: UseFloatingPositionOptions = {},
-) {
-  const resolvedPlacement = computed<Placement>(() => toValue(options.placement) ?? "bottom");
-  const resolvedStrategy = computed<Strategy>(() => toValue(options.strategy) ?? "absolute");
-
-  const resolvedMiddleware = computed<Middleware[]>(() => {
-    const explicitMiddleware = toValue(options.middleware);
-
-    if (explicitMiddleware?.length) {
-      return explicitMiddleware;
-    }
-
-    const middleware: Middleware[] = [];
-
-    if (toValue(options.enableFlip) !== false) {
-      middleware.push(flip({ padding: options.shiftPadding ?? 8 }));
-    }
-
-    if (toValue(options.enableShift) !== false) {
-      middleware.push(shift({ padding: options.shiftPadding ?? 8 }));
-    }
-
-    const offsetValue = toValue(options.offset);
-
-    if (typeof offsetValue === "number") {
-      middleware.push(floatingOffset(offsetValue));
-    } else {
-      middleware.push(
-        floatingOffset({
-          mainAxis: offsetValue?.mainAxis ?? 0,
-          crossAxis: offsetValue?.crossAxis ?? 0,
-          alignmentAxis: offsetValue?.alignmentAxis,
-        }),
-      );
-    }
-
-    return middleware;
-  });
-
-  const floating = useFloating(referenceEl, floatingEl, {
-    placement: resolvedPlacement,
-    strategy: resolvedStrategy,
-    whileElementsMounted: toValue(options.autoUpdate) === false ? undefined : autoUpdate,
-    middleware: resolvedMiddleware,
-  });
-
-  const floatingStyle = computed(() => ({
-    position: resolvedStrategy.value,
-    top: `${floating.y.value ?? 0}px`,
-    left: `${floating.x.value ?? 0}px`,
-  }));
-
-  return {
-    ...floating,
-    floatingStyle,
-    resolvedPlacement,
-    resolvedStrategy,
-  };
-}