@object-ui/plugin-list 17.7.0 → 18.0.0

package/README.md

@@ -20,6 +20,15 @@ The toolbar and cell renderers are tuned for low visual noise on dense tables:
 - **Unified toolbar row**: view tabs (`schema.tabs`), user filters and tool
   buttons share a single bordered row. The previous stacked rows (`tabs` /
   `description` / `toolbar`) are collapsed into one separator line.
+- **Four tool buttons by default**: the right side of the row is Filter, Sort,
+  Display and Search. **Display** holds the rest — a Layout row (the
+  visualization switcher, when the list offers more than one), Group, Row
+  color, Hide fields, Density, a session-only Row numbers switch and an Edit
+  inline switch, with Reset to view default, Refresh and Export in its footer.
+  Its trigger counts the settings that differ from the view's own. Each
+  control saves what its own toolbar button saves; the panel stores nothing
+  of its own. A view that sets `compactToolbar: false` gets one toolbar
+  button per control instead (objectui#12423).
 - **Flat user-filter pills**: `userFilters` (dropdown mode) render as ghost
   text + count. Active state is shown via `text-foreground font-medium`
   rather than a filled / bordered pill.
@@ -108,7 +117,12 @@ import { ListView } from '@object-ui/plugin-list';
 ```
 
 When both are present, `grouping` wins. End users can also add or remove
-grouping fields at runtime via the Group toolbar button.
+grouping fields at runtime via the Group toolbar button. Every such edit, in
+the Display panel's Group section or in the wide toolbar's Group panel
+(Clear included), fires `onGroupingChange` with the spec `GroupingConfig`, or
+with `undefined` when the grouping is cleared. A changed `schema.grouping` that
+the list re-reads does not fire it: that value came from the host
+(objectui#11860).
 
 A grouped **grid** is grouped on the server: over a data source that answers
 the group header query (`dataSource.queryGroupHeaders`), `ListView` hands the
@@ -129,6 +143,11 @@ still grouped in the browser, exactly.
 
 ### With Multiple View Types
 
+Each view type's configuration is a block of that name at the top level of the
+schema: `kanban`, `calendar`, `gallery`, `timeline`, `gantt`, `map`, `chart`,
+`tree`. Each block is `@objectstack/spec`'s own list-view block, and an unknown
+key in it is refused by name.
+
 ```tsx
 import { ListView } from '@object-ui/plugin-list';
 
@@ -138,25 +157,32 @@ import { ListView } from '@object-ui/plugin-list';
     objectName: 'deals',
     viewType: 'kanban',
     columns: ['name', 'amount', 'stage', 'close_date'],
-    options: {
-      kanban: {
-        groupField: 'stage',
-        titleField: 'name',
-      },
-      calendar: {
-        startDateField: 'close_date',
-        titleField: 'name',
-      },
-      chart: {
-        chartType: 'bar',
-        xAxisField: 'stage',
-        yAxisFields: ['amount'],
-      }
-    }
+    kanban: {
+      groupByField: 'stage',
+      columns: ['name', 'amount'],
+      titleField: 'name',
+    },
+    calendar: {
+      startDateField: 'close_date',
+      titleField: 'name',
+    },
+    // A chart binds a semantic-layer dataset and selects its dimensions and
+    // measures by name (ADR-0021).
+    chart: {
+      chartType: 'bar',
+      dataset: 'deal_pipeline',
+      dimensions: ['stage'],
+      values: ['total_amount'],
+    },
   }}
 />
 ```
 
+A stored view may also carry the same blocks in a legacy `options` bag
+(`options.kanban`, …), which the platform's view write door judges key by key
+with the same block schemas. `ListView` reads it under the top-level block, which
+wins per key. Author the top-level blocks.
+
 ### With Callbacks
 
 ```tsx
@@ -172,6 +198,57 @@ import { ListView } from '@object-ui/plugin-list';
   onSearchChange={(search) => console.log('Search:', search)}
   onSortChange={(sort) => console.log('Sort:', sort)}
   onFilterChange={(filters) => console.log('Filters:', filters)}
+  onGroupingChange={(grouping) => console.log('Grouping:', grouping)}
+/>
+```
+
+### Host slot: `toolbarLeading`
+
+A host can draw its own node at the start of the list toolbar row, before the
+user-filter chips, with the `toolbarLeading` prop. The node sits in a
+`min-w-0 flex-1` wrapper, so it gets the width the right-hand controls leave.
+This is a React prop for the host app, not a schema key: list metadata cannot
+set it. Without it the toolbar row is unchanged. The console uses it to put its
+saved-view tabs on the same row as Filter, Sort, Display and Search.
+
+```tsx
+import { ListView } from '@object-ui/plugin-list';
+
+function MyViewTabs() {
+  return <nav aria-label="Views">…</nav>;
+}
+
+<ListView
+  schema={{ type: 'list-view', objectName: 'tasks', columns: ['title', 'status'] }}
+  toolbarLeading={<MyViewTabs />}
+/>
+```
+
+### Host prop: `viewDefaults`
+
+A host that stores the user's own hidden fields or density and lays that
+preference over `hiddenFields` / `rowHeight` in `schema` passes the view's own
+values in `viewDefaults`. The Display control's trigger count and its "Reset to
+view default" then compare these two settings against the view, not against
+`schema`, and the reset writes the view's values back through the doors the
+controls write through (`onHiddenFieldsChange`, `schema.onDensityChange`), so
+the stored preference follows. This is a React prop for the host app, not a
+schema key: list metadata cannot set it.
+
+When it is passed, its members are the whole baseline: an absent `hiddenFields`
+means the view hides nothing, and an absent `rowHeight` means the default
+density. Without it nothing changes: `schema` is taken as the view's own. The
+console passes it on the object list page, where it persists both settings per
+user.
+
+```tsx
+import { ListView } from '@object-ui/plugin-list';
+
+// The view hides `amount`; the user has since hidden `stage` as well.
+<ListView
+  schema={{ type: 'list-view', objectName: 'deals', hiddenFields: ['amount', 'stage'] }}
+  viewDefaults={{ hiddenFields: ['amount'] }}
+  onHiddenFieldsChange={(hidden) => console.log('Hidden:', hidden)}
 />
 ```
 
@@ -198,12 +275,11 @@ const view: ListViewSchema = {
   columns: ['title', 'status', 'assignee'],
   filters: [['status', '=', 'open']],
   sort: [{ field: 'title', order: 'asc' }],
-  options: {
-    grid: {},
-    kanban: { groupField: 'status', titleField: 'title', cardFields: ['assignee'] },
-    calendar: { startDateField: 'due_date', titleField: 'title' },
-    chart: { chartType: 'bar', xAxisField: 'status', yAxisFields: ['amount'] },
-  },
+  // One block per view type, at the top level. A grid has no block of its own:
+  // its settings are the top-level keys above.
+  kanban: { groupByField: 'status', columns: ['assignee'], titleField: 'title' },
+  calendar: { startDateField: 'due_date', titleField: 'title' },
+  chart: { chartType: 'bar', dataset: 'task_status', dimensions: ['status'], values: ['total_amount'] },
 };
 
 // `columns` also accepts ListColumn objects in place of the field-name strings.
@@ -229,6 +305,47 @@ const viewTypes: Record<NonNullable<ListViewSchema['viewType']>, string> = {
 export { view, richColumns, viewTypes };
 ```
 
+## Empty state
+
+When the `grid` or `gallery` visualization has no record to show, the view
+draws its `emptyState` (the spec's `EmptyState`): a Lucide `icon`, a `title`, a
+`message` and one `link: { label, url }` the user follows, such as the how-to
+page that explains what belongs in the list (objectui#12270). A member left out
+keeps the localized default copy; `title`, `message` and the link's `label`
+each take a string or an inline locale map, resolved against the display
+locale.
+
+The link is followed as a `type: 'url'` action through the action runner, so it
+opens what such an action opens: an in-app path (`/…` or `./…`) in place, an
+`http(s)://` address as the runner opens an external target, and `mailto:` in
+place. The runner refuses anything else at the click and reports it. The link
+is drawn beside the add-record action when the view's `addRecord` block offers
+one; the two are separate, and either, both or neither may be drawn.
+
+```typescript
+import type { ListViewSchema } from '@object-ui/types';
+
+const emptyTasks: ListViewSchema = {
+  type: 'list-view',
+  objectName: 'tasks',
+  viewType: 'grid',
+  columns: ['title'],
+  emptyState: {
+    title: 'No open tasks',
+    message: 'Tasks assigned to you appear here.',
+    icon: 'inbox',
+    link: { label: 'How tasks are assigned', url: '/docs/tasks' },
+  },
+};
+
+export { emptyTasks };
+```
+
+A list page (`interfaceConfig` of a `type: 'list'` page) may declare its own
+`emptyState` of the same shape. The page's own block wins, whole, over the one
+its source view declares, on every visualization; the source view's is the
+fallback when the page declares none.
+
 ## Page size and fetch batch
 
 A list view asks the server for one window of records. When
@@ -239,22 +356,132 @@ the view pages:
   grid's pager turns it. Its size is the default `@objectstack/spec` declares
   for `pagination.pageSize`; the list reads it from the spec rather than
   keeping a number of its own.
-- **Every other view does not page** — kanban, calendar, gallery and the rest,
-  and a grouped grid. The window is one fetch batch of **100** records, and
-  records past it are not reachable; the record-count bar says so when the
-  batch comes back full. It is a fetch size, not a page size, so it does not
-  follow the spec's display default.
+- **Every other view does not page** — kanban, gallery and the rest, and a
+  grouped grid. The window is one fetch batch of **100** records, and records
+  past it are not reachable; the record-count bar says so when the batch comes
+  back full. It is a fetch size, not a page size, so it does not follow the
+  spec's display default.
+- **The calendar view fetches the days it shows.** With a start date bound
+  (`calendar.startDateField`), the window is the calendar's visible days on
+  that field (and on `calendar.endDateField` when one is bound, so a span that
+  runs into the month is fetched), plus the records with no start date, which
+  the calendar lists as unscheduled. The list walks that window in steps of the
+  same fetch batch of 100 until it is exhausted, so every record of the month
+  is drawn, and stops at the platform's non-grid ceiling of 2,000 records with
+  a note under the calendar naming both numbers. Moving to a month the fetched
+  window does not cover fetches that month. The calendar reports the days it
+  draws through its `onVisibleRangeChange` callback (objectui#12081).
+
+A declared `pagination.pageSize` sizes the window on every view but the
+calendar, as before. With no declared size, switching between the grid view and
+another view changes the window, so the list fetches again.
+
+## On a page — `data` and `type`
+
+A `list-view` node on a page is written in `@objectstack/spec`'s list view
+spelling: `data` says where its records come from, and `type` says which kind of
+list it is. On a metadata page both sit in the node's `properties`. The node's
+own `type` stays `list-view`, because it is the key the page renderer looks the
+component up by:
 
-A declared `pagination.pageSize` sizes the window on every view, as before.
-With no declared size, switching between the grid view and another view
-changes the window, so the list fetches again.
+```json
+{
+  "type": "list-view",
+  "properties": {
+    "data": { "provider": "object", "object": "deal" },
+    "columns": ["name", "amount"],
+    "kanban": { "groupByField": "stage" }
+  }
+}
+```
+
+That node draws a grid of `deal` records: without `properties.type` the list is
+a grid, the spec's default kind. Add `"type": "kanban"` to the same `properties`
+and it draws a kanban over `deal`, grouped by `stage`. A `type` that names no
+kind this list draws is a grid too. `data` may also hand the list its rows
+(`{ "provider": "value", "items": [...] }`).
+
+A page node's own `objectName` and `viewType` are **not read**. The page
+renderer removes them before the list sees the node, and logs one warning per key
+naming what to write instead. A node that names its object only as `objectName`
+therefore names no object, and the list draws a hint in its place: "No object
+named: set data.object or dataSource.object." Converting page nodes stored in
+the old spelling is the platform's job (an ADR-0087 conversion in
+`@objectstack/spec`); this renderer does not read them back. `ListView`'s own
+React props (the `ListViewSchema` examples above) are a separate surface and
+still spell the two `objectName` and `viewType`.
+
+`objectui validate` judges a page `list-view` node in this spelling. Its record
+source is `properties.data` or a bound `dataSource.object`, and a node with
+neither is refused at `properties.data`. `objectName` and `viewType` are refused
+by name, on the node or in `properties`, each naming what to write instead
+(`properties.data`, `properties.type`). A `properties.type` that names no kind a
+list view draws is refused, and so is a list view prop such as `columns` written
+on the node itself rather than in `properties`.
+
+## On a page — `requiredPermissions`
+
+One more key of the spec's list view row acts on a page `list-view` node. It
+sits in `properties`:
+
+```json
+{
+  "type": "list-view",
+  "properties": {
+    "data": { "provider": "object", "object": "deal" },
+    "columns": ["name", "amount"],
+    "requiredPermissions": ["sales.view_pipeline"]
+  }
+}
+```
+
+**`requiredPermissions`** names the capabilities the viewer must **all** hold,
+the names permission sets grant through `systemPermissions`. It gates the node
+the way it gates the record blocks (`record:details`, `record:highlights`,
+`record:related_list`). A viewer missing one sees the notice "Insufficient
+permissions to view list." (`role="status"`) in place of the list, and no
+records are queried. An empty list, or no key, is no gate. A permission
+provider that reports no capabilities at all leaves the list shown; the server
+stays the authority. Only the page node reads this key: the object list page
+draws `ListView` itself, and the server gates the views it serves.
+
+`addRecord` draws an Add button. `position` places it: `"top"` (the toolbar),
+`"bottom"` or `"both"`. `mode` and `formView` are not read.
+
+The spec row declares `enabled` default `true` and `position` default
+`"bottom"`. The renderer does not apply those defaults: it draws the button only
+for an explicit `enabled: true`, and places an absent `position` at the top.
+objectui#13099 owns that gap; until it lands, write both keys.
+
+```json
+{
+  "type": "list-view",
+  "properties": {
+    "data": { "provider": "object", "object": "deal" },
+    "addRecord": { "enabled": true, "position": "top" }
+  }
+}
+```
+
+On a page node the click calls the `onCreate` a `RelatedRecordActionsContext`
+provider (`@object-ui/react`) serves for the listed object, resolved with
+`{ objectName }` and no `relationshipField`. The console's page host serves the
+create the object list's New opens: the record-form overlay, or the full-page
+create route for an object whose `editMode` is `page`. With no such provider,
+for a viewer who may not create, or for a create the object greys, the button
+is not drawn, rather than drawn with no action. A host that passes `ListView`'s
+own `onAddRecord` prop keeps it; the console's object list passes its header
+New's create.
+
+`sharing` does nothing on a page node yet: it draws a Share button with no
+action, because the spec declares none for it. It is not a published input.
 
 ## Page binding — `dataSource` (referencing a saved view by name)
 
-On a metadata page, a `list-view` component can bind its data through the spec's
-per-element data source (`PageComponentSchema.dataSource`,
-`ElementDataSourceSchema`) instead of spelling `objectName` and inlining the
-view's configuration:
+On a metadata page, a `list-view` component can also bind its data through the
+spec's per-element data source (`PageComponentSchema.dataSource`,
+`ElementDataSourceSchema`) instead of naming its object in `data` and inlining
+the view's configuration. A bound `dataSource.object` outranks `data`:
 
 ```json
 {
@@ -274,7 +501,8 @@ copy of a view's configuration in sync with the view itself. Both the short key
 this placement, and they beat the component's own same-named key. Values that
 come from the named view are a *baseline*: a key written on the component itself
 is more specific than the view it points at, so the component's key wins
-(an empty `columns: []` counts as "not authored"). `filter` is the exception —
+(an empty `columns: []` counts as "not authored"), and a kind written as
+`properties.type` beats the view's kind. `filter` is the exception —
 the spec calls `dataSource.filter` "additional filter criteria", so the
 component's filter, the view's filter and the binding's filter all AND together.
 A binding can narrow what the view selects, never widen it.
@@ -285,6 +513,48 @@ actual views, and issues no query. It deliberately does not fall back to the
 object's default view: that would turn a typo into a silently *wider* answer on a
 page that still looks like it works.
 
+## Compact posture in a narrow page region — `compact`
+
+`ListViewProps` has an optional host prop, `compact`. It is a React prop, not a
+schema key: nothing in `@objectstack/spec` declares a posture, and an author
+never writes one. The `list-view` page block sets it. It reads
+`usePageRegionPosture()` from `@object-ui/components` and passes
+`compact` when the answer is `'compact'`, which means the page region the block
+sits in is narrower than half the page (an `aside` or `sidebar` rail beside
+`main`).
+
+With `compact`, the list draws:
+
+- a header with the list's title (its `label`, else the object's label) and
+  the record count;
+- one row per record: the view's first visible column, with the second visible
+  column muted on a line below; a click on a row opens the record the way a grid
+  row does.
+
+It does not draw the toolbar, the view tabs, the `#` row-number column, the
+pager or the record-count bar.
+
+The prop applies only to a paged grid, the view whose rows `ListView` fetches
+a page of. A board, a calendar or a grouped grid keeps its own rendering. When
+`compact` is absent (wide regions, unknown widths, the object list page and
+every other host), the list renders exactly as before.
+
+### "View all"
+
+Under its rows the compact list draws a "View all" link (`list.viewAll`) to the
+rest of the list. The host builds the destination: the `list-view` block asks
+the host's `listHref` / `openList` on `RelatedRecordActionsContext`
+(`@object-ui/react`) for the object it reads, naming the saved view the block
+binds with `dataSource.view` when it binds one. Without a bound view the link
+goes to the object's own list. The block's own `filter`, `columns` and `sort`
+are never handed over, so they never reach the URL; the header count stays the
+answer to what the block shows.
+
+The link is a real anchor: a plain left click navigates in the app through
+`openList`, and a modifier click (a new tab) follows the href. A host that
+publishes no `listHref`, or answers `null`, gets no link. An empty list draws
+no link either.
+
 ## Sorting (and why relational columns are not offered)
 
 The toolbar sort becomes a server `$orderby` on the **flat field name**, so the

package/dist/ListEmptyState.d.ts

@@ -0,0 +1,72 @@
+import { LucideIcon } from 'lucide-react';
+import { ListViewSchema } from '@object-ui/types';
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The empty state a list draws when it has no records (objectui#12217).
+ *
+ * ONE component, drawn by the two surfaces that show a list of records as
+ * rows or cards: `ListView` for its `grid` and `gallery` visualizations, and
+ * `ObjectGallery` when it is rendered without a `ListView` around it (an
+ * authored `object-gallery` node, `ObjectView`'s own non-grid path). It used to
+ * live inline in `ListView`'s grid branch, and `ObjectGallery` drew its own
+ * hard-coded English line instead, ignoring both the view's authored
+ * `emptyState` and the locale.
+ *
+ * Module-internal: not exported from the package barrel. The copy is the
+ * `list.*` keys the grid already read; ⛔ no second string table. Each caller
+ * hands over the translation function and display locale it already holds, the
+ * authored members it has (an authored icon NAME already resolved through the
+ * icon seam), and what it knows about the query that came back empty; a caller
+ * that has no search box or user filters (a standalone gallery) says `false`.
+ */
+import * as React from 'react';
+/**
+ * Whether a DECLARED filter (the view's own `filter`, or a standalone node's)
+ * narrows the query at all: a non-empty condition array or a non-empty
+ * filter-node object. An absent filter, `[]` and `{}` narrow nothing.
+ */
+export declare function hasDeclaredFilter(filter: unknown): boolean;
+/** The authored `emptyState` (the spec's `EmptyStateSchema`). */
+type AuthoredEmptyState = NonNullable<ListViewSchema['emptyState']>;
+export interface ListEmptyStateProps {
+    /** The authored `emptyState.title` (`I18nLabel`), resolved here against `displayLocale`. */
+    title?: AuthoredEmptyState['title'];
+    /** The authored `emptyState.message` (`I18nLabel`), resolved here against `displayLocale`. */
+    message?: AuthoredEmptyState['message'];
+    /**
+     * The authored `emptyState.icon`, already resolved by the caller through the
+     * ONE icon seam (`resolveIcon`, objectui#5935); `null` or absent draws the
+     * `Inbox` glyph.
+     */
+    icon?: LucideIcon | null;
+    /**
+     * The authored `emptyState.link`, `{ label, url }` (objectui#12270), drawn by
+     * the one shared `EmptyStateLink` beside the add-record action. The spec
+     * keeps the two apart: the link is the empty state's own next step, the
+     * add-record entry point is the view's `addRecord` block, so either, both or
+     * neither may be drawn.
+     */
+    link?: AuthoredEmptyState['link'];
+    /**
+     * The USER applied a query: the search box, the user-filter chips, the
+     * filter panel. Only then is the user told to adjust or clear their filters.
+     */
+    hasUserQuery: boolean;
+    /** The declared filter narrows the query (see {@link hasDeclaredFilter}). */
+    hasBaseFilter: boolean;
+    /** Draws the add-record action when supplied; omitted, no action is drawn. */
+    onAddRecord?: () => void;
+    /** The caller's `list.*` translation function. */
+    t: (key: string) => string;
+    /** The locale an authored `I18nLabel` map is resolved against. */
+    displayLocale: string;
+}
+export declare function ListEmptyState({ title: authoredTitle, message: authoredMessage, icon, link, hasUserQuery, hasBaseFilter, onAddRecord, t, displayLocale, }: ListEmptyStateProps): React.JSX.Element;
+export {};
+//# sourceMappingURL=ListEmptyState.d.ts.map

package/dist/ListEmptyState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListEmptyState.d.ts","sourceRoot":"","sources":["../src/ListEmptyState.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAKvD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAI1D;AAED,iEAAiE;AACjE,KAAK,kBAAkB,GAAG,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,4FAA4F;IAC5F,KAAK,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAClC;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB,6EAA6E;IAC7E,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,kDAAkD;IAClD,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,eAAe,EACxB,IAAI,EACJ,IAAI,EACJ,YAAY,EACZ,aAAa,EACb,WAAW,EACX,CAAC,EACD,aAAa,GACd,EAAE,mBAAmB,qBAgErB"}