@panneau/lists 5.0.0-alpha.2 → 5.0.0-alpha.20

package/dist/ListView.d.ts

@@ -1,20 +1,38 @@
 import { type ReactNode } from 'react';
-import type { List } from '@panneau/core';
-import type { Field, Filter } from '@panneau/protocol';
-import { type ListActions } from './actions/actions';
-import type { ActionIcons } from './actions/icons';
-import type { DisplayEntry, FilterEntry, ListActionHandler, ListColumn, ListItem, ListLayoutEntry } from './types';
+import type { List, ResolvedCalendar } from '@panneau/core';
+import type { Action, Field, Filter, RuleFailure } from '@panneau/protocol';
+import { type ListActions } from './actions/actions.js';
+import type { ActionIcons } from './actions/icons.js';
+import type { DisplayEntry, FilterEntry, ListActionHandler, ListActionPreviewer, ListColumn, ListInlineEditHandler, ListItem, ListLayoutEntry } from './types.js';
 export interface ListViewProps {
     /** The list state of `@panneau/core` (`useList()`): query and selection. */
     list: List;
-    /** The items of the current page. `undefined` while they load for the first time. */
+    /**
+     * The items of the current page. `undefined` while they load for the first time: the list
+     * draws a skeleton of its rows, from its columns and its page size.
+     */
     items: readonly ListItem[] | undefined;
+    /**
+     * Every column of the list. Those with `hidden` are shown when the user chooses them, from
+     * the "Columns" menu, and the view of the list state says which ones are shown (decision 0042).
+     */
     columns: readonly ListColumn[];
+    /** Offers the user to show, hide and order the columns. Defaults to `true`. */
+    columnChoice?: boolean;
     /**
      * How many items match the query, on every page (`meta.total`). With it, the list shows
      * pagination and offers to select every matching item. Without it, `items` is the whole list.
      */
     total?: number | undefined;
+    /**
+     * The cursors of the page, for a list paged with cursors (`nextCursor` and `previousCursor`
+     * of its `meta`): the list then has buttons to the previous and next pages, without page
+     * numbers or a total, and doesn't offer to select every matching item.
+     */
+    cursors?: {
+        next: string | null;
+        previous?: string | null | undefined;
+    } | undefined;
     /** Shows that items are loading. Items already shown stay, dimmed. */
     isLoading?: boolean;
     /** An error while loading: an alert with a retry replaces the items. */
@@ -28,7 +46,7 @@ export interface ListViewProps {
     search?: boolean;
     /** Layouts to choose from, the first one being the default. Defaults to `['table']`. */
     layouts?: readonly string[];
-    /** The layout, controlled. */
+    /** The layout, controlled. Without it, the layout is the view of the list state. */
     layout?: string;
     onLayoutChange?: (layout: string) => void;
     /** Page sizes to choose from. */
@@ -42,6 +60,12 @@ export interface ListViewProps {
     actions?: ListActions;
     /** Runs an action, after its confirmation. */
     onAction?: ListActionHandler;
+    /**
+     * Asks the backend how many items of a query selection ("Select all N items") an action will
+     * skip, before the confirmation: the list only knows the abilities of the current page. Only
+     * for actions with `dryRun`. `useActionPreview()` of `@panneau/actions` is one.
+     */
+    previewAction?: ListActionPreviewer;
     /**
      * Icons of actions by action id (`{ archive: Archive }`), for actions written in code. They
      * win over the Lucide icon an action names (`"icon": "archive"`).
@@ -49,16 +73,57 @@ export interface ListViewProps {
     actionIcons?: ActionIcons;
     /** The field that titles items, for their label (`itemTitle` of the resource). */
     itemTitle?: string;
+    /**
+     * The field shown as the image of items (`itemImage` of the resource, or `media` in a media
+     * library): a media reference, a media, a file or a URL. The `gallery` layout needs it
+     * (decision 0044), and the table starts each title with its thumbnail (decision 0061).
+     */
+    itemImage?: string | undefined;
+    /**
+     * The calendar of the list (`calendar` of `resolveList()`), for its `calendar` layout. The list
+     * state asks for its month when it is given the same calendar.
+     */
+    calendar?: Pick<ResolvedCalendar, 'field' | 'filter'> | null | undefined;
+    /**
+     * The id of the main action of rows, which keeps its label while the others show their icons
+     * (decision 0060): the one the title of an item opens, `edit` for a resource that opens its
+     * items in their form. Defaults to `show` when rows have it, else `edit`.
+     */
+    primaryAction?: string | null;
     /** The label of an item, for checkboxes and actions. Defaults to its title, then its id. */
     getItemLabel?: (item: ListItem) => string;
     /** A link to an item, on its title. */
     getItemHref?: (item: ListItem) => string | null;
+    /**
+     * The link of a built-in `show` or `edit` action without a `url` or a `route` (decision 0040),
+     * which the caller resolves to its own routes. Without it, or when it answers `null`, the list
+     * leaves those links out.
+     */
+    getLinkHref?: (action: Action, item: ListItem) => string | null;
+    /**
+     * The item shown next to the list, such as in a panel of its details: its row is marked, and
+     * the link of its title is the current page.
+     */
+    currentItemId?: string | null;
     /** Displays by name, over the built-in ones and those of the plugins. */
     displays?: Readonly<Record<string, DisplayEntry>>;
     /** Layouts by id, over the built-in ones and those of the plugins. */
     layoutComponents?: Readonly<Record<string, ListLayoutEntry>>;
     /** Filter controls by filter type, over the built-in ones. */
     filterControls?: Readonly<Record<string, FilterEntry>>;
+    /**
+     * The fields that columns edit in place (`inlineEdit` of the list), on the items that can be
+     * updated, in the table (decision 0043). Needs `onInlineEdit`.
+     */
+    inlineEdit?: readonly string[];
+    /** Saves a field edited in place, and resolves with the updated item. */
+    onInlineEdit?: ListInlineEditHandler;
+    /**
+     * The message of a portable rule that a value edited in place fails. Defaults to
+     * `formatRuleFailure()` of `@panneau/core`, in English; `useFormatRuleFailure()` of
+     * `@panneau/forms` translates them.
+     */
+    formatError?: (failure: RuleFailure, path: string) => string;
     /** Content at the end of the toolbar, such as a button to create an item. */
     toolbar?: ReactNode;
     /** Shown when the list has no items, without filters or search. */
@@ -72,5 +137,5 @@ export interface ListViewProps {
  * cards), with sorting, search, filters and their chips, pagination, selection and actions. It
  * fetches nothing: the caller gives the items of the list's query and their total.
  */
-export declare function ListView({ list, items, columns, total, isLoading, error, onRetry, filters, fields, search, layouts: layoutsProp, layout: controlledLayout, onLayoutChange, perPageOptions, selectable: selectableProp, actions: actionsProp, onAction, actionIcons, itemTitle, getItemLabel: getItemLabelProp, getItemHref, displays, layoutComponents, filterControls, toolbar, emptyMessage, 'aria-label': ariaLabel, className, }: ListViewProps): import("react").JSX.Element;
+export declare function ListView({ list, items, columns: allColumns, columnChoice, total, cursors, isLoading, error, onRetry, filters: filtersProp, fields, search, layouts: layoutsProp, layout: controlledLayout, onLayoutChange, perPageOptions, selectable: selectableProp, actions: actionsProp, onAction, previewAction, actionIcons, itemTitle, itemImage, calendar, primaryAction: primaryActionProp, getItemLabel: getItemLabelProp, getItemHref, getLinkHref, currentItemId, displays, layoutComponents, filterControls, inlineEdit, onInlineEdit, formatError, toolbar, emptyMessage, 'aria-label': ariaLabel, className, }: ListViewProps): import("react").JSX.Element;
 //# sourceMappingURL=ListView.d.ts.map

package/dist/ListView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ListView.d.ts","sourceRoot":"","sources":["../src/ListView.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"ListView.d.ts","sourceRoot":"","sources":["../src/ListView.tsx"],"names":[],"mappings":"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"}