@vc-shell/framework 1.2.4-beta.2 → 1.2.4-beta.3

package/ui/composables/index.ts

@@ -1,4 +1,5 @@
-export * from "./useAdaptiveItems";
-export * from "./useFloatingPosition";
-export * from "./useScrollArrows";
-export * from "./useTeleportTarget";
+export * from "@ui/composables/useAdaptiveItems";
+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,10 +1,40 @@
 import { ref, computed, onMounted, onBeforeUnmount, nextTick, type Ref, watch } from "vue";
-import { useElementSize } from "@vueuse/core";
+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;
@@ -13,28 +43,56 @@ export function useAdaptiveItems<T>(options: {
     containerRef,
     items,
     getItemKey,
-    moreButtonWidth,
+    moreButtonWidth: moreButtonFallbackWidth,
     calculationStrategy = "forward",
     initialItemWidth = 50,
   } = options;
 
-  // Size container
+  // Container width tracking
   const { width: containerWidth } = useElementSize(containerRef);
 
-  // Store element sizes by key
+  // 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);
 
-  // ResizeObserver for tracking element size changes
+  // 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
-   * If size not found, return approximate width
+   * Get element width by key.
+   * Falls back to initialItemWidth if not yet measured.
    */
   const getItemWidth = (item: T): number => {
     const key = getItemKey(item);
@@ -42,19 +100,22 @@ export function useAdaptiveItems<T>(options: {
   };
 
   /**
-   * Distribute items into visible/hidden arrays for a given available width.
+   * 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 + itemWidth <= availableWidth) {
+      if (currentWidth + gapBefore + itemWidth <= availableWidth) {
         visible.push(item);
-        currentWidth += itemWidth;
+        currentWidth += gapBefore + itemWidth;
       } else {
         hidden.push(item);
       }
@@ -64,27 +125,40 @@ export function useAdaptiveItems<T>(options: {
   };
 
   /**
-   * Calculate which elements will be visible,
-   * and which will be hidden.
+   * Calculate which elements will be visible and which will be hidden.
    *
-   * Uses a two-pass approach to avoid circular dependency:
+   * 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) {
-      result = distributeItems(itemsToCheck, containerWidth.value - moreButtonWidth);
+      const effectiveMoreWidth = getMoreButtonWidth();
+      const gapBeforeMore = result.visible.length > 0 ? gap : 0;
+      result = distributeItems(itemsToCheck, containerWidth.value - effectiveMoreWidth - gapBeforeMore);
     }
 
-    // If reverse strategy is used, reverse arrays
+    // Restore original order for reverse strategy
     if (calculationStrategy === "reverse") {
       visibleItems.value = result.visible.reverse();
       hiddenItems.value = result.hidden.reverse();
@@ -95,108 +169,156 @@ export function useAdaptiveItems<T>(options: {
   };
 
   /**
-   * Measure element widths and update size cache
+   * 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;
 
-    // Find all elements inside container with data-item-key attribute
+    // 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 htmlElement = element as HTMLElement;
-        const styles = getComputedStyle(htmlElement);
-        const width =
-          htmlElement.offsetWidth + parseFloat(styles.marginLeft || "0") + parseFloat(styles.marginRight || "0");
-
-        // Save size to cache
-        itemSizes.value.set(key, width);
+        const width = measureNaturalWidth(element as HTMLElement);
+        if (width > 0) {
+          itemSizes.value.set(key, width);
+        }
       }
     });
 
-    // Recalculate visible items with new measurements
     calculateVisibleItems();
   };
 
   /**
-   * Setup ResizeObserver for tracking element size changes
+   * Remove stale entries from the size cache when items are removed.
    */
-  const setupElementsObserver = () => {
-    if (elementsObserver) {
-      elementsObserver.disconnect();
+  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);
+      }
     }
+  };
 
-    // Create new ResizeObserver
-    elementsObserver = new ResizeObserver((entries) => {
-      // Check if sizes have changed
-      let hasChanges = false;
-
-      entries.forEach((entry) => {
-        const element = entry.target as HTMLElement;
-        const key = element.getAttribute("data-item-key");
-
-        if (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 =
-            element.offsetWidth + parseFloat(styles.marginLeft || "0") + parseFloat(styles.marginRight || "0");
+            baseWidth + parseFloat(styles.marginLeft || "0") + parseFloat(styles.marginRight || "0");
 
-          // If size has changed, update cache
-          if (itemSizes.value.get(key) !== width) {
+          if (width > 0 && itemSizes.value.get(key) !== width) {
             itemSizes.value.set(key, width);
             hasChanges = true;
           }
         }
-      });
 
-      // If there are changes, recalculate
-      if (hasChanges) {
-        calculateVisibleItems();
-      }
-    });
+        if (hasChanges) {
+          calculateVisibleItems();
+        }
+      });
+    }
 
-    // Update current measurements and setup observation
     nextTick(() => {
       if (!containerRef.value) return;
 
-      // Find all elements to observe
       const elements = containerRef.value.querySelectorAll("[data-item-key]");
+      const newElements = new Set<Element>();
 
+      // Observe new elements
       elements.forEach((element) => {
-        elementsObserver?.observe(element);
+        newElements.add(element);
+        if (!observedElements.has(element)) {
+          elementsObserver?.observe(element);
+          observedElements.add(element);
+        }
       });
 
-      // Make initial measurement
+      // 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, () => {
-    calculateVisibleItems();
+    debouncedCalculate();
   });
 
-  // Recalculate when list of items changes
+  // 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,
+    () => items.value.map(getItemKey).join("\0"),
     () => {
+      cleanupSizeCache();
       nextTick(() => {
         setupElementsObserver();
-        calculateVisibleItems();
       });
     },
-    { deep: true },
   );
 
   // Initialize when mounted
   onMounted(() => {
     nextTick(() => {
-      // Measure element sizes
       measureElementSizes();
-
-      // Setup observer for size changes
       setupElementsObserver();
     });
   });
@@ -207,6 +329,7 @@ export function useAdaptiveItems<T>(options: {
       elementsObserver.disconnect();
       elementsObserver = null;
     }
+    observedElements.clear();
   });
 
   return {
@@ -216,7 +339,6 @@ export function useAdaptiveItems<T>(options: {
     recalculate: () => {
       nextTick(() => {
         measureElementSizes();
-        calculateVisibleItems();
       });
     },
     // Export function for updating observer

package/ui/composables/useFormField.ts

@@ -0,0 +1,54 @@
+import { computed, inject, useId } from "vue";
+import type { IFormFieldProps } from "@ui/types/form-field";
+import { InputGroupContextKey } from "@ui/components/molecules/vc-input-group/context";
+
+/**
+ * Shared logic for all form field components.
+ * Handles: unique ID generation, ARIA attribute computation,
+ * InputGroupContext integration, and resolved disabled/invalid state.
+ */
+export function useFormField(props: IFormFieldProps & { hint?: string }) {
+  const groupContext = inject(InputGroupContextKey, null);
+  const uid = useId();
+
+  const fieldId = computed(() => `vc-field-${uid}`);
+  const labelId = computed(() => `${fieldId.value}-label`);
+  const errorId = computed(() => `${fieldId.value}-error`);
+  const hintId = computed(() => `${fieldId.value}-hint`);
+
+  const invalid = computed(() => !!props.error || !!props.errorMessage || !!groupContext?.invalid.value);
+
+  const resolvedDisabled = computed(() => !!props.disabled || !!groupContext?.disabled.value);
+
+  const resolvedName = computed(() => groupContext?.name.value || props.name);
+
+  const ariaDescribedBy = computed(() => {
+    const ids = new Set<string>();
+
+    if (groupContext?.describedBy.value) {
+      groupContext.describedBy.value.split(/\s+/).forEach((id) => ids.add(id));
+    }
+
+    if (props.errorMessage) {
+      ids.add(errorId.value);
+    }
+
+    if (props.hint) {
+      ids.add(hintId.value);
+    }
+
+    return ids.size ? Array.from(ids).join(" ") : undefined;
+  });
+
+  return {
+    fieldId,
+    labelId,
+    errorId,
+    hintId,
+    invalid,
+    resolvedDisabled,
+    resolvedName,
+    ariaDescribedBy,
+    groupContext,
+  };
+}

package/ui/composables/useScrollArrows.ts

@@ -1,4 +1,5 @@
-import { ref, watch, onBeforeUnmount, type Ref } from "vue";
+import { ref, onBeforeUnmount, type Ref } from "vue";
+import { useResizeObserver } from "@vueuse/core";
 
 export interface UseScrollArrowsOptions {
   /** Pixels per animation frame (~60fps). Default: 2 */
@@ -14,7 +15,6 @@ export function useScrollArrows(
   const canScrollUp = ref(false);
   const canScrollDown = ref(false);
   let scrollAnimationId: number | null = null;
-  let resizeObserver: ResizeObserver | null = null;
 
   function updateScrollState() {
     const el = viewportRef.value;
@@ -48,34 +48,10 @@ export function useScrollArrows(
     }
   }
 
-  // Observe size changes so arrows update when the viewport is resized
-  watch(
-    viewportRef,
-    (el, _oldEl, onCleanup) => {
-      resizeObserver?.disconnect();
-      resizeObserver = null;
-
-      if (!el) {
-        canScrollUp.value = false;
-        canScrollDown.value = false;
-        return;
-      }
-
-      resizeObserver = new ResizeObserver(updateScrollState);
-      resizeObserver.observe(el);
-
-      onCleanup(() => {
-        resizeObserver?.disconnect();
-        resizeObserver = null;
-      });
-    },
-    { immediate: true },
-  );
+  useResizeObserver(viewportRef, updateScrollState);
 
   onBeforeUnmount(() => {
     stopScroll();
-    resizeObserver?.disconnect();
-    resizeObserver = null;
   });
 
   return {

package/ui/composables/useTeleportTarget.ts

@@ -1,5 +1,5 @@
 import { computed, inject, type MaybeRefOrGetter, toValue } from "vue";
-import { AppRootElementKey } from "../../injection-keys";
+import { AppRootElementKey } from "@framework/injection-keys";
 
 export interface UseTeleportTargetOptions {
   to?: MaybeRefOrGetter<string | HTMLElement | null | undefined>;

package/ui/types/form-field.ts

@@ -0,0 +1,44 @@
+/**
+ * Base props shared by ALL form field components:
+ * VcCheckbox, VcSwitch, VcRadioButton, VcInput, VcTextarea,
+ * VcSelect, VcDatePicker, VcEditor, VcFileUpload, VcColorInput, etc.
+ */
+export interface IFormFieldProps {
+  /** Field label text */
+  label?: string;
+  /** Tooltip text shown on label hover */
+  tooltip?: string;
+  /** Whether the field is disabled */
+  disabled?: boolean;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Form field name attribute */
+  name?: string;
+  /** External error flag */
+  error?: boolean;
+  /** Error message text — also sets error state when truthy */
+  errorMessage?: string;
+}
+
+/**
+ * Extended props for text-input-like components:
+ * VcInput, VcTextarea, VcSelect, VcDatePicker, VcColorInput
+ */
+export interface ITextFieldProps extends IFormFieldProps {
+  /** Placeholder text */
+  placeholder?: string;
+  /** Hint text shown below the field */
+  hint?: string;
+  /** Show clear button */
+  clearable?: boolean;
+  /** Show loading indicator */
+  loading?: boolean;
+  /** Auto-focus on mount */
+  autofocus?: boolean;
+  /** Field size variant */
+  size?: "default" | "small";
+  /** Whether multilanguage mode is active */
+  multilanguage?: boolean;
+  /** Current language code for multilanguage mode */
+  currentLanguage?: string;
+}

package/ui/types/index.ts

@@ -1,5 +1,7 @@
 import { MaybeRef } from "vue";
-import * as components from "./../components";
+import * as components from "@ui/components";
+
+export type { IFormFieldProps, ITextFieldProps } from "./form-field";
 
 // Declare all components globally
 

package/core/shell-features/ai-agent.ts

@@ -1,22 +0,0 @@
-import { provideAiAgentService } from "../plugins/ai-agent";
-import type { IAiAgentConfig } from "../plugins/ai-agent";
-import type { ShellFeature } from "../types/shell-feature";
-
-/**
- * Creates an AI agent shell feature from the provided config.
- * Not included in defaultFeatures — created conditionally when aiAgentConfig is injected.
- */
-export function createAiAgentFeature(
-  config: IAiAgentConfig,
-  addGlobalToolbarButton = true,
-): ShellFeature {
-  return {
-    id: "ai-agent",
-    onSetup: () => {
-      provideAiAgentService({
-        config,
-        addGlobalToolbarButton,
-      });
-    },
-  };
-}

package/core/shell-features/index.ts

@@ -1,16 +0,0 @@
-import type { InjectionKey } from "vue";
-import { notificationsFeature } from "./notifications";
-import { settingsFeature } from "./settings";
-import type { ShellFeature } from "../types/shell-feature";
-
-export const SHELL_FEATURES_KEY: InjectionKey<ShellFeature[]> = Symbol("ShellFeatures");
-
-/**
- * Default shell features included when no custom features are provided.
- * AI agent is NOT included — it requires runtime config and is added conditionally.
- */
-export const defaultFeatures: ShellFeature[] = [notificationsFeature, settingsFeature];
-
-export { notificationsFeature, settingsFeature };
-export { createAiAgentFeature } from "./ai-agent";
-export type { ShellFeature, ShellContext } from "../types/shell-feature";

package/core/shell-features/notifications.ts

@@ -1,22 +0,0 @@
-import { NotificationDropdown } from "../../shared/components";
-import type { ShellFeature } from "../types/shell-feature";
-
-export const notificationsFeature: ShellFeature = {
-  id: "notifications",
-  appBarWidgets: [
-    {
-      id: "notification-dropdown",
-      component: NotificationDropdown,
-      icon: "lucide-bell",
-      order: 10,
-    },
-  ],
-  mobileButtons: [
-    {
-      id: "notification-dropdown",
-      component: NotificationDropdown,
-      icon: "lucide-bell",
-      order: 10,
-    },
-  ],
-};

package/core/shell-features/settings.ts

@@ -1,15 +0,0 @@
-import { LanguageSelector } from "../../shared/components/language-selector";
-import { ThemeSelector } from "../../shared/components/theme-selector";
-import { ChangePasswordButton } from "../../shared/components/change-password-button";
-import { LogoutButton } from "../../shared/components/logout-button";
-import type { ShellFeature } from "../types/shell-feature";
-
-export const settingsFeature: ShellFeature = {
-  id: "settings",
-  settingsMenuItems: [
-    { id: "theme-selector", component: ThemeSelector, order: 10 },
-    { id: "language-selector", component: LanguageSelector, order: 20 },
-    { id: "change-password", component: ChangePasswordButton, order: 30 },
-    { id: "logout", component: LogoutButton, order: 100 },
-  ],
-};