@synopackageland/ui 0.10.5 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.11.1 (2026-10-17)
+
+- Fill-height pages: `AppLayout height="fill"` takes its container's height (a DSM window) and scrolls its content area instead of the document; `PageContent height="fill"` keeps the page header, tabs and toolbar in place and lets its last child (a `DataGrid`, or a flex column holding one) take the height left. The grid scrolls its rows under its sticky header and its pager stays in view, so a 50-row page no longer pushes the pager far below. Both default to `height="auto"` (unchanged). The SDK's `AppShell` page `fill: true` does the same.
+- `DataGrid` column `priority`: when the shown columns do not fit at their minimum widths, the grid leaves out the lowest priority first (the rightmost of a tie first), so an 800 px DSM window drops its least needed columns instead of scrolling sideways. Columns without a `priority`, or with `hideable: false`, always show. A column left out for width is not saved as hidden, is still searched by the quick filter, returns when the window widens, and is listed unchecked in the column chooser with "Too narrow" (new label `hiddenByWidth`, nine locales); checking it there shows it for this view.
+- New `formatDateTime(value, { locale, style, timeZone, now, unknown })`. `style: 'compact'` fits a 140 px column in every built-in locale: this year `10/17 14:32` (zh-TW, zh-CN, ja), `10. 17. 14:32` (ko), `Oct 17, 2:32 PM` (en), `17. Okt., 14:32` (de); another year the date with its year (`2025/3/2`, `Mar 2, 2025`). The default `full` style (`Oct 17, 2026, 2:32:05 PM`, `2026年10月17日 下午2:32:05`) is for the tooltip. `DateTimeFormatOptions` is exported.
+- **Visible change:** a running `CellStatus` fits one DataGrid row: the label line is 16 px, the gap 2 px and the bar a 4 px line (new `Progress size="sm"`), 22 px in all, so rows with a progress bar are as high as the others. A `detail` still adds a line.
+- Every DataGrid body cell, a `#cell-<key>` slot's included, carries `data-column="<key>"`.
+- Checkbox menu entries take a `hint`, a quiet note after the label. The column chooser keeps its menu open while columns are toggled (documented; unchanged).
+- Visible changes for apps: Download Hub should mark its downloads page `fill: true` in `AppShell` and make the list's wrapper a flex column (`display:flex; flex-direction:column; min-height:0`), give optional columns a `priority` (start time 1, speed 2, location 3, size 4), format times with `formatDateTime(..., { style: 'compact' })` with the full form as `title` instead of its own `Intl.DateTimeFormat`, and drop its own `data-cell` spans used only to find cells in tests.
+
+繁中摘要：新增填滿高度的頁面：`AppLayout height="fill"` 取容器高度（DSM 視窗）、由內容區捲動而非整份文件；`PageContent height="fill"` 讓頁首、分頁籤、工具列固定，最後一個子元素（`DataGrid`，或包著它的 flex 欄）填滿剩餘高度，表格在固定表頭下捲動列、頁尾 pager 永遠可見。兩者預設 `height="auto"`（不變）；SDK `AppShell` 的頁面 `fill: true` 效果相同。`DataGrid` 欄位新增 `priority`：最小寬度放不下時，從最低優先的欄開始隱藏（同優先從最右邊），800px DSM 視窗會少顯示次要欄而不橫向捲動；沒設 `priority` 或 `hideable: false` 的欄一定顯示。因寬度隱藏的欄不會存成使用者隱藏、仍參與快速篩選、視窗變寬即回來，欄位選單中以未勾選加「空間不足」（新 label `hiddenByWidth`，九語系）列出，勾選即在此檢視中顯示。新增 `formatDateTime`：`style: 'compact'` 在所有內建語系都放得進 140px 欄，今年為 `10/17 14:32`、`Oct 17, 2:32 PM`，其他年份只顯示含年份的日期（`2025/3/2`、`Mar 2, 2025`）；預設 `full` 含秒，供 tooltip。**可見變更：**執行中的 `CellStatus` 符合一列高度（標籤 16px＋間距 2px＋新的 `Progress size="sm"` 4px 細條＝22px），有進度條的列不再較高；`detail` 仍會多一行。DataGrid 每個儲存格（含 slot）都有 `data-column`。勾選型選單項目新增 `hint`；欄位選單勾選時保持開啟（已寫入文件，行為不變）。Download Hub 升級時：下載頁設 `fill: true`、清單外層改為 flex 欄、選用欄設 `priority`（開始時間 1、速度 2、存放位置 3、大小 4）、時間改用 `formatDateTime` compact 並以完整格式作 `title`、移除只為測試定位而加的 `data-cell`。
+
+## 0.11.0 (2026-10-17)
+
+- `DataGrid` handles long lists by itself. Every column gets a pixel width: a column with `width` keeps it, a column without one is flexible and shares the rest by the new `flex` weight (default 1), never below its `minWidth` (default 80 px for a flexible column). A long file name can no longer take the whole width, a header never wraps one character per line, and the grid scrolls sideways only when the minimums do not fit (a phone) or the user widened columns. A plain cell is cut to one line with its full text in a tooltip; `wrap: true` wraps a column instead. Headers carry their label as a tooltip.
+- Column chooser: `column-chooser` adds a columns button at the right of the header where the user shows and hides columns (`hideable: false` keeps one, `defaultHidden: true` starts one hidden) and resets order, visibility and widths. `v-model:hidden-columns`; `resetColumns()` is exposed.
+- Column reorder: `column-reorder` moves a column by dragging its header onto another, or with Alt+Left/Right on a focused header. `v-model:column-order`.
+- Quick filter: `filter` (with `searchable` / `searchText` per column, `filter-row`, or `:local-filter="false"` for server results) runs before sorting and paging, so it finds rows on every page. The footer reads "3 of 240 items" and an empty result says "No matching items".
+- Paging: `page` and `page-size` work unbound as well as with `v-model:page` / `v-model:page-size`; `page-sizes` adds a page-size choice to the footer. A new filter, sort or page size goes back to page 1; a page past the end (the rows shrank) shows the last page.
+- Saved view: `state-key` saves the user's column order, hidden columns, widths, sort and page size in localStorage and restores them; bound props win. `loadGridState` / `saveGridState` and the `DataGridViewState` type are exported for apps that keep the view elsewhere.
+- New `labels`: `columns`, `resetColumns`, `filtered(count, total)`, `noMatch`, `pageSize` (optional, like the row labels; translated in all nine locales).
+- **Visible change:** columns without a `width` share the free width evenly (by `flex`) instead of sizing to their content, and the table always has a trailing filler column. **Behavior change:** a grid that did not bind `page` now pages when the footer buttons are clicked (before, it only emitted `update:page`).
+- Visible changes for apps: Download Hub's list no longer lets a long name push 存放位置 and 狀態 into one-character columns. Give the main column `flex: 2` and a `minWidth`, mark optional columns (start/finish time, speed) `defaultHidden`, add `column-chooser`, `column-reorder`, `page-sizes` and a `state-key`, and bind a `SearchField variant="filter"` to `filter`. Remove hand-written `title` attributes on plain cells and app-side filtering of the current page.
+
+繁中摘要：`DataGrid` 自己處理長清單。每欄都有像素寬度：有 `width` 的欄維持，沒有的欄依新的 `flex`（預設 1）分配剩餘寬度、不小於 `minWidth`（彈性欄預設 80px）；長檔名不再吃掉整個寬度，表頭不會一字一行，只有最小寬度放不下（手機）或使用者拉寬欄時才橫向捲動。一般儲存格單行省略並以 tooltip 顯示全文，`wrap: true` 改為換行；表頭也有 tooltip。新增欄位選擇（`column-chooser`：表頭右側按鈕，可顯示／隱藏欄、重設順序／顯示／寬度；`hideable: false`、`defaultHidden`、`v-model:hidden-columns`、`resetColumns()`）、欄位排序（`column-reorder`：拖曳表頭或 Alt+←／→；`v-model:column-order`）、快速篩選（`filter`，在排序與分頁前搜尋全部列；`searchable`、`searchText`、`filter-row`、`:local-filter="false"`；頁尾顯示「3／240 個項目」，無結果顯示「沒有符合的項目」）、分頁改進（`page`／`page-size` 不綁也能用，`page-sizes` 選每頁筆數；篩選、排序、每頁筆數變更時回到第 1 頁，超出頁數時顯示最後一頁）、狀態保存（`state-key` 把欄順序、隱藏、寬度、排序、每頁筆數存 localStorage；綁定的 props 優先；匯出 `loadGridState`／`saveGridState`）。新增 labels：`columns`、`resetColumns`、`filtered`、`noMatch`、`pageSize`（九種語系皆已翻譯）。**可見變更：**沒有 `width` 的欄改為平均分配剩餘寬度而非依內容；表格最後固定有填充欄。**行為變更：**沒綁 `page` 的 grid 點頁尾按鈕會自己換頁（以前只 emit）。App 升級時：主欄設 `flex: 2` 與 `minWidth`，選用欄（開始／完成時間、速度）設 `defaultHidden`，加上 `column-chooser`、`column-reorder`、`page-sizes`、`state-key`，並把 `SearchField variant="filter"` 綁到 `filter`；移除自己在一般儲存格加的 `title` 與只篩選目前頁的程式。
+
 ## 0.10.5 (2026-10-17)
 
 - **Visible change:** `Checkbox`, `RadioGroup` and the `TreeView` checkbox use an 18 px box with a 9 px text gap (was 16 px and 8 px); the check, indeterminate dash and radio dot scale with the box. Labels use a 20 px line height and vertical `RadioGroup` / `CheckboxGroup` items have an 8 px gap: the net row pitch is 28 px (20 + 8), down from the intermediate 30 px. Tokens `--ui-choice-box-size`, `--ui-choice-box-gap`, `--ui-choice-box-offset` and `--ui-choice-stack-gap` control these sizes. Textless DataGrid selection boxes, including select-all, are centred without the inline line-box offset; the horizontal gap remains 34 px (`--ui-choice-inline-gap`).

package/README.md

@@ -335,6 +335,31 @@ import { AppLayout, Button, PageHeader } from '@synopackageland/ui'
 `PageHeader` the space is the header's own bottom padding (12px in a DSM
 window), with no section gap added.
 
+**Fill-height pages.** A list page whose grid pages its rows should not
+scroll as a whole, or a 50-row page pushes its pager far below. Give both the
+layout and the page `height="fill"`: `AppLayout` then takes its container's
+height (a DSM window) and scrolls its content area instead of the document;
+`PageContent` keeps its header, tabs and toolbar in place, and its **last
+child** takes the height left. Make that child the `DataGrid` itself, or a
+flex column (`flex flex-col min-h-0`) holding it: the grid scrolls its rows
+under its sticky header, with the pager always in view. Pages that are not
+`fill` in the same layout scroll as before. In the SDK's `AppShell`, the same
+is a page's `fill: true`.
+
+```vue
+<AppLayout height="fill" min-height="0">
+  <template #sidebar>…</template>
+  <PageContent height="fill">
+    <PageHeader title="下載" />
+    <div class="flex items-center justify-between gap-2">
+      <SectionTabs v-model="tab" :items="tabs" />
+      <SearchField v-model="filter" variant="filter" />
+    </div>
+    <DataGrid :columns="columns" :rows="rows" :filter="filter" :page-sizes="[50, 100, 200]" column-chooser />
+  </PageContent>
+</AppLayout>
+```
+
 To set a block apart inside a card, use `<Surface variant="inset">`. DSM draws it as a
 faint grey block with no border of its own, at 12px × 16px padding.
 
@@ -475,30 +500,51 @@ maps its own states to six link states.
 
 ### DataGrid
 
+`DataGrid` is the list for data that grows (downloads, tasks, files): sorting,
+column chooser, column reorder, resize, quick filter, paging and saved view
+state. `DataTable` stays the small read-only table that becomes cards on a
+phone; use `DataGrid` for anything a user searches or arranges.
+
 ```vue
+<SearchField v-model="filter" variant="filter" />
 <DataGrid
-  :columns="[{ key: 'name', label: 'Name', sortable: true, width: 170, minWidth: 80 }]"
+  :columns="[
+    { key: 'name', label: '名稱', sortable: true, flex: 2, minWidth: 200, hideable: false },
+    { key: 'size', label: '大小', sortable: true, width: 90, align: 'right' },
+    { key: 'location', label: '存放位置', minWidth: 120 },
+    { key: 'started', label: '開始時間', sortable: true, width: 140, defaultHidden: true },
+  ]"
   :rows="rows"
-  :default-sort="{ key: 'name', direction: 'asc' }"
-  v-model:column-widths="savedWidths"
+  :filter="filter"
+  :page-sizes="[50, 100, 200]"
+  state-key="downloads"
+  column-chooser
+  column-reorder
   footer
   refreshable
-  :labels="{ items: n => `${n} 個項目`, refresh: '重新整理', empty: '沒有資料' }"
   @refresh="reload"
 />
 ```
 
+- **Column widths.** A column with `width` (px, or a percentage of the grid) keeps it; a column without one is flexible and shares the rest by `flex` (default 1), never below its `minWidth` (default 80px for a flexible column, 40px for a fixed one). A long text cannot widen its column, and a header never wraps. When the minimums do not fit (a phone), the grid scrolls sideways instead of squeezing.
+- **Long text.** A plain cell is cut to one line with an ellipsis and shows its full text on hover (`title`); `wrap: true` wraps a column instead. A `#cell-<key>` slot renders its own content: `CellText` cuts and titles it the same way. Every body cell, a slot's included, carries `data-column="<key>"`.
+- **Row height.** Rows are one height (28px, 24px compact). `CellStatus` with a running `progress` fits it (a 4px bar under the label); its `detail` adds a line, so put speed or a reason in its own column. Dates: `formatDateTime(value, { locale, style: 'compact' })` in the cell (this year: `10/17 14:32`, `Oct 17, 2:32 PM`; another year: the date with its year, `2025/3/2`, `Mar 2, 2025`) and the full `formatDateTime(value, { locale })` as its `title`; it fits a 140px column in every built-in locale.
 - **Sort.** Click a sortable header, or focus it and press Enter/Space (`aria-sort` is set). Cycle: ascending, descending, off. Leave `sort` unbound and the grid sorts itself (start with `default-sort`); bind `v-model:sort` to control it; with `:local-sort="false"` it only emits.
-- **Column resize.** Drag the right edge of a header, or focus the edge and press the left/right arrows (10px). Widths are px, never below the column's `minWidth` (default 40). Persist them with `v-model:column-widths` (or `@column-resize`); pass them back to restore. `resizable` is on by default; turn it off per grid or per column.
+- **Column chooser.** `column-chooser` adds a columns button at the right of the header: the user shows and hides columns and resets them. `hideable: false` keeps a column, `defaultHidden: true` starts one hidden; the last shown column cannot be hidden. Bind `v-model:hidden-columns` to control it. A click on a column toggles it and **keeps the menu open**, so several columns can be changed in a row; Reset, Escape or a click outside closes it.
+- **Column priority (narrow windows).** Give optional columns a `priority`: when the shown columns do not fit at their minimum widths (a fixed `width`, else `minWidth`), the grid leaves out the lowest priority first (the rightmost of a tie first) until the rest fits, so an 800px DSM window loses its least needed columns instead of scrolling sideways. A column without a `priority`, or with `hideable: false`, is never left out, so a grid of such columns still scrolls (a phone). A column left out for width is not hidden by the user: it is not saved, the quick filter still searches it, it returns when the window widens, and the chooser lists it unchecked with "Too narrow" (`labels.hiddenByWidth`). Checking it there shows it anyway for this view; the next lowest priority then makes room, or the grid scrolls.
+- **Column reorder.** `column-reorder` lets the user drag a header onto another, or focus it and press Alt+Left/Right. Bind `v-model:column-order` to control it; keys of new columns not in a saved order follow at the end.
+- **Column resize.** Drag the right edge of a header, or focus the edge and press the left/right arrows (10px). Persist widths with `v-model:column-widths` (or `@column-resize`); pass them back to restore. `resizable` is on by default; turn it off per grid or per column.
+- **Quick filter.** `filter` shows the rows whose shown, searchable columns contain the text (case-insensitive), across every page, before sorting and paging. `searchable: false` leaves a column out, `searchText(row)` gives the text to search, `filter-row(row, text)` replaces the match. Rows that come filtered from a server: `:local-filter="false"`. The footer reads "3 of 240 items" and an empty result says nothing matches.
+- **Paging.** Long lists are paged in the footer (20 rows per page by default). `page` and `page-size` work unbound or with `v-model:page` / `v-model:page-size`; `page-sizes` adds the page-size choice. A new filter, sort or page size goes back to page 1, and a page past the end shows the last one. With `:local-pagination="false"` and `total-rows` the app pages on its server. Virtual scrolling is not provided.
+- **Saved view.** `state-key="downloads"` saves the user's column order, hidden columns, widths, sort and page size in this browser (localStorage) and restores them; bound props win. To keep them on a server, bind the v-models instead, or use the exported `loadGridState` / `saveGridState`. `resetColumns()` (exposed) and the chooser's Reset restore order, visibility and widths.
 - **Layout.** Sticky header (default), column dividers, hover and selected row colours, `max-height` to scroll inside the grid. `selectable` adds checkboxes; with `select-on-row-click` a row click selects the row and Ctrl/Cmd-click toggles it.
-- **Footer bar.** `footer` shows the DSM bar with the item count; `refreshable` adds the refresh button (`@refresh`, `refreshing` spins it). Without `footer` it appears only when there is more than one page or a `#footer` slot.
-- **Localisation.** Every built-in string goes through `labels`: `empty`, `items(count)`, `page(page, count)`, `previous`, `next`, `refresh`, `selectAll`, `selectRow(key)`, `resizeColumn(label)`. `emptyText` still works.
+- **Footer bar.** `footer` shows the DSM bar with the item count; `refreshable` adds the refresh button (`@refresh`, `refreshing` spins it). Without `footer` it appears when there is more than one page, a page-size choice that matters, or a `#footer` slot.
+- **Localisation.** Every built-in string goes through `labels`: `empty`, `noMatch`, `items(count)`, `filtered(count, total)`, `page(page, count)`, `previous`, `next`, `pageSize`, `refresh`, `selectAll`, `selectRow(key)`, `resizeColumn(label)`, `columns`, `resetColumns`, `hiddenByWidth`. `emptyText` still works.
 - **Loading.** `loading` masks the table with a centred indicator; `loading-text` adds a message.
 - **Footer layout.** The footer has top and bottom divider lines and a separator
   before Refresh. In a flex column with a bounded height, the grid fills the
   remaining space and its rows scroll above the footer. Use `class="flex-none"`
   for a grid that should retain its content height.
-- Virtual scrolling is not provided; page long lists (`page-size`).
 
 ### Loading
 

package/dist/DataGridListDemo.vue.d.ts

@@ -0,0 +1,13 @@
+type __VLS_Props = {
+    stateKey?: string;
+    locale?: 'zh-TW' | 'en';
+    filter?: string;
+    toolbar?: boolean;
+};
+declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    filter: string;
+    locale: "zh-TW" | "en";
+    toolbar: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/DownloadsPageDemo.vue.d.ts

@@ -0,0 +1,8 @@
+type __VLS_Props = {
+    locale?: 'zh-TW' | 'en';
+};
+declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    locale: "zh-TW" | "en";
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/app/app-layout/AppLayout.vue.d.ts

@@ -12,6 +12,12 @@ type __VLS_Props = {
     brandName?: string;
     /** Logo URL beside the brand name; defaults to the page icon. */
     brandIcon?: string;
+    /**
+     * `'fill'` takes the container's height (a DSM window) and scrolls the
+     * content area instead of the document, so a `PageContent height="fill"`
+     * page can keep its header and pager in view.
+     */
+    height?: 'auto' | 'fill';
 };
 type __VLS_Slots = {
     sidebar?: () => unknown;
@@ -22,6 +28,7 @@ type __VLS_Slots = {
     footer?: () => unknown;
 };
 declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    height: "auto" | "fill";
     minHeight: string;
     sidebarWidth: string;
     responsive: boolean;

package/dist/components/app/page-content/PageContent.vue.d.ts

@@ -6,12 +6,19 @@ type __VLS_Props = {
     width?: 'fill' | 'readable' | (string & {});
     /** Web/portal mode uses a page surface by default. Set flat for card-based dashboards. */
     surface?: 'auto' | 'flat' | 'card';
+    /**
+     * `'fill'` takes the container's height and does not scroll: the header,
+     * tabs and toolbar stay, and the last child (a DataGrid, or a flex column
+     * holding one) takes the height left and scrolls itself.
+     */
+    height?: 'auto' | 'fill';
 };
 declare var __VLS_1: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
 declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    height: "auto" | "fill";
     width: "fill" | "readable" | (string & {});
     surface: "auto" | "flat" | "card";
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;

package/dist/components/composite/data-grid/DataGrid.vue.d.ts

@@ -6,9 +6,28 @@ export type DataGridSort = {
 export type DataGridColumn = {
     key: string;
     label: string;
-    /** A pixel width (`120`, `"120px"`). Other CSS units size the column but cannot be resized from. */
+    /** A pixel width (`120`, `"120px"`) or a percentage of the grid; without it the column is flexible. */
     width?: string | number;
+    /** Defaults to 80px for a flexible column, 40px for a fixed one. */
     minWidth?: string | number;
+    /** A flexible column's share of the space the fixed columns leave; defaults to 1. */
+    flex?: number;
+    /** Wraps the cell text instead of cutting it to one line with an ellipsis. */
+    wrap?: boolean;
+    /** `false` keeps the column shown: the column chooser cannot hide it. */
+    hideable?: boolean;
+    /** Starts hidden; the user can show it from the column chooser. */
+    defaultHidden?: boolean;
+    /**
+     * Leaves the column out when the grid is too narrow for every column's
+     * minimum width: the lowest priority goes first. Without one the column
+     * always shows. The column chooser still lists it, to show it anyway.
+     */
+    priority?: number;
+    /** `false` leaves the column out of the quick filter. */
+    searchable?: boolean;
+    /** The text the quick filter searches for a row; defaults to the cell value. */
+    searchText?: (row: Record<string, unknown>) => string;
     align?: 'left' | 'center' | 'right';
     sortable?: boolean;
     /** Overrides the grid's `resizable` for this column. */
@@ -105,9 +124,19 @@ type __VLS_Props = {
     selectOnRowClick?: boolean;
     /** One selected row at a time, picked by clicking the row; no checkbox column. */
     singleSelect?: boolean;
+    /** Bind to control the page; leave unset and the grid pages by itself. */
     page?: number;
+    /** Rows per page; defaults to the first of `pageSizes`, else 20. Bind with `v-model:page-size` to follow the user's choice. */
     pageSize?: number;
+    /** Page sizes the user can pick from in the footer, e.g. `[20, 50, 100]`. */
+    pageSizes?: number[];
     totalRows?: number;
+    /** Quick filter text: shows the rows whose shown, searchable columns contain it, across all pages. */
+    filter?: string;
+    /** Replaces the quick filter's match with your own; it gets the trimmed, lower-cased filter text. */
+    filterRow?: (row: Record<string, unknown>, text: string) => boolean;
+    /** `false` when the rows arrive filtered (a server search): the grid shows them as they are. */
+    localFilter?: boolean;
     localSort?: boolean;
     localPagination?: boolean;
     loading?: boolean;
@@ -119,6 +148,20 @@ type __VLS_Props = {
     resizable?: boolean;
     /** Persisted column widths in px, by column key. */
     columnWidths?: DataGridColumnWidths;
+    /** Column keys in display order; bind to keep the user's order, leave unset and the grid tracks it. */
+    columnOrder?: string[];
+    /** Keys of hidden columns; defaults to the columns marked `defaultHidden`. */
+    hiddenColumns?: string[];
+    /**
+     * Saves the user's column order, hidden columns, widths, sort and page size
+     * in this browser under this key and restores them. Bound props win; to keep
+     * them on a server, bind the v-models instead.
+     */
+    stateKey?: string;
+    /** A header menu where the user shows and hides columns and resets them. */
+    columnChooser?: boolean;
+    /** Drag a header onto another, or press Alt+Left/Right on it, to move the column. */
+    columnReorder?: boolean;
     /** `true` always shows the footer bar, `false` never; unset shows it when paged or given a slot. */
     footer?: boolean;
     refreshable?: boolean;
@@ -137,6 +180,7 @@ type __VLS_Props = {
     /** Row reordering with drag and drop plus keyboard support. */
     draggable?: boolean | DataGridDraggable;
 };
+declare function resetColumns(): void;
 type __VLS_Slots = {
     empty?: (props: Record<string, never>) => unknown;
     'group-title'?: (props: DataGridGroupSlotProps) => unknown;
@@ -160,12 +204,16 @@ declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {
     collapseAllGroups: () => void;
     moveRowUp: (row: Record<string, unknown>) => void;
     moveRowDown: (row: Record<string, unknown>) => void;
+    resetColumns: typeof resetColumns;
 }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     refresh: () => any;
+    "update:pageSize": (value: number) => any;
     "update:sort": (value: DataGridSort | null) => any;
     "update:selectedKeys": (value: string[]) => any;
     "update:page": (value: number) => any;
     "update:columnWidths": (value: DataGridColumnWidths) => any;
+    "update:columnOrder": (value: string[]) => any;
+    "update:hiddenColumns": (value: string[]) => any;
     "update:rows": (value: Record<string, unknown>[]) => any;
     "update:expandedKeys": (value: string[]) => any;
     columnResize: (value: {
@@ -192,10 +240,13 @@ declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {
     cellUpdate: (value: DataGridCellUpdate) => any;
 }, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
     onRefresh?: (() => any) | undefined;
+    "onUpdate:pageSize"?: ((value: number) => any) | undefined;
     "onUpdate:sort"?: ((value: DataGridSort | null) => any) | undefined;
     "onUpdate:selectedKeys"?: ((value: string[]) => any) | undefined;
     "onUpdate:page"?: ((value: number) => any) | undefined;
     "onUpdate:columnWidths"?: ((value: DataGridColumnWidths) => any) | undefined;
+    "onUpdate:columnOrder"?: ((value: string[]) => any) | undefined;
+    "onUpdate:hiddenColumns"?: ((value: string[]) => any) | undefined;
     "onUpdate:rows"?: ((value: Record<string, unknown>[]) => any) | undefined;
     "onUpdate:expandedKeys"?: ((value: string[]) => any) | undefined;
     onColumnResize?: ((value: {
@@ -222,6 +273,7 @@ declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {
     onCellUpdate?: ((value: DataGridCellUpdate) => any) | undefined;
 }>, {
     footer: boolean;
+    filter: string;
     sort: DataGridSort | null;
     loading: boolean;
     group: DataGridGroup | null;
@@ -231,15 +283,20 @@ declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {
     pageSize: number;
     selectable: boolean;
     rowKey: string;
+    columnOrder: string[];
+    hiddenColumns: string[];
     defaultSort: DataGridSort | null;
     selectedKeys: string[];
     selectOnRowClick: boolean;
     singleSelect: boolean;
+    localFilter: boolean;
     localSort: boolean;
     localPagination: boolean;
     loadingRows: number;
     stickyHeader: boolean;
     resizable: boolean;
+    columnChooser: boolean;
+    columnReorder: boolean;
     refreshable: boolean;
     refreshing: boolean;
     expandable: DataGridExpandable | null;

package/dist/components/composite/data-grid/columnState.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Columns in a saved order: keys the order names come first, in its order;
+ * columns it does not name (added since it was saved) follow in their own
+ * order; keys of columns that are gone are ignored.
+ */
+export declare function orderColumns<T extends {
+    key: string;
+}>(columns: T[], order: string[]): T[];
+/** `keys` with `key` moved to index `to`. */
+export declare function moveKey(keys: string[], key: string, to: number): string[];

package/dist/components/composite/data-grid/columnWidths.d.ts

@@ -1,6 +1,34 @@
 export declare const DEFAULT_MIN_COLUMN_WIDTH = 40;
-export declare const FALLBACK_COLUMN_WIDTH = 100;
+/** A flexible column keeps room for a short header and a few characters. */
+export declare const FLEX_MIN_COLUMN_WIDTH = 80;
 export declare const KEYBOARD_RESIZE_STEP = 10;
 /** A pixel width from a number or a `"120px"` / `"120"` string; other units are unknown. */
 export declare function toPixels(value: string | number | undefined): number | undefined;
 export declare function clampWidth(width: number, minWidth: number): number;
+export type ColumnWidthSpec = {
+    key: string;
+    /** A fixed width in px; without it the column shares the rest by `flex`. */
+    width?: number;
+    minWidth: number;
+    flex: number;
+};
+/**
+ * Pixel widths for every column: fixed ones keep theirs, flexible ones share
+ * what is left by weight and never drop below their minimum. Unknown space
+ * (`0`) gives the minimums, so the grid scrolls rather than squeezes.
+ */
+export declare function distributeColumnWidths(columns: ColumnWidthSpec[], available: number): Record<string, number>;
+export type ColumnPrioritySpec = {
+    key: string;
+    /** The least width the column takes: its fixed width or its minimum. */
+    minWidth: number;
+    /** Lower hides first; without one the column is never hidden for width. */
+    priority?: number;
+};
+/**
+ * Keys of the columns to leave out so the rest fits `available` at their
+ * minimum widths: the lowest priority first, the rightmost of a tie first.
+ * Columns without a priority stay, so the grid may still scroll. Unknown
+ * space (`0`) hides none.
+ */
+export declare function columnsHiddenByWidth(columns: ColumnPrioritySpec[], available: number): string[];

package/dist/components/composite/data-grid/labels.d.ts

@@ -1,5 +1,5 @@
 /**
- * Text overrides for the grid chrome. The three row-operation labels were added
+ * Text overrides for the grid chrome. The row-operation and column labels were added
  * after the first release and stay optional so an existing external
  * `DataGridLabels` object literal keeps compiling; the grid merges the defaults in.
  */
@@ -16,12 +16,29 @@ export type DataGridLabels = {
     expandRow?: (key: string) => string;
     collapseRow?: (key: string) => string;
     reorderRow?: (key: string) => string;
+    /** The column chooser button. */
+    columns?: string;
+    resetColumns?: string;
+    /** The item count while the quick filter hides rows. */
+    filtered?: (count: number, total: number) => string;
+    /** The empty text when rows exist but none matches the filter. */
+    noMatch?: string;
+    /** The page-size chooser. */
+    pageSize?: string;
+    /** Beside a column the chooser lists that the width leaves out. */
+    hiddenByWidth?: string;
 };
 /** `DataGridLabels` after the defaults were merged in: every label is present. */
 export type ResolvedDataGridLabels = DataGridLabels & {
     expandRow: (key: string) => string;
     collapseRow: (key: string) => string;
     reorderRow: (key: string) => string;
+    columns: string;
+    resetColumns: string;
+    filtered: (count: number, total: number) => string;
+    noMatch: string;
+    pageSize: string;
+    hiddenByWidth: string;
 };
 export declare const defaultDataGridLabels: ResolvedDataGridLabels;
 /** Locale-aware chrome; the exported English defaults remain available to callers. */

package/dist/components/composite/data-grid/rowFilter.d.ts

@@ -0,0 +1,10 @@
+type FilterColumn = {
+    key: string;
+    searchable?: boolean;
+    searchText?: (row: Record<string, unknown>) => string;
+};
+/** The filter text as matched: trimmed and case-folded; empty matches every row. */
+export declare const normalizeFilter: (text: string | undefined) => string;
+/** Whether a searchable column's text (its value, or `searchText`) contains the normalized filter. */
+export declare function rowMatches(row: Record<string, unknown>, columns: FilterColumn[], filter: string): boolean;
+export {};

package/dist/components/composite/data-grid/viewState.d.ts

@@ -0,0 +1,15 @@
+/** What a user changed in a grid's view; every field is optional. */
+export type DataGridViewState = {
+    columnOrder?: string[];
+    hiddenColumns?: string[];
+    columnWidths?: Record<string, number>;
+    sort?: {
+        key: string;
+        direction: 'asc' | 'desc';
+    } | null;
+    pageSize?: number;
+};
+/** The view state saved under `key` in this browser; fields it cannot trust are dropped. */
+export declare function loadGridState(key: string): DataGridViewState;
+/** Saves the view state under `key`; a browser that refuses storage keeps the grid working unsaved. */
+export declare function saveGridState(key: string, state: DataGridViewState): void;

package/dist/components/composite/scroll-edges/ScrollEdges.vue.d.ts

@@ -7,7 +7,9 @@ declare var __VLS_1: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
-declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {
+    viewport: Readonly<import('vue').ShallowRef<HTMLElement | null>>;
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/components/primitives/dropdown-menu/types.d.ts

@@ -19,6 +19,8 @@ export type DropdownMenuCheckboxEntry = {
     disabled?: boolean;
     danger?: boolean;
     shortcut?: string;
+    /** A quiet note after the label, such as why the item is unchecked. */
+    hint?: string;
 };
 export type DropdownMenuRadioEntry = {
     type: 'radio';

package/dist/components/primitives/progress/Progress.vue.d.ts

@@ -6,8 +6,11 @@ type __VLS_Props = {
     valueLabel?: string;
     /** Colours the bar by meaning, such as `warning` for a volume that is nearly full. */
     tone?: 'primary' | 'success' | 'warning' | 'danger';
+    /** `sm` is a 4px line that fits under a label in a dense table row. */
+    size?: 'md' | 'sm';
 };
 declare const __VLS_export: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    size: "md" | "sm";
     value: number;
     max: number;
     tone: "primary" | "success" | "warning" | "danger";

package/dist/composables/elementWidth.d.ts

@@ -1,4 +1,4 @@
-import { ShallowRef } from 'vue';
+import { Ref } from 'vue';
 /** Observe the component's container, including DSM window resizes that do not
  * resize the document viewport. Zero is unknown (e.g. hidden tab or SSR). */
-export declare function useElementWidth(element: Readonly<ShallowRef<HTMLElement | null>>): import('vue').Ref<number, number>;
+export declare function useElementWidth(element: Readonly<Ref<HTMLElement | null | undefined>>): Ref<number, number>;

package/dist/i18n/text.d.ts

@@ -122,6 +122,11 @@ export declare const englishUiText: {
     readonly "Expand row {key}": "Expand row {key}";
     readonly "Collapse row {key}": "Collapse row {key}";
     readonly "Reorder row {key}": "Reorder row {key}";
+    readonly Columns: "Columns";
+    readonly "Reset columns": "Reset columns";
+    readonly "Too narrow": "Too narrow";
+    readonly "{count} of {total} items": "{count} of {total} items";
+    readonly "No matching items": "No matching items";
     readonly "Sort by {name}": "Sort by {name}";
     readonly "Value is required": "Value is required";
     readonly "Value does not match the expected format": "Value does not match the expected format";

package/dist/index.d.ts

@@ -105,8 +105,8 @@ export { default as RepeatRow } from './components/composite/repeat-rows/RepeatR
 export { default as FieldCell } from './components/composite/repeat-rows/FieldCell.vue';
 export { formatFileSize, formatSpeed } from './lib/fileSize';
 export type { UnknownOption } from './lib/fileSize';
-export { formatDuration, formatPercent, formatRelativeTime } from './lib/format';
-export type { FormatOptions } from './lib/format';
+export { formatDateTime, formatDuration, formatPercent, formatRelativeTime } from './lib/format';
+export type { DateTimeFormatOptions, FormatOptions } from './lib/format';
 export { resolveFieldWidth } from './lib/fieldWidth';
 export type { FieldWidth } from './lib/fieldWidth';
 export { default as SettingsSection } from './components/composite/settings-section/SettingsSection.vue';
@@ -126,6 +126,7 @@ export { default as Statistic } from './components/composite/statistic/Statistic
 export type { DataTableColumn } from './components/composite/data-table/DataTable.vue';
 export { default as DataGrid } from './components/composite/data-grid/DataGrid.vue';
 export type { DataGridColumn, DataGridColumnWidths, DataGridLabels, ResolvedDataGridLabels, DataGridSort, DataGridGroup, DataGridExpandable, DataGridDraggable, DataGridReorder, DataGridCellUpdate, DataGridAdapter, DataGridCellSlotProps } from './components/composite/data-grid/DataGrid.vue';
+export { loadGridState, saveGridState, type DataGridViewState } from './components/composite/data-grid/viewState';
 export { default as TreeView } from './components/composite/tree-view/TreeView.vue';
 export type { TreeNode, TreeViewCheckPayload, TreeViewDraggableConfig, TreeViewPosition, TreeViewReorder } from './components/composite/tree-view/TreeView.vue';
 export { default as FilePicker } from './components/composite/file-picker/FilePicker.vue';