compote-ui 0.79.2 → 0.81.0

package/dist/icons/index.d.ts

@@ -16,6 +16,7 @@ export { default as PhFile } from './PhFile.svelte';
 export { default as PhFileArchive } from './PhFileArchive.svelte';
 export { default as PhFileText } from './PhFileText.svelte';
 export { default as PhFunnel } from './PhFunnel.svelte';
+export { default as PhFunnelFill } from './PhFunnelFill.svelte';
 export { default as PhHeadphones } from './PhHeadphones.svelte';
 export { default as PhImage } from './PhImage.svelte';
 export { default as PhListMagnifyingGlass } from './PhListMagnifyingGlass.svelte';

package/dist/icons/index.js

@@ -16,6 +16,7 @@ export { default as PhFile } from './PhFile.svelte';
 export { default as PhFileArchive } from './PhFileArchive.svelte';
 export { default as PhFileText } from './PhFileText.svelte';
 export { default as PhFunnel } from './PhFunnel.svelte';
+export { default as PhFunnelFill } from './PhFunnelFill.svelte';
 export { default as PhHeadphones } from './PhHeadphones.svelte';
 export { default as PhImage } from './PhImage.svelte';
 export { default as PhListMagnifyingGlass } from './PhListMagnifyingGlass.svelte';

package/dist/utils/date-filter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Calendar-day range filters for date and date-time columns.
+ *
+ * The filter value is `[from?, to?]`, each an ISO calendar date (`YYYY-MM-DD`) or empty — no
+ * time, no zone, so it serializes cleanly. Both bounds are inclusive days. A cell matches
+ * when the day it shows in the display zone (see `readDateInZone`) falls inside the range.
+ * For an instant that is the half-open interval [start of `from`, start of the day after
+ * `to`) in that zone, with day starts taken from the calendar — so 23- and 25-hour DST days
+ * need no special handling.
+ */
+import { CalendarDate } from '@internationalized/date';
+/** A date range filter value as stored in table state. */
+export type DateRangeFilterValue = [from?: string, to?: string];
+/** A filter value read into calendar dates; an absent bound leaves that end open. */
+export type DateRange = {
+    from?: CalendarDate;
+    to?: CalendarDate;
+};
+/**
+ * The range a filter value stands for. Invalid bounds are dropped and a reversed range is
+ * swapped (as TanStack's `inNumberRange` does). Always returns a range — never undefined —
+ * because the table falls back to the raw value when `resolveFilterValue` returns nullish.
+ */
+export declare function resolveDateRange(filterValue: unknown): DateRange;
+/** Whether a filter value has no usable bound, so the filter should be removed. */
+export declare function isEmptyDateRange(filterValue: unknown): boolean;
+/**
+ * Whether a cell value falls in `range`, judged by the calendar day it shows in `timeZone`.
+ * Empty or unparseable cell values never match while the filter is active.
+ */
+export declare function matchesDateRange(value: unknown, range: DateRange, timeZone: string): boolean;

package/dist/utils/date-filter.js

@@ -0,0 +1,58 @@
+/**
+ * Calendar-day range filters for date and date-time columns.
+ *
+ * The filter value is `[from?, to?]`, each an ISO calendar date (`YYYY-MM-DD`) or empty — no
+ * time, no zone, so it serializes cleanly. Both bounds are inclusive days. A cell matches
+ * when the day it shows in the display zone (see `readDateInZone`) falls inside the range.
+ * For an instant that is the half-open interval [start of `from`, start of the day after
+ * `to`) in that zone, with day starts taken from the calendar — so 23- and 25-hour DST days
+ * need no special handling.
+ */
+import { CalendarDate, parseDate, toCalendarDate } from '@internationalized/date';
+import { readDateInZone } from './date';
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/** A bound as a calendar date; anything but a valid `YYYY-MM-DD` reads as no bound. */
+function readBound(value) {
+    if (typeof value !== 'string' || !DATE_ONLY.test(value))
+        return undefined;
+    try {
+        return parseDate(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The range a filter value stands for. Invalid bounds are dropped and a reversed range is
+ * swapped (as TanStack's `inNumberRange` does). Always returns a range — never undefined —
+ * because the table falls back to the raw value when `resolveFilterValue` returns nullish.
+ */
+export function resolveDateRange(filterValue) {
+    if (!Array.isArray(filterValue))
+        return {};
+    const from = readBound(filterValue[0]);
+    const to = readBound(filterValue[1]);
+    if (from && to && from.compare(to) > 0)
+        return { from: to, to: from };
+    return { from, to };
+}
+/** Whether a filter value has no usable bound, so the filter should be removed. */
+export function isEmptyDateRange(filterValue) {
+    const { from, to } = resolveDateRange(filterValue);
+    return !from && !to;
+}
+/**
+ * Whether a cell value falls in `range`, judged by the calendar day it shows in `timeZone`.
+ * Empty or unparseable cell values never match while the filter is active.
+ */
+export function matchesDateRange(value, range, timeZone) {
+    const date = readDateInZone(value, timeZone);
+    if (!date)
+        return false;
+    const day = date instanceof CalendarDate ? date : toCalendarDate(date);
+    if (range.from && day.compare(range.from) < 0)
+        return false;
+    if (range.to && day.compare(range.to) > 0)
+        return false;
+    return true;
+}

package/dist/utils/date.d.ts

@@ -1,4 +1,4 @@
-import { type DateValue } from '@internationalized/date';
+import { CalendarDate, ZonedDateTime, type DateValue } from '@internationalized/date';
 export type { DateValue };
 /**
  * Anything the date components accept for a single value: an
@@ -24,3 +24,21 @@ export declare function dateValueToString(value: DateValue): string;
 export declare function dateValueToDate(value: DateValue, timeZone?: string): Date;
 /** Emit a `DateValue` back in the original `shape` it was bound as. */
 export declare function fromDateValue(value: DateValue | null, shape: DateValueShape, timeZone?: string): DateValue | string | Date | null;
+/**
+ * A value read for display in `timeZone`: a calendar date (a day, with no instant behind it)
+ * or an instant converted into `timeZone`.
+ */
+export type ZonedOrCalendarDate = CalendarDate | ZonedDateTime;
+/**
+ * Read any date-ish value — a `DateValue`, ISO/DB string, native `Date` or epoch-millisecond
+ * number — the way it should be shown in `timeZone`. Never throws: anything unparseable
+ * (including an out-of-range date like `2024-02-30`) is `null`.
+ *
+ * - `"2024-03-15"` and `CalendarDate` stay calendar dates. They are never turned into an
+ *   instant, which would put them on the previous day in zones west of UTC.
+ * - `Date`, epoch numbers, offset strings (`Z`, `+02:00`) and `ZonedDateTime` are instants,
+ *   converted into `timeZone`.
+ * - A datetime without an offset (`"2024-03-15T10:30"`, `CalendarDateTime`) is a wall-clock
+ *   time in `timeZone`.
+ */
+export declare function readDateInZone(value: unknown, timeZone: string): ZonedOrCalendarDate | null;

package/dist/utils/date.js

@@ -1,4 +1,4 @@
-import { parseDate, parseDateTime, parseAbsolute, parseAbsoluteToLocal, fromDate, getLocalTimeZone } from '@internationalized/date';
+import { CalendarDate, CalendarDateTime, ZonedDateTime, parseDate, parseDateTime, parseAbsolute, parseAbsoluteToLocal, fromAbsolute, fromDate, getLocalTimeZone, toTimeZone, toZoned } from '@internationalized/date';
 const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
 // Trailing `Z`, or a `+HH`, `+HH:MM`, `+HHMM` offset.
 const HAS_OFFSET = /(?:[zZ]|[+-]\d{2}(?::?\d{2})?)$/;
@@ -62,3 +62,50 @@ export function fromDateValue(value, shape, timeZone) {
         return dateValueToDate(value, timeZone);
     return value;
 }
+/**
+ * Read any date-ish value — a `DateValue`, ISO/DB string, native `Date` or epoch-millisecond
+ * number — the way it should be shown in `timeZone`. Never throws: anything unparseable
+ * (including an out-of-range date like `2024-02-30`) is `null`.
+ *
+ * - `"2024-03-15"` and `CalendarDate` stay calendar dates. They are never turned into an
+ *   instant, which would put them on the previous day in zones west of UTC.
+ * - `Date`, epoch numbers, offset strings (`Z`, `+02:00`) and `ZonedDateTime` are instants,
+ *   converted into `timeZone`.
+ * - A datetime without an offset (`"2024-03-15T10:30"`, `CalendarDateTime`) is a wall-clock
+ *   time in `timeZone`.
+ */
+export function readDateInZone(value, timeZone) {
+    try {
+        return readDate(value, timeZone);
+    }
+    catch {
+        return null;
+    }
+}
+function readDate(value, timeZone) {
+    if (value == null)
+        return null;
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : fromDate(value, timeZone);
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? fromAbsolute(value, timeZone) : null;
+    }
+    if (value instanceof ZonedDateTime)
+        return toTimeZone(value, timeZone);
+    if (value instanceof CalendarDateTime)
+        return toZoned(value, timeZone);
+    if (value instanceof CalendarDate)
+        return value;
+    if (typeof value !== 'string')
+        return null;
+    const raw = value.trim();
+    if (!raw)
+        return null;
+    if (DATE_ONLY.test(raw))
+        return parseDate(raw);
+    const iso = normalizeIso(raw);
+    return HAS_OFFSET.test(iso)
+        ? parseAbsolute(iso, timeZone)
+        : toZoned(parseDateTime(iso), timeZone);
+}

package/dist/utils/release-focus-on-exit.d.ts

@@ -0,0 +1,22 @@
+declare function releaseFocusOnExit(event: Event): void;
+/**
+ * Spread onto Ark overlay content (popover, dialog, drawer) so a field focused inside it blurs
+ * before the content unmounts, not during the unmount.
+ *
+ * Zag's presence can unmount content from inside a Svelte effect (it does when the document is
+ * hidden). Svelte then removes the content mid-flush; a field still focused in there blurs during
+ * that removal, and zag handles some blurs with `flushSync` (DatePicker's machine, for one). That
+ * nested `flushSync` breaks the outer flush: "Cannot read properties of null (reading 'clear')"
+ * in Svelte's `flush_queued_effects` (still the case in svelte 5.57.2).
+ *
+ * Zag dispatches `exitcomplete` on the content node once presence decides to unmount, before
+ * Svelte removes it. Blurring there lets the field commit on blur as usual, at a point where a
+ * nested `flushSync` is safe. Usually focus is already back on the trigger by then (exit
+ * animations outlast the focus restore), and this does nothing.
+ *
+ * A spread because Ark's content prop types don't list the `exitcomplete` event.
+ */
+export declare const releaseFocusOnExitProps: {
+    onexitcomplete: typeof releaseFocusOnExit;
+};
+export {};

package/dist/utils/release-focus-on-exit.js

@@ -0,0 +1,26 @@
+function releaseFocusOnExit(event) {
+    const content = event.currentTarget;
+    if (!(content instanceof HTMLElement))
+        return;
+    const active = content.ownerDocument.activeElement;
+    if (active instanceof HTMLElement && content.contains(active))
+        active.blur();
+}
+/**
+ * Spread onto Ark overlay content (popover, dialog, drawer) so a field focused inside it blurs
+ * before the content unmounts, not during the unmount.
+ *
+ * Zag's presence can unmount content from inside a Svelte effect (it does when the document is
+ * hidden). Svelte then removes the content mid-flush; a field still focused in there blurs during
+ * that removal, and zag handles some blurs with `flushSync` (DatePicker's machine, for one). That
+ * nested `flushSync` breaks the outer flush: "Cannot read properties of null (reading 'clear')"
+ * in Svelte's `flush_queued_effects` (still the case in svelte 5.57.2).
+ *
+ * Zag dispatches `exitcomplete` on the content node once presence decides to unmount, before
+ * Svelte removes it. Blurring there lets the field commit on blur as usual, at a point where a
+ * nested `flushSync` is safe. Usually focus is already back on the trigger by then (exit
+ * animations outlast the focus restore), and this does nothing.
+ *
+ * A spread because Ark's content prop types don't list the `exitcomplete` event.
+ */
+export const releaseFocusOnExitProps = { onexitcomplete: releaseFocusOnExit };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "compote-ui",
-	"version": "0.79.2",
+	"version": "0.81.0",
 	"license": "MIT",
 	"repository": {
 		"type": "git",

package/skills/component-usage/references/overlays-and-floating-ui.md

@@ -183,8 +183,13 @@ Composable floating panel anchored to a trigger.
 </Popover.Root>
 ```
 
-`Popover.Content` accepts `showArrow?: boolean` (default `true`). Control placement via
-`<Popover.Root positioning={{ placement: 'right' }}>`.
+`Popover.Content` accepts `showArrow?: boolean` (default `true`) and forwards other props to Ark's
+`Popover.Content`. Control placement via `<Popover.Root positioning={{ placement: 'right' }}>`.
+
+The dialog is labelled automatically: while a `Popover.Title` / `Popover.Description` is rendered
+inside, `Popover.Content` gets `aria-labelledby` / `aria-describedby` pointing at it — no `ids` or
+manual `aria-*` needed (Zag alone misses them because content mounts lazily). An explicit
+`aria-labelledby` / `aria-describedby` (or `aria-label`, for the title) on `Popover.Content` wins.
 
 ## HoverCard
 

package/skills/data-table/SKILL.md

@@ -8,7 +8,7 @@ description: >
 metadata:
   type: composition
   library: compote-ui
-  library_version: '0.79.2'
+  library_version: '0.81.0'
 requires:
   - component-usage
   - theming
@@ -20,6 +20,13 @@ sources:
   - src/lib/components/data-table-v9/column-helper.ts
   - src/lib/components/data-table-v9/create-table.svelte.ts
   - src/lib/components/data-table-v9/data-table.svelte
+  - src/lib/components/data-table-v9/data-table-head.svelte
+  - src/lib/components/data-table-v9/header/column-header-filter.svelte
+  - src/lib/components/data-table-v9/column-filter-kind.ts
+  - src/lib/components/data-table-v9/filter-editors/column-filter-editor.svelte
+  - src/lib/components/data-table-v9/column-filter-editing.svelte.ts
+  - src/lib/utils/select-filter.ts
+  - src/lib/utils/date-filter.ts
   - src/lib/components/data-table-v9/virtual/data-table-virtualized.svelte
   - src/lib/components/data-table-v9/virtual/data-table-virtual-rows.svelte
 ---
@@ -162,6 +169,78 @@ shows the active filter count as a badge in the corner either way.
 <DataTable.ColumnVisibility {table} triggerLabel="Columns" />
 ```
 
+### Filter from column headers
+
+Pass `headerFilters` to `DataTable.Root` / `VirtualDataTable.Root` to put a funnel in the header
+of every filterable leaf column (not group headers, not `enableColumnFilter: false`, never
+`type: 'action'`). The funnel shows on header hover/focus (always on touch screens); once the
+column is filtered it stays visible, filled and in the primary color. Clicking it opens a popup
+titled with the column name, with a "Clear" button and the editor for the column's type:
+
+| Column `type`                       | Popup editor                           | Filter value                     |
+| ----------------------------------- | -------------------------------------- | -------------------------------- |
+| `number`, `currency`, `percent`     | From / To number inputs                | `[min?, max?]` (`inNumberRange`) |
+| `boolean`                           | All / Yes / No                         | `true` / `false`                 |
+| `select`                            | Search + checkbox list with row counts | array of options                 |
+| `date`, `date-time`                 | From / To date pickers                 | `[from?, to?]` as `YYYY-MM-DD`   |
+| anything else (`text`, `time`, ...) | Text search                            | string                           |
+
+Edits apply immediately (text and number inputs after a 300ms debounce — also when the popup
+closes first). The header popups and `DataTable.ColumnFilter` edit the same table state, so a
+filter set in one shows in the other. `headerFilters` is opt-in and defaults to `false`.
+
+```svelte
+<div class="h-96 min-h-0">
+	<DataTable.Root {table} caption="Invoices" headerFilters />
+</div>
+```
+
+### Build your own filter UI
+
+For filter controls outside the toolbar and header popups (a facet panel beside the table, a
+filter sidebar), use the same building blocks the Funnel uses. They read and write the table's
+column filters, so the Funnel, header funnels and your UI always show the same state.
+
+- `ColumnFilterEditor` — the Funnel's editor for one column, picked by its type (see the table in
+  "Filter from column headers"). Pass `editing` only if the editor can be torn down while it holds
+  a pending text/range edit (see below); without it the editor uses one bound to the column's table.
+- `ColumnFilterEditing` — the debounced text/range edits pending on a table, shared by every host.
+  `isActive(columnId)` lets a host refuse writes from an editor it has already dropped (Ark's
+  NumberInput commits on the blur its unmount triggers).
+- `getColumnFilterKind(column)` / `filterKindFor(type)` — the column's `ColumnFilterKind`
+  (`range`, `boolean`, `select`, `date` or `text`), or `null` for columns that never filter.
+- `selectFilterOptions(column.getFacetedUniqueValues())` — a select column's options with row
+  counts, sorted by label, "(empty)" last with value `EMPTY_SELECT_VALUE` (`null`). Counts are
+  cross-filtered: every other active filter applies, the column's own does not.
+- `getColumnLabel(column)` and the `DataTableColumnInstance<T>` type for the columns you list.
+
+```svelte
+<script lang="ts">
+	import * as DataTable from 'compote-ui/data-table';
+
+	let { table }: { table: DataTable.DataTableInstance<Product> } = $props();
+
+	const facets = $derived(
+		table
+			.getAllLeafColumns()
+			.filter((column) => column.getCanFilter() && DataTable.getColumnFilterKind(column))
+	);
+</script>
+
+{#each facets as column (column.id)}
+	<h3>{DataTable.getColumnLabel(column)}</h3>
+	<DataTable.ColumnFilterEditor {column} />
+{/each}
+```
+
+A custom select list writes the same value the Funnel does — an array of options, `undefined`
+when none is ticked:
+
+```ts
+const selected = (column.getFilterValue() as DataTable.SelectFilterValue[] | undefined) ?? [];
+column.setFilterValue(next.length ? next : undefined);
+```
+
 ### Add a refresh button
 
 `DataTable.Refresh` is data-source agnostic: it calls `onRefresh` and, if that returns a promise,

package/skills/data-table/references/column-options.md

@@ -58,6 +58,29 @@ Type defaults:
 
 Use one `grow: true` column to absorb extra horizontal space.
 
+## Date columns: display and filter
+
+`date`, `time` and `date-time` cells are read the same way for display and for the date filter,
+in the column's display zone — `formatOptions.timeZone` when set, otherwise the viewer's local
+zone:
+
+- `'2024-03-15'` (and a `CalendarDate`) is a calendar day. It always shows and filters as
+  15 March, also in zones west of UTC — it is never turned into a midnight-UTC instant.
+- `Date`, epoch milliseconds, strings with an offset (`Z`, `+02:00`, DB `+02`) and
+  `ZonedDateTime` are instants, shown and filtered on the day they fall on in the display zone.
+- A datetime without an offset (`'2024-03-15T10:30'`) is wall-clock time in the display zone.
+- Unreadable values (e.g. `'2024-02-30'`) render as `-` and never match an active filter.
+
+`date` and `date-time` columns filter by calendar-day range. The filter value is
+`[from?, to?]`, each `YYYY-MM-DD` or empty (open-ended); both days are inclusive, a reversed
+range is swapped, and an empty range removes the filter. Instants are judged by their calendar
+day, so 23- and 25-hour DST days need no special handling. `time` columns keep the text filter.
+
+```ts
+table.getColumn('createdAt')?.setFilterValue(['2024-03-01', '2024-03-31']); // March
+table.getColumn('createdAt')?.setFilterValue([undefined, '2024-03-31']); // up to 31 March
+```
+
 ## Select columns with multiple values
 
 A `type: 'select'` column may return an array (tags, multi-select attributes). The Funnel then
@@ -134,6 +157,8 @@ booleans and object-valued columns are excluded from global search. Also availab
 
 `table: DataTableInstance<T>` (required), `caption?: string` (sr-only `<caption>`),
 `emptyMessage?: string` (default `'No rows found'`), `class?: ClassValue`,
+`headerFilters?: boolean` (default `false`; funnel filter popups in column headers — see
+"Filter from column headers" in SKILL.md),
 `onRowClick?: (details: { row: T; event: MouseEvent }) => void`,
 `onRowDoubleClick?: (details: { row: T; event: MouseEvent }) => void` — `row` is `row.original`.
 Clicks on the row-selection checkbox and url-cell buttons do **not** trigger either handler.

package/skills/data-table/references/table-state-and-reactivity.md

@@ -29,14 +29,19 @@ const filters = $derived(table.store.state.columnFilters);
 ```
 
 Change filters from app code with the table API — `column.setFilterValue(...)`,
-`table.setColumnFilters(...)`, `table.resetColumnFilters()`. `DataTable.ColumnFilter` shows the
-live filter value in its inputs (it only holds edits still inside the 300ms debounce), so an
-external change clears or updates the inputs, and editing one range bound keeps the other
-bound's current value. An edit still inside the debounce is dropped when its column's filter
-changes from outside — even if the filter ends on its old value again (e.g. reset, then saved
-filters restored), since `createTable` keeps a per-column filter revision that only goes up. A
-reset that finds the filter already empty changes nothing (TanStack keeps the state reference),
-so an edit typed into that empty filter still commits.
+`table.setColumnFilters(...)`, `table.resetColumnFilters()`. `DataTable.ColumnFilter` and the
+`headerFilters` popups show the live filter value in their inputs (they only hold edits still
+inside the 300ms debounce), so an external change clears or updates the inputs, and editing one
+range bound keeps the other bound's current value. An edit still inside the debounce is dropped
+when its column's filter changes from outside — even if the filter ends on its old value again
+(e.g. reset, then saved filters restored), since `createTable` keeps a per-column filter revision
+that only goes up.
+
+Pending edits belong to the table, not to the control they were typed in: the latest edit to a
+column wins whether it came from a header popup or the toolbar, and it still commits after its
+popup closes. `table.resetColumnFilters()` and `table.reset()` cancel every pending edit — also
+one typed into a column that had no filter yet, which a reset would otherwise leave untouched —
+and so does destroying the component that created the table.
 
 ```ts
 // e.g. drop every filter on columns that belong to the previous category