@vc-shell/framework 1.2.4-beta.5 → 1.2.4-beta.7

package/ui/components/organisms/vc-table/VcTableAdapter.vue

@@ -9,7 +9,7 @@
       :selection="internalSelection"
       :is-row-selectable="rowSelectable"
       :row-actions="effectiveRowActions"
-      :row-class="rowClassWithHighlight"
+      :active-item-id="selectedItemId ? toValue(selectedItemId) : undefined"
       :loading="loadingValue"
       :resizable-columns="props.resizableColumns"
       :reorderable-columns="props.reorderableColumns"
@@ -28,6 +28,8 @@
       :pagination="paginationConfig"
       :add-row="addRowConfig"
       :variant="props.variant"
+      :empty-state="mappedEmptyState"
+      :not-found-state="mappedNotFoundState"
       @sort="handleSort"
       @update:selection="handleSelectionUpdate"
       @row-click="handleRowClick"
@@ -107,52 +109,12 @@
         />
       </template>
 
-      <!-- Empty / NotFound -->
-      <template #empty>
-        <template v-if="isNotFoundState && ($slots.notfound || props.notfound)">
-          <slot name="notfound">
-            <div
-              v-if="props.notfound"
-              class="vc-table-adapter__empty-state"
-            >
-              <VcIcon
-                v-if="props.notfound.icon"
-                :icon="props.notfound.icon"
-                size="xxl"
-              />
-              <p class="vc-table-adapter__empty-text">{{ toValue(props.notfound.text) }}</p>
-              <a
-                v-if="props.notfound.action"
-                class="vc-table-adapter__empty-action"
-                @click="props.notfound.clickHandler?.()"
-              >
-                {{ toValue(props.notfound.action) }}
-              </a>
-            </div>
-          </slot>
-        </template>
-        <template v-else>
-          <slot name="empty">
-            <div
-              v-if="props.empty"
-              class="vc-table-adapter__empty-state"
-            >
-              <VcIcon
-                v-if="props.empty.icon"
-                :icon="props.empty.icon"
-                size="xxl"
-              />
-              <p class="vc-table-adapter__empty-text">{{ toValue(props.empty.text) }}</p>
-              <a
-                v-if="props.empty.action"
-                class="vc-table-adapter__empty-action"
-                @click="props.empty.clickHandler?.()"
-              >
-                {{ toValue(props.empty.action) }}
-              </a>
-            </div>
-          </slot>
-        </template>
+      <!-- Empty / NotFound — delegate rendering to VcDataTable via props, passthrough custom slots -->
+      <template v-if="$slots.notfound" #not-found>
+        <slot name="notfound" />
+      </template>
+      <template v-if="$slots.empty" #empty>
+        <slot name="empty" />
       </template>
 
       <!-- Loading -->
@@ -200,8 +162,7 @@ import VcDataTable from "@ui/components/organisms/vc-table/VcDataTable.vue";
 import VcColumn from "@ui/components/organisms/vc-table/components/VcColumn.vue";
 import { GlobalFiltersButton } from "@ui/components/organisms/vc-table/components";
 import { VcDropdownPanel } from "@ui/components/molecules";
-import { VcIcon } from "@ui/components/atoms";
-import type { TableAction, TableEmptyAction, DataTablePagination, AddRowConfig } from "@ui/components/organisms/vc-table/types";
+import type { TableAction, TableEmptyAction, DataTablePagination, AddRowConfig, TableStateConfig } from "@ui/components/organisms/vc-table/types";
 import type { ITableColumns, IActionBuilderResult } from "@core/types";
 
 // ============================================================================
@@ -383,16 +344,6 @@ const effectiveRowActions = computed<((item: T) => TableAction<T>[]) | undefined
   return (item: T) => (props.itemActionBuilder!(item) ?? []) as TableAction<T>[];
 });
 
-// Row class: apply highlight for selectedItemId
-const rowClassWithHighlight = computed(() => {
-  const selectedId = toValue(props.selectedItemId);
-  if (!selectedId) return undefined;
-  return (data: T) => {
-    const rowId = String((data as any).id ?? "");
-    return rowId === selectedId ? "vc-data-table__row--highlighted" : "";
-  };
-});
-
 // Pagination
 const paginationConfig = computed<DataTablePagination | undefined>(() => {
   if (props.footer === false || !props.pages) return undefined;
@@ -416,6 +367,27 @@ const isNotFoundState = computed(
   () => props.items.length === 0 && (!!props.searchValue || (props.activeFilterCount ?? 0) > 0),
 );
 
+/** Map legacy TableEmptyAction → TableStateConfig for VcDataTable */
+const mappedEmptyState = computed<TableStateConfig | undefined>(() => {
+  if (!props.empty) return undefined;
+  return {
+    icon: props.empty.icon,
+    title: typeof props.empty.text === "string" ? props.empty.text : toValue(props.empty.text),
+    actionLabel: props.empty.action ? (typeof props.empty.action === "string" ? props.empty.action : toValue(props.empty.action)) : undefined,
+    actionHandler: props.empty.clickHandler,
+  };
+});
+
+const mappedNotFoundState = computed<TableStateConfig | undefined>(() => {
+  if (!props.notfound) return undefined;
+  return {
+    icon: props.notfound.icon,
+    title: typeof props.notfound.text === "string" ? props.notfound.text : toValue(props.notfound.text),
+    actionLabel: props.notfound.action ? (typeof props.notfound.action === "string" ? props.notfound.action : toValue(props.notfound.action)) : undefined,
+    actionHandler: props.notfound.clickHandler,
+  };
+});
+
 // Loading: unwrap MaybeRef
 const loadingValue = computed(() => toValue(props.loading) ?? false);
 
@@ -598,30 +570,5 @@ function handleAddRow(event: { defaults: Record<string, unknown>; cancel: () =>
 <style lang="scss">
 .vc-table-adapter {
   @apply tw-flex tw-flex-col tw-grow tw-basis-0 tw-overflow-hidden;
-
-  &__empty-state {
-    @apply tw-flex tw-flex-col tw-items-center tw-justify-center tw-py-8 tw-gap-3;
-    color: var(--neutrals-500);
-  }
-
-  &__empty-text {
-    @apply tw-text-sm tw-text-center;
-    color: var(--neutrals-600);
-  }
-
-  &__empty-action {
-    @apply tw-text-sm tw-cursor-pointer tw-underline;
-    color: var(--primary-500);
-
-    &:hover {
-      color: var(--primary-700);
-    }
-  }
-}
-
-/* Row highlight for selectedItemId support.
- * No !important — allows hover (higher specificity) to override naturally. */
-.vc-data-table__row--highlighted {
-  background-color: var(--primary-50);
 }
 </style>

package/ui/components/organisms/vc-table/base/BaseVcDataTable.ts

@@ -267,6 +267,15 @@ export const baseVcDataTableProps = {
     default: undefined,
   },
 
+  /**
+   * ID of the currently active (highlighted) row.
+   * Use v-model:activeItemId for two-way binding.
+   */
+  activeItemId: {
+    type: String,
+    default: undefined,
+  },
+
   // ============================================================================
   // COLUMN FEATURES
   // ============================================================================
@@ -499,6 +508,7 @@ export const vcDataTableEmits = [
   "filter",
 
   // Row interactions
+  "update:activeItemId",
   "row-click",
   "row-dblclick",
   "row-contextmenu",

package/ui/components/organisms/vc-table/components/DataTableBody.vue

@@ -7,8 +7,11 @@
     <template v-if="items.length === 0 && !loading">
       <slot name="empty">
         <TableEmpty
+          :icon="emptyIcon"
           :title="emptyTitle"
           :description="emptyDescription"
+          :action-label="emptyActionLabel"
+          :action-handler="emptyActionHandler"
         />
       </slot>
     </template>
@@ -141,6 +144,7 @@ export interface RowProps<T> {
   index: number;
   columns: ColumnInstance[];
   isSelected: boolean;
+  isActive: boolean;
   isSelectable: boolean;
   selectionMode?: "single" | "multiple";
   showSelectionCell: boolean;
@@ -172,6 +176,12 @@ const props = defineProps<{
   emptyTitle?: string;
   /** Empty state description */
   emptyDescription?: string;
+  /** Empty state icon */
+  emptyIcon?: string;
+  /** Empty state action button label */
+  emptyActionLabel?: string;
+  /** Empty state action button handler */
+  emptyActionHandler?: () => void;
   /** Loading text (kept for custom loading slot consumers) */
   loadingText?: string;
   /** Number of skeleton rows to show during loading */

package/ui/components/organisms/vc-table/components/DataTableRow.vue

@@ -19,6 +19,7 @@
     <TableRow
       v-if="!groupingEnabled || !expandableRowGroups || isGroupRowExpanded"
       :selected="isSelected"
+      :active="isActive"
       :reorderable="reorderable"
       :show-drag-handle="showDragHandle"
       :index="index"
@@ -154,6 +155,8 @@ const props = defineProps<{
   // === Selection ===
   /** Whether this row is selected */
   isSelected?: boolean;
+  /** Whether this row is the active (highlighted) row */
+  isActive?: boolean;
   /** Whether this row can be selected */
   isSelectable?: boolean;
   /** Selection mode: 'single' or 'multiple' */

package/ui/components/organisms/vc-table/components/TableEmpty.vue

@@ -11,28 +11,34 @@
         </div>
       </slot>
     </div>
-    <div v-if="$slots.action" class="vc-table-composition__empty-action">
-      <slot name="action" />
+    <div v-if="actionLabel || $slots.action" class="vc-table-composition__empty-action">
+      <slot name="action">
+        <VcButton
+          v-if="actionLabel"
+          variant="primary"
+          @click="actionHandler?.()"
+        >
+          {{ actionLabel }}
+        </VcButton>
+      </slot>
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
-import { VcIcon } from "@ui/components/atoms";
+import { VcIcon, VcButton } from "@ui/components/atoms";
 
 defineProps<{
-  /**
-   * Icon to display
-   */
+  /** Icon to display */
   icon?: string;
-  /**
-   * Title text
-   */
+  /** Title text */
   title?: string;
-  /**
-   * Description text
-   */
+  /** Description text */
   description?: string;
+  /** Action button label — renders VcButton when provided */
+  actionLabel?: string;
+  /** Action button click handler */
+  actionHandler?: () => void;
 }>();
 </script>
 

package/ui/components/organisms/vc-table/components/TableRow.vue

@@ -3,7 +3,7 @@
     role="row"
     class="vc-table-composition__row"
     :class="{
-      'vc-table-composition__row--selected': selected,
+      'vc-table-composition__row--selected': selected || active,
       'vc-table-composition__row--clickable': isClickable,
       'vc-table-composition__row--header': variant === 'header',
       'vc-table-composition__row--dragging': isDragging,
@@ -48,6 +48,10 @@ const props = withDefaults(
      * Whether the row is selected
      */
     selected?: boolean;
+    /**
+     * Whether the row is the active (highlighted) row — visual only, does not affect checkbox
+     */
+    active?: boolean;
     /**
      * Row variant
      */

package/ui/components/organisms/vc-table/types.ts

@@ -69,6 +69,20 @@ export interface TableEmptyAction {
   clickHandler?: () => void;
 }
 
+/** Configuration for empty/not-found state with icon, text, and optional action button */
+export interface TableStateConfig {
+  /** Icon name (e.g. "lucide-package-open", "material-shopping_cart") */
+  icon?: string;
+  /** Title text */
+  title?: string;
+  /** Description text below the title */
+  description?: string;
+  /** Action button label — renders VcButton when provided */
+  actionLabel?: string;
+  /** Action button click handler */
+  actionHandler?: () => void;
+}
+
 export type { MaybeRef } from "vue";
 
 /** Shared props for editable cell formatters (CellDefault, CellNumber, CellMoney) */
@@ -400,6 +414,8 @@ export interface VcDataTableProps<T = any> {
   rowClass?: (data: T) => string | object;
   /** Per-row function returning inline styles */
   rowStyle?: (data: T) => object;
+  /** ID of the currently active (highlighted) row — use with `v-model:activeItemId` */
+  activeItemId?: string;
   /** Visual table variant */
   variant?: "default" | "striped" | "bordered";
 
@@ -534,6 +550,12 @@ export interface VcDataTableExtendedProps<T = any> extends VcDataTableProps<T> {
    * useful when the table is narrowed (e.g. a second blade opens).
    */
   showAllColumns?: boolean;
+  /** Empty state configuration (shown when items array is empty and no search/filters are active).
+   *  Overrides default i18n title/description. Use `#empty` slot for fully custom rendering. */
+  emptyState?: TableStateConfig;
+  /** Not-found state configuration (shown when items array is empty AND search/filters are active).
+   *  Overrides default i18n title/description. Use `#not-found` slot for fully custom rendering. */
+  notFoundState?: TableStateConfig;
 }
 
 /** VcDataTable Emits — all events emitted by VcDataTable */

package/ui/components/organisms/vc-table/vc-data-table.stories.ts

@@ -495,6 +495,38 @@ export const SingleSelection: StoryFn = () => ({
   `,
 });
 
+export const ActiveItemHighlight: StoryFn = () => ({
+  components: { VcDataTable, VcColumn },
+  setup() {
+    const activeId = ref<string | undefined>(undefined);
+
+    return { products: mockProducts, activeId };
+  },
+  template: `
+    <div style="height: 400px">
+      <p class="tw-mb-2">Active row ID: {{ activeId ?? 'None' }}
+        <button class="tw-ml-2 tw-text-sm tw-underline" @click="activeId = undefined">Clear</button>
+      </p>
+      <VcDataTable
+        :items="products"
+        v-model:active-item-id="activeId"
+      >
+        <VcColumn id="name" field="name" title="Name" />
+        <VcColumn id="price" field="price" title="Price" type="money" />
+        <VcColumn id="stock" field="stock" title="Stock" type="number" />
+        <VcColumn id="status" field="status" title="Status" />
+      </VcDataTable>
+    </div>
+  `,
+});
+ActiveItemHighlight.parameters = {
+  docs: {
+    description: {
+      story: "Click a row to highlight it as active. Click again to deselect. Use `v-model:active-item-id` for two-way binding — the table automatically highlights the row matching the given ID and updates the value on row click.",
+    },
+  },
+};
+
 /**
  * VcDataTable with single selection via VcColumn (radio button style)
  */
@@ -4971,3 +5003,176 @@ SearchWithGlobalFilters.parameters = {
     },
   },
 };
+
+/**
+ * Empty state using the declarative `emptyState` prop (TableStateConfig).
+ * Shown when `items` is empty and there is no active search or filters.
+ */
+export const EmptyStateConfig: StoryFn = () => ({
+  components: { VcDataTable, VcColumn },
+  setup() {
+    const actionClicked = ref(false);
+    const emptyState = {
+      icon: "fas fa-box-open",
+      title: "No products yet",
+      description: "Your product catalog is empty. Add your first product to get started.",
+      actionLabel: "Add Product",
+      actionHandler: () => {
+        actionClicked.value = true;
+      },
+    };
+    return { products: [] as Product[], emptyState, actionClicked };
+  },
+  template: `
+    <div style="height: 400px">
+      <div v-if="actionClicked" class="tw-mb-2 tw-p-2 tw-bg-success-50 tw-rounded tw-text-sm tw-text-success-700">
+        Action button clicked!
+      </div>
+      <VcDataTable :items="products" :empty-state="emptyState">
+        <VcColumn id="name" field="name" title="Name" />
+        <VcColumn id="price" field="price" title="Price" type="money" />
+        <VcColumn id="stock" field="stock" title="Stock" type="number" />
+        <VcColumn id="status" field="status" title="Status" />
+      </VcDataTable>
+    </div>
+  `,
+});
+EmptyStateConfig.parameters = {
+  docs: {
+    description: {
+      story:
+        "Demonstrates the declarative `emptyState` prop (`TableStateConfig`) — " +
+        "icon, title, description, and an optional action button. " +
+        "Shown when `items` is an empty array and no search/filter is active.",
+    },
+  },
+};
+
+/**
+ * Not Found state using the declarative `notFoundState` prop (TableStateConfig).
+ * Shown when `items` is empty AND there is an active search or filter.
+ * The table uses `searchable` with a pre-filled search value to trigger the not-found state.
+ */
+export const NotFoundStateConfig: StoryFn = () => ({
+  components: { VcDataTable, VcColumn },
+  setup() {
+    const searchValue = ref("nonexistent product xyz");
+    const actionClicked = ref(false);
+
+    const notFoundState = {
+      icon: "fas fa-search",
+      title: "No results found",
+      description: "We couldn't find any products matching your search. Try adjusting your query.",
+      actionLabel: "Clear Search",
+      actionHandler: () => {
+        searchValue.value = "";
+        actionClicked.value = true;
+      },
+    };
+
+    const emptyState = {
+      icon: "fas fa-box-open",
+      title: "No products yet",
+      description: "Your product catalog is empty.",
+    };
+
+    return { products: [] as Product[], searchValue, notFoundState, emptyState, actionClicked };
+  },
+  template: `
+    <div style="height: 400px">
+      <div v-if="actionClicked" class="tw-mb-2 tw-p-2 tw-bg-success-50 tw-rounded tw-text-sm tw-text-success-700">
+        Search cleared! (In a real app, items would reload and show the empty state instead.)
+      </div>
+      <VcDataTable
+        :items="products"
+        searchable
+        v-model:search-value="searchValue"
+        search-placeholder="Search products..."
+        :not-found-state="notFoundState"
+        :empty-state="emptyState"
+      >
+        <VcColumn id="name" field="name" title="Name" />
+        <VcColumn id="price" field="price" title="Price" type="money" />
+        <VcColumn id="stock" field="stock" title="Stock" type="number" />
+        <VcColumn id="status" field="status" title="Status" />
+      </VcDataTable>
+    </div>
+  `,
+});
+NotFoundStateConfig.parameters = {
+  docs: {
+    description: {
+      story:
+        "Demonstrates the `notFoundState` prop — shown instead of `emptyState` when items " +
+        "is empty AND there is an active search query or filters. " +
+        "The action button clears the search. Both `emptyState` and `notFoundState` " +
+        "can be provided simultaneously — the table picks the right one based on context.",
+    },
+  },
+};
+
+/**
+ * Both empty and not-found states — interactive demo.
+ * Search to switch between the two states.
+ */
+export const EmptyVsNotFound: StoryFn = () => ({
+  components: { VcDataTable, VcColumn },
+  setup() {
+    const searchValue = ref("");
+
+    const emptyState = {
+      icon: "fas fa-box-open",
+      title: "No products yet",
+      description: "Your catalog is empty. Add your first product to get started.",
+      actionLabel: "Add Product",
+      actionHandler: () => alert("Add product clicked!"),
+    };
+
+    const notFoundState = {
+      icon: "fas fa-search",
+      title: "Nothing matches your search",
+      description: "Try a different search term or clear the search field.",
+      actionLabel: "Clear Search",
+      actionHandler: () => {
+        searchValue.value = "";
+      },
+    };
+
+    return { products: [] as Product[], searchValue, emptyState, notFoundState };
+  },
+  template: `
+    <div style="height: 450px">
+      <div class="tw-mb-4 tw-p-3 tw-bg-gradient-to-r tw-from-accent-50 tw-to-primary-50 tw-rounded-lg tw-text-sm">
+        <p class="tw-font-semibold tw-mb-1">Empty vs Not Found</p>
+        <p class="tw-text-neutrals-600">
+          Type anything in the search bar to switch from <strong>empty state</strong> to <strong>not found state</strong>.
+          Clear the search to go back to empty state.
+        </p>
+      </div>
+      <VcDataTable
+        :items="products"
+        searchable
+        v-model:search-value="searchValue"
+        search-placeholder="Type to trigger not-found state..."
+        :empty-state="emptyState"
+        :not-found-state="notFoundState"
+      >
+        <VcColumn id="name" field="name" title="Name" />
+        <VcColumn id="price" field="price" title="Price" type="money" />
+        <VcColumn id="stock" field="stock" title="Stock" type="number" />
+        <VcColumn id="status" field="status" title="Status" />
+      </VcDataTable>
+    </div>
+  `,
+});
+EmptyVsNotFound.parameters = {
+  docs: {
+    description: {
+      story:
+        "Interactive demo showing the difference between empty and not-found states. " +
+        "With an empty search field the table shows the `emptyState` config. " +
+        "Type anything in the search bar to see the `notFoundState` config instead. " +
+        "The table automatically switches between the two based on whether a search/filter is active.",
+    },
+  },
+};