nuxt-ui-tools 1.17.0 → 1.18.0

package/dist/runtime/table/types/data-list.d.ts

@@ -6,6 +6,7 @@ import type { PaginationProps } from '@nuxt/ui/components/Pagination.vue';
 import type { SelectProps } from '@nuxt/ui/components/Select.vue';
 import type { ComputedRef } from 'vue';
 import type { TableInternals } from '../composables/use-table-internals.js';
+import type { TableEmptySchema } from './layout.js';
 import type { TableLayout } from './utils.js';
 export interface DataListTable {
     schema: ComputedRef<{
@@ -211,6 +212,14 @@ export interface DataListLayoutSwitchUi {
     triggerLeadingIcon?: DataListUiClass;
     triggerTrailingIcon?: DataListUiClass;
 }
+/** UI slots rendered by the summary/table toggle. */
+export interface DataListViewToggleUi {
+    [slot: string]: DataListUiClass | undefined;
+    base?: DataListUiClass;
+    label?: DataListUiClass;
+    leadingIcon?: DataListUiClass;
+    trailingIcon?: DataListUiClass;
+}
 /** UI slots rendered by the content state boundary. */
 export interface DataListContentUi {
     root?: DataListUiClass;
@@ -244,6 +253,35 @@ export interface DataListTableUi {
     loading?: DataListUiClass;
     loadingOverlay?: DataListUiClass;
     emptyOverlay?: DataListUiClass;
+    /** The empty state's button: the reset of a filtered list and the first-use `empty.action`. */
+    emptyAction?: DataListUiClass;
+    /** The row-actions button at the end of each row, in the table and in summary rows. */
+    rowAction?: DataListUiClass;
+    /** The tap area around a selection checkbox, a row's or the select-all one, in the table and in summary rows. */
+    selectControl?: DataListUiClass;
+}
+/** UI slots rendered by summary rows, the compact presentation of the table layout. */
+export interface DataListSummaryUi {
+    root?: DataListUiClass;
+    viewport?: DataListUiClass;
+    /** The select-all strip above the rows, present when the list has selection. */
+    header?: DataListUiClass;
+    list?: DataListUiClass;
+    row?: DataListUiClass;
+    /** The checkbox cell of a row and of the select-all strip. */
+    select?: DataListUiClass;
+    /** The tappable part of a row: everything between the checkbox and the actions. */
+    main?: DataListUiClass;
+    leading?: DataListUiClass;
+    body?: DataListUiClass;
+    title?: DataListUiClass;
+    /** The line under the title, holding the status and the details. */
+    meta?: DataListUiClass;
+    status?: DataListUiClass;
+    details?: DataListUiClass;
+    actions?: DataListUiClass;
+    skeleton?: DataListUiClass;
+    loadingMore?: DataListUiClass;
 }
 /** UI slots rendered by the grid mode and its built-in states. */
 export interface DataListGridUi {
@@ -356,16 +394,19 @@ export interface DataListLayoutSwitchProps {
     /** Icons per layout; defaults to list and box icons. */
     icons?: Partial<Record<TableLayout, string>>;
 }
-/** Component props exposed by the table renderer controls. */
+/** Component props exposed by the summary/table toggle. */
+export interface DataListViewToggleProps {
+    button?: DataListButtonProps;
+}
+/** Component props exposed by the table renderer controls, shared by summary rows. */
 export interface DataListTableProps {
     checkbox?: DataListCheckboxProps;
     rowActions?: DataListButtonProps;
-    /** Empty state copy; `description: false` hides the second line. */
-    empty?: {
-        icon?: string;
-        title?: string;
-        description?: string | false;
-    };
+    /**
+     * Empty state copy and first-use action shared by every list. A list's own `empty` schema
+     * field wins, field by field. `description: false` hides the second line.
+     */
+    empty?: TableEmptySchema;
 }
 /** Component props exposed by offset pagination. */
 export interface DataListPaginationProps {
@@ -432,13 +473,22 @@ export interface DataListUiConfig {
     columnPanel?: DataListPartConfig<DataListColumnPanelUi, DataListColumnPanelProps>;
     sortMenu?: DataListPartConfig<DataListSortMenuUi, DataListSortMenuProps>;
     layoutSwitch?: DataListPartConfig<DataListLayoutSwitchUi, DataListLayoutSwitchProps>;
+    viewToggle?: DataListPartConfig<DataListViewToggleUi, DataListViewToggleProps>;
     content?: DataListPartConfig<DataListContentUi>;
     table?: DataListTableConfig;
+    summary?: DataListPartConfig<DataListSummaryUi>;
     grid?: DataListGridConfig;
     pagination?: DataListPartConfig<DataListPaginationUi, DataListPaginationProps>;
     infiniteLoader?: DataListPartConfig<DataListInfiniteLoaderUi, DataListInfiniteLoaderProps>;
     selectionActions?: DataListPartConfig<DataListSelectionActionsUi, DataListSelectionActionsProps>;
-    /** Overrides merged on top of this config while the viewport is below the `md` breakpoint. */
+    /**
+     * Overrides merged on top of this config while the viewport is below the `md` breakpoint.
+     *
+     * Below `md` the package also adds a 44px touch target (`min-h-11 min-w-11` and alike) to the
+     * controls a thumb reaches, under the classes of each `ui` slot: yours add to them and win only
+     * where they conflict. To shrink a control back, state the conflicting utilities, for example
+     * `min-h-0 min-w-0`.
+     */
     mobile?: Omit<DataListUiConfig, 'mobile'>;
 }
 export interface DataListGridConfig extends DataListPartConfig<DataListGridUi> {

package/dist/runtime/table/types/layout.d.ts

@@ -1,3 +1,5 @@
+import type { ButtonProps } from '@nuxt/ui/components/Button.vue';
+import type { LinkProps } from '@nuxt/ui/components/Link.vue';
 import type { TableColumnCollection, TableSummaryRequest, TableSummaryScope, TableSummaryValue } from './columns.js';
 import type { TableTreeSchema } from './tree.js';
 import type { GenericObject, TableDefaultSort, TableGridSortOption, TableLayout, TableRowRenderParams, RenderableType, TableSortKey, TableTextValue } from './utils.js';
@@ -5,6 +7,27 @@ export interface TablePersistenceOptions {
     state?: boolean;
     preferences?: boolean;
 }
+/**
+ * The button of a first-use empty state. Any Nuxt UI button prop applies; `label` may be lazy so
+ * it follows the locale.
+ */
+export interface TableEmptyAction extends Omit<ButtonProps, 'ui' | 'label'> {
+    label: TableTextValue;
+    /** Runs on click. Use `to` instead to navigate. */
+    onClick?: (event: MouseEvent) => void;
+}
+/**
+ * What a list shows when it has no records at all. Anything left out keeps the localized default.
+ * A list hidden by filters or a search always offers to reset them instead, never `action`.
+ */
+export interface TableEmptySchema {
+    icon?: string;
+    title?: TableTextValue;
+    /** `false` hides the second line. */
+    description?: TableTextValue | false;
+    /** The first thing to do in an empty list, such as creating the first record. */
+    action?: TableEmptyAction;
+}
 export type TableLayoutControl<TLayout extends TableLayout = TableLayout> = boolean | string | Partial<Record<TLayout, boolean | string>> | (() => boolean | string | Partial<Record<TLayout, boolean | string>>);
 export interface TableControlsSchema {
     refresh?: TableLayoutControl;
@@ -13,6 +36,8 @@ export interface TableControlsSchema {
     filters?: TableLayoutControl;
     sort?: TableLayoutControl;
     actions?: TableLayoutControl;
+    /** The toggle between summary rows and the full table, offered while `table.summary` is active. */
+    summary?: TableLayoutControl;
 }
 export interface TableSelectionSchema {
     mode?: false | true | 'auto';
@@ -59,6 +84,54 @@ export interface TableTableSchema<TRow extends GenericObject = GenericObject, TC
     defaultSorting?: TableDefaultSort<TSortKey>;
     selection?: boolean | 'auto';
     summaries?: TableSummariesSchema<TRow>;
+    /**
+     * Reads each record as one compact row instead of a line of columns, the way a phone screen
+     * needs it. Off until configured; see `TableRowSummarySchema` for when it applies.
+     */
+    summary?: TableRowSummarySchema<TRow, TContext, TPageContext>;
+}
+/** One value of a summary row's detail line. Empty values are skipped. */
+export type TableRowSummaryValue = string | number | null | undefined | false;
+/**
+ * A record as one summary row: an identity, one status, a couple of useful values and the row
+ * actions. Every callback receives the params a grid card gets, with `layout: 'table'`.
+ *
+ * Summary rows replace the column table, so columns, column sorting and the totals row are not
+ * shown while they are active. Filters, search, selection, row actions and pagination work as in
+ * the table, and a toggle brings the full table back.
+ *
+ * @example
+ * summary: {
+ *   leading: ({ row }) => h(UAvatar, { text: initials(row.name), size: 'md' }),
+ *   title: ({ row }) => row.name,
+ *   status: ({ row }) => h(UBadge, { label: STATUS[row.status], variant: 'subtle' }),
+ *   details: ({ row }) => [row.kind, row.city],
+ *   to: ({ row }) => `/accounts/${row.id}`,
+ * }
+ */
+export interface TableRowSummarySchema<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TPageContext extends GenericObject = GenericObject> {
+    /**
+     * Where summary rows replace the column table: `true`, `false`, a responsive string, or a
+     * getter returning either. The reader can still switch to the table from the toggle.
+     * @default 'true md:false' Summary rows below the `md` breakpoint, the table from `md` up.
+     * @example 'true lg:false' // summary rows on tablets too
+     */
+    enabled?: boolean | string | (() => boolean | string);
+    /** The record's identity. One line, cut with an ellipsis when it does not fit. */
+    title: (params: TableRowRenderParams<TRow, TContext, TPageContext>) => string | number;
+    /**
+     * A 32px tile before the title: an avatar, an icon, initials. It is clipped to a rounded
+     * square, so pass an element that fills it.
+     */
+    leading?: (params: TableRowRenderParams<TRow, TContext, TPageContext>) => RenderableType;
+    /** One status pill, first on the line under the title. */
+    status?: (params: TableRowRenderParams<TRow, TContext, TPageContext>) => RenderableType;
+    /** The two or so values worth reading without opening the record, joined with " · ". */
+    details?: (params: TableRowRenderParams<TRow, TContext, TPageContext>) => TableRowSummaryValue[];
+    /** Makes the row a link to the record. Return `undefined` for a row that is not one. */
+    to?: (params: TableRowRenderParams<TRow, TContext, TPageContext>) => LinkProps['to'] | undefined;
+    /** Runs when the row is tapped. With `to`, it runs before the navigation. */
+    onSelect?: (params: TableRowRenderParams<TRow, TContext, TPageContext>) => void;
 }
 export interface TableSummariesSchema<TRow extends GenericObject = GenericObject> {
     /** Rows the aggregates describe; defaults to `filtered`. */

package/dist/runtime/table/types/schema.d.ts

@@ -1,14 +1,22 @@
 import type { TableBulkAction, TableRowAction, TableToolbarAction } from './actions.js';
 import type { TableContextDataFromItems, TableContextItem, TablePageContextItem } from './context.js';
 import type { TableFiltersSchema } from './filters.js';
-import type { TableControlsSchema, TableGridSchema, TablePaginationSchema, TablePersistenceOptions, TableSelectionSchema, TableTableSchema } from './layout.js';
+import type { TableControlsSchema, TableEmptySchema, TableGridSchema, TablePaginationSchema, TablePersistenceOptions, TableSelectionSchema, TableTableSchema } from './layout.js';
 import type { InferTableSourceRow, ExtractTableSourceResult, NormalizeTableSource, TableCursorPageResult, TableSource, TableSourceExecutionResult } from './source.js';
 import type { TableKnownFieldPath, TableLayout, TableRowKey, TableSortKey, GenericObject } from './utils.js';
 export interface TableSchema<TRow extends GenericObject = GenericObject, TContextItems extends TableContextItem[] = TableContextItem[], TPageContextItems extends TablePageContextItem<TRow, TableContextDataFromItems<TContextItems>>[] = TablePageContextItem<TRow, TableContextDataFromItems<TContextItems>>[], TFilterKey extends string = TableKnownFieldPath<TRow>, TSortKey extends string = TableSortKey<TRow>> {
     tableKey: string;
     rowKey: TableRowKey<TRow>;
     source: TableSource<TRow, TableContextDataFromItems<TContextItems>, TRow[] | TableSourceExecutionResult<TRow> | TableCursorPageResult<TRow>>;
+    /**
+     * Names a record for assistive technology, in "Select {label}" and "Actions for {label}".
+     * Without it the controls name the row by its position on the page.
+     * @example (row) => row.name
+     */
+    rowLabel?: (row: TRow) => string | number | null | undefined;
     defaultLayout?: TableLayout;
+    /** What the list shows while it has no records at all. See `TableEmptySchema`. */
+    empty?: TableEmptySchema;
     pagination?: TablePaginationSchema;
     context?: TContextItems;
     pageContext?: TPageContextItems;

package/dist/runtime/table/types/source.d.ts

@@ -5,10 +5,15 @@ import type { GenericObject, TableKnownFieldPath, TablePaginationState, TableSor
 /** Table name of the shared `QueryDefinition`, kept for public type compatibility. */
 export type TableQueryDefinition<TData = unknown> = QueryDefinition<TData>;
 /**
- * Result of a query definition: what its `queryFn` resolves to, or the data type of TanStack
+ * Result of a query definition: what the table actually receives.
+ *
+ * A `select` wins, because TanStack hands its return value to the consumer in place of the
+ * fetched data. Without one it is what the `queryFn` resolves to, or the data type of TanStack
  * options whose `queryFn` may be a ref or `skipToken` (Tuyau's `queryOptions()`).
  */
 export type TableSourceQueryResult<TQuery> = TQuery extends {
+    select: (...args: never[]) => infer TSelected;
+} ? Awaited<TSelected> : TQuery extends {
     queryFn: (...args: never[]) => infer TResult;
 } ? Awaited<TResult> : TQuery extends UseQueryOptions<infer _TQueryFnData, infer _TError, infer TResult, infer _TQueryData, infer _TQueryKey> ? Awaited<TResult> : never;
 /** Row of a table query result: an array of rows, or a page (`{ rows }`). */

package/dist/runtime/table/types/table-api.d.ts

@@ -103,6 +103,18 @@ export interface TableApi<TSchema = TableSchemaView> {
         }>;
         set: (layout: TableLayout) => void;
     };
+    /**
+     * Summary rows, the compact presentation of the table layout. With no `table.summary` in the
+     * schema, or where it is not enabled, `state.available` is `false` and `set` has no effect.
+     */
+    summary: {
+        state: ComputedRef<{
+            active: boolean;
+            available: boolean;
+        }>;
+        /** Shows the summary rows (`true`) or the full table (`false`), and remembers the choice. */
+        set: (active: boolean) => void;
+    };
     filters: {
         state: ComputedRef<TableFilterState>;
         search: WritableComputedRef<string>;

package/dist/runtime/table/utils/columns/defs.js

@@ -48,7 +48,9 @@ export function createColumnDefs(options) {
         canHide: false,
         internal: "selection",
         label: "",
-        render: ({ row, index }) => selection.cell({ row: { id: options.params.selection.getRowId({ index, row }) } }),
+        render: ({ row, index }) => selection.cell({
+          row: { id: options.params.selection.getRowId({ index, row }), index, original: row }
+        }),
         renderHeader: () => selection.header(),
         sortable: false
       },

package/dist/runtime/table/utils/columns/render.d.ts

@@ -9,6 +9,8 @@ export declare function createSelectionColumn(options: {
     cell: ({ row }: {
         row: {
             id: string;
+            original: GenericObject;
+            index: number;
         };
     }) => import("vue/jsx-runtime").JSX.Element;
     enableHiding: boolean;

package/dist/runtime/table/utils/columns/render.js

@@ -29,7 +29,8 @@ export function createSelectionColumn(options) {
         TableSelectionControl,
         {
           modelValue: options.params.selection.isRowSelected({ rowId }),
-          ariaLabel: "Select row",
+          row: row.original,
+          index: row.index,
           onToggle: (event) => options.params.selection.toggleRowSelection({
             rowId,
             selected: !options.params.selection.isRowSelected({ rowId }),
@@ -46,7 +47,6 @@ export function createSelectionColumn(options) {
       TableSelectionControl,
       {
         modelValue: options.params.selection.allSelected.value ? true : options.params.selection.partiallySelected.value ? "indeterminate" : false,
-        ariaLabel: "Select all rows",
         onToggle: () => options.params.selection.toggleAllRows({
           selected: !options.params.selection.allSelected.value
         })

package/dist/runtime/table/utils/data-list-ui.js

@@ -205,7 +205,9 @@ export function mergeDataListUiConfig(appUi, componentUi, density, size) {
     search: mergeSearchConfig(appUi?.search, componentUi?.search),
     selectionActions: mergePartConfig(appUi?.selectionActions, componentUi?.selectionActions),
     sortMenu: mergePartConfig(appUi?.sortMenu, componentUi?.sortMenu),
-    table: mergeUiConfig(appUi?.table, componentUi?.table)
+    summary: mergeUiConfig(appUi?.summary, componentUi?.summary),
+    table: mergeUiConfig(appUi?.table, componentUi?.table),
+    viewToggle: mergePartConfig(appUi?.viewToggle, componentUi?.viewToggle)
   };
 }
 function mergeUiConfig(appDefaults, componentConfig) {

package/dist/runtime/table/utils/mobile-defaults.d.ts

@@ -0,0 +1,7 @@
+import type { DataListUiConfig } from '../types/index.js';
+/**
+ * Adds the package's mobile defaults to a config: a 44px touch target on every control a thumb
+ * reaches. Their classes go under the classes each slot already has, so an app's own slot classes
+ * are kept and win wherever they conflict.
+ */
+export declare function layerDataListMobileDefaults(config: DataListUiConfig): DataListUiConfig;

package/dist/runtime/table/utils/mobile-defaults.js

@@ -0,0 +1,25 @@
+import { isObject, isString } from "../../shared/utils/predicate.js";
+import { DATA_LIST_MOBILE_DEFAULTS } from "../constants/mobile.js";
+import { mergeDataListUiClass } from "./data-list-ui.js";
+function isClassEntry(entry) {
+  return isString(entry[1]);
+}
+function readPart(config, name) {
+  const part = new Map(Object.entries(config)).get(name);
+  return isObject(part) ? part : {};
+}
+function layerPart(config, name, defaults) {
+  const own = readPart(config, name);
+  const ui = isObject(own.ui) ? own.ui : {};
+  const classes = new Map(Object.entries(ui).filter(isClassEntry));
+  const added = Object.entries(defaults).filter(isClassEntry).map(
+    ([slot, base]) => [slot, mergeDataListUiClass(base, void 0, classes.get(slot))]
+  );
+  return { ...own, ui: { ...ui, ...Object.fromEntries(added) } };
+}
+export function layerDataListMobileDefaults(config) {
+  const layered = Object.entries(DATA_LIST_MOBILE_DEFAULTS).map(
+    ([name, defaults]) => [name, layerPart(config, name, defaults.ui)]
+  );
+  return Object.assign({}, config, Object.fromEntries(layered));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Nuxt module and runtime toolkit for UI-heavy Nuxt applications",
   "homepage": "https://github.com/ChronicStone/nuxt-ui-tools#readme",
   "bugs": "https://github.com/ChronicStone/nuxt-ui-tools/issues",