@viniaraujo68/plinth 0.3.1 → 0.6.0

package/README.md

@@ -169,6 +169,16 @@ theme context. `AppShell` fills its parent, so give it one with a height. Its na
 titled first-level routes that have a page of their own; a titled route with no page stays a heading
 in the breadcrumb trail and is left out of the navigation, which has nothing to link it to.
 
+One level of nesting is read off the same tree: a first-level route whose children are titled,
+static and have pages of their own becomes a **group**, a header that folds those children away.
+It opens by itself when the current page is inside it and then stays wherever the reader leaves it;
+the group's own page, when it has one, leads the fold under `overviewLabel` ("Overview"). Children
+go through the same role gate as everything else, and a group left with no children in scope falls
+back to a plain entry — or vanishes, when it has no page either. In the collapsed rail a group is
+its icon, and clicking it expands the sidebar onto the open group. On the bottom bar a group with a
+page takes a slot and links there, one without takes none, and every group's children go into the
+"More" sheet under its heading. Routes with no such children render exactly as before.
+
 An app that cannot render the controller in the right state on the server — a prerendered site, a
 client-only app — usually stamps `data-theme="plinth-light"` or `data-theme="plinth-dark"` on
 `<html>` from a head script, so the very first paint is already right. That stamp is a **seed for
@@ -251,36 +261,79 @@ arrangement across reloads. `createFormatters` decides the
 locale once, and `createHttpClient` takes the three things that actually differ between apps — the
 base URL, how auth is injected, and how the backend spells an error body.
 
+Work the reader waits on goes through **`toast.promise`**: a spinning `loading` toast that turns into
+a success or an error in place once the work settles. It never rejects — it resolves to the value,
+or to `undefined` on failure — and hands the failure to `onerror`, or to `reportError` when none is
+given, the same rule `AsyncButton` follows. `toast.update(id, patch)` changes a live toast in place.
+
+```ts
+const saved = await toast.promise(api.post("/orders", draft), {
+  loading: "Saving…",
+  success: (order) => `Order ${order.id} saved.`,
+  error: (error) => errorMessage(error),
+});
+```
+
+A request that failed in the page rather than in a toast renders **`RequestErrorDisplay`**, which
+sorts the error with **`classifyError`** — offline, unauthorized, forbidden, not found, server or
+unknown — and gives each kind its own icon and wording, all of it overridable through `labels`. It
+never rethrows, so an `{:catch error}` branch that renders it is safe on the server too.
+
 ## Entry points
 
-| Import                             | What it carries                                                                                            |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `@viniaraujo68/plinth`             | `AsyncAction`, the error reporter, `LIBRARY_VERSION`                                                       |
-| `@viniaraujo68/plinth/theme`       | `ThemeContext`, `ThemeController`, `ThemeToggle`, the cookie helpers, `createCssColorReader`               |
-| `@viniaraujo68/plinth/theme.css`   | The stylesheet the tokens are declared in                                                                  |
-| `@viniaraujo68/plinth/attachments` | The `tooltip` attachment, usable on any tag, and `sortable`, which reorders a list from its drag handles   |
-| `@viniaraujo68/plinth/components`  | The primitives, the `DateRange` and option-matching helpers                                                |
-| `@viniaraujo68/plinth/confirm`     | `confirm`, `Confirmer`, the challenge helpers                                                              |
-| `@viniaraujo68/plinth/shell`       | `AppShell`, `Breadcrumbs`                                                                                  |
-| `@viniaraujo68/plinth/table`       | `DataTable`, the sorting and column-layout functions behind it, `competitionRanks`, the sort ↔ URL helpers |
-| `@viniaraujo68/plinth/toast`       | The toast queue and its host                                                                               |
-| `@viniaraujo68/plinth/routing`     | `RoutingConfig`, `RoutingContext`, `resolvePathname`, `withSearchParams`                                   |
-| `@viniaraujo68/plinth/user`        | `UserContext`, `ScopedComponent`, the anonymous default                                                    |
-| `@viniaraujo68/plinth/http`        | `createHttpClient`, `ApiError`, `errorMessage`, `errorStatus`                                              |
-| `@viniaraujo68/plinth/formatters`  | `createFormatters`, over `Intl`                                                                            |
+| Import                             | What it carries                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `@viniaraujo68/plinth`             | `AsyncAction`, the error reporter, `LIBRARY_VERSION`                                                         |
+| `@viniaraujo68/plinth/theme`       | `ThemeContext`, `ThemeController`, `ThemeToggle`, the cookie helpers, `createCssColorReader`                 |
+| `@viniaraujo68/plinth/theme.css`   | The stylesheet the tokens are declared in                                                                    |
+| `@viniaraujo68/plinth/attachments` | The `tooltip` attachment, usable on any tag, and `sortable`, which reorders a list from its drag handles     |
+| `@viniaraujo68/plinth/components`  | The primitives, the `DateRange` and option-matching helpers                                                  |
+| `@viniaraujo68/plinth/confirm`     | `confirm`, `Confirmer`, the challenge helpers                                                                |
+| `@viniaraujo68/plinth/shell`       | `AppShell`, `TopBar`, `Breadcrumbs`, `NavigationProgress`                                                    |
+| `@viniaraujo68/plinth/table`       | `DataTable`, the sorting and column-layout functions behind it, `competitionRanks`, the sort ↔ URL helpers   |
+| `@viniaraujo68/plinth/toast`       | The toast queue, `toast.loading`, `toast.promise`, `toast.update`, and its host                              |
+| `@viniaraujo68/plinth/routing`     | `RoutingConfig`, `RoutingContext`, `resolvePathname`, `withSearchParams`, `safeNext`, `loginUrl`, `withNext` |
+| `@viniaraujo68/plinth/user`        | `UserContext`, `ScopedComponent`, the anonymous default                                                      |
+| `@viniaraujo68/plinth/http`        | `createHttpClient`, `ApiError`, `errorMessage`, `errorStatus`, `classifyError`                               |
+| `@viniaraujo68/plinth/formatters`  | `createFormatters`, over `Intl`                                                                              |
+| `@viniaraujo68/plinth/i18n`        | `createI18n`, `LocaleToggle`, the interpolation and plural helpers                                           |
+| `@viniaraujo68/plinth/virtual`     | `Virtualizer`, `VirtualList`, `WindowedData`, `WindowedVirtualizer`, `DataList`                              |
+| `@viniaraujo68/plinth/url-state`   | `createUrlState`, `urlStore`, `SyncedState`, `createParamsCodec` and `param`, the codec contracts            |
 
 The components entry point ships `AsyncButton`, `Combobox`, `Copyable`, `DateRangePicker`,
-`Dialog`, `DragHandle`, `Dropdown`, `ErrorDisplay`, `ErrorPage`, `JsonInput`, `Listbox`, `LoadingButton`, `Logo`,
-`Modal`, `MultiSelect`, `Paginator`, `RefreshButton`, `SegmentedControl`, `Select`, `Skeleton` and
-`Tooltip`. Every one of them has a page in the showcase.
+`Dialog`, `DragHandle`, `Dropdown`, `ErrorDisplay`, `ErrorPage`, `JsonInput`, `JsonView`, `Listbox`, `LoadingButton`, `Logo`,
+`Modal`, `MultiSelect`, `Paginator`, `RefreshButton`, `RequestErrorDisplay`, `SegmentedControl`, `Select`, `Skeleton`, `Tabs`,
+`VirtualJsonView`
+and `Tooltip`. Every one of them has a page in the showcase.
 It also exports the mark's outline as data — `PICK_PATH` and `PICK_CLIP_PATH` — for anything
-that wants the pick as a silhouette of its own.
+that wants the pick as a silhouette of its own. Not for avatars: the shell draws a profile picture as
+a disc, and an app's should be one too.
+
+**`Tabs`** switches what one panel shows: a `tablist` with a roving tabindex, where the arrow keys,
+Home and End move the selection and the selection follows the focus. It scrolls sideways on a phone
+instead of wrapping, fading at the edge while tabs are hidden past it. `value` is bindable; a page
+that keeps its section in the URL passes it in and navigates on `onchange`, and `idPrefix` makes the
+tab ids predictable so the panel can name its tab through `aria-labelledby`.
+
+`DateRangePicker` picks a from/to pair from presets or two typed fields. By default it is a window
+of instants — presets are durations back from now ("24h"), the fields are local date-times and the
+pair goes out as UTC ISO strings. With `mode="date"` it is a span of calendar days: the fields are
+date fields, the pair is `YYYY-MM-DD`, and an empty end leaves that side open, so "since March" and
+"all time" are pairs too. Presets can follow the calendar instead of a duration — `thisMonth`,
+`lastMonth`, `lastMonths(n)` and `allTime` build the usual ones, and any `range(now)` function will
+do. Every preset re-anchors on a timer, and a picker handed a pair opens on the preset that names it.
 
 `JsonInput` edits a JSON document as text: it reports through a bindable `invalid` whether the text
 parses, shows the parser's message after the first blur, can reindent on blur, and sets the
 textarea's custom validity so a form will not submit a broken document. `parseJsonText` and
 `formatJsonText` are the same rules, for reading the text once it is sent.
 
+`JsonView` shows a value read-only, as `JSON.stringify(value, null, 2)` would print it: `toJSON` is
+honoured, so a `Date` shows as its ISO string, and a reference back to an ancestor shows a marker
+instead of recursing. Nodes fold one by one, all at once or from `collapseDepth` down; the search
+(Ctrl/Cmd+F while the viewer has the focus) reaches inside folds and unfolds what it lands on; and
+copying — the whole document or a selection — writes the expanded text, never the fold summaries.
+
 Two of those pick one thing from a list, and which one to reach for is decided by the length of
 the list rather than by a flag:
 
@@ -337,6 +390,131 @@ Enter confirms only once it matches. The library ships no translations, so `conf
 `cancelLabel`, `closeLabel` and `challengeLabel` on the host translate every confirm at once, and
 any call overrides them through its own options.
 
+## Top bar, progress line and the sign-in round trip
+
+`AppShell` is built for an app with a navigation to show. One with two or three pages and an
+account puts **`TopBar`** over the page instead: the brand at the start, the app's controls at the
+end, and — once the user context says someone is signed in — their avatar, opening an account menu
+with their name, the app's own `<li>` entries and signing out. Choosing an entry closes the menu,
+and `--plinth-top-bar-width` caps the bar's content to the width of the page under it.
+
+```svelte
+<TopBar menuLabel={t("nav.accountMenu")} logoutLabel={t("nav.logout")}>
+  {#snippet brand()}<a href="/">Acme</a>{/snippet}
+  {#snippet actions()}
+    <LocaleToggle {i18n} label={t("nav.language")} />
+    <ThemeToggle iconOnly />
+  {/snippet}
+  {#snippet menu()}<li><a href="/account">{t("nav.account")}</a></li>{/snippet}
+</TopBar>
+```
+
+**`NavigationProgress`** goes with either shell: a line across the top of the window while a
+navigation takes longer than `delay` (150ms). The library imports nothing from SvelteKit, so the app
+says when one is under way — `<NavigationProgress active={navigating.to !== null} />`.
+
+The routing entry point also carries the `?next=` round trip of a sign-in page. A guard sends a
+visitor to **`loginUrl(page.url)`** — `/login?next=/where/they/were`, path only, since the query
+string is where share tokens live. The sign-in page reads the parameter back through
+**`safeNext`**, which keeps it only if the browser would resolve it to the same site:
+`//evil.example`, `/\evil.example` and the spellings the URL parser turns into them come back
+`null`, so a crafted link cannot send someone who just typed their password elsewhere.
+**`withNext`** carries the same path across the link between sign-in and sign-up.
+
+## Languages
+
+`@viniaraujo68/plinth/i18n` is for the app's own text — the library still ships no translations,
+and its components keep taking every word through props. **`createI18n`** takes a flat dictionary
+per locale and returns the current locale as `$state`, a `t()` that reads it, and `tag`, the BCP 47
+tag for `Intl`:
+
+```ts
+// src/lib/i18n.svelte.ts
+import { createI18n } from "@viniaraujo68/plinth/i18n";
+import pt from "./i18n/pt.js";
+import en from "./i18n/en.js";
+
+export const i18n = createI18n({
+  dictionaries: { pt, en },
+  tags: { pt: "pt-BR", en: "en-US" },
+  fallback: "pt",
+  unmatched: "en",
+  storageKey: "acme.locale",
+});
+export const { t } = i18n;
+```
+
+`t("days", { count: 3 })` fills `{count}` and picks between a `{ one, other }` pair — exactly one
+takes `one`, everything else, zero included, takes `other`, which is not what CLDR says for
+Portuguese and is what its readers expect. A key missing from the current dictionary is read from the
+fallback one. The first visit starts on the browser's language, matched by language when the region
+differs, or on `unmatched` when nothing matches; a later one starts on the pick
+**`LocaleToggle`** remembered. Switching relabels `<html lang>` too. The server renders the fallback
+locale and never switches — the instance is shared by every request — and the browser corrects the
+text during hydration.
+
+## URL state
+
+`@viniaraujo68/plinth/url-state` keeps a screen's filters, sorting and paging in the query string,
+so a link reopens what its sender was looking at and the back button undoes a search. It is state,
+not a query layer: nothing in it fetches or caches.
+
+```svelte
+<script lang="ts">
+  import { createParamsCodec, createUrlState, param } from "@viniaraujo68/plinth/url-state";
+
+  const catalog = createParamsCodec({
+    q: param.string({ default: "" }),
+    sort: param.string({ oneOf: ["asc", "desc"], default: "asc" }),
+    tags: param.list(param.string()),
+    page: param.number({ default: 1, min: 1, integer: true }),
+  });
+
+  const filters = createUrlState(catalog, { resetOnCommit: ["page"] });
+</script>
+
+<input bind:value={filters.draft.q} />
+<button disabled={!filters.isDirty} onclick={filters.commit}>Apply</button>
+<button onclick={() => filters.update((s) => ({ ...s, page: s.page + 1 }))}>Next</button>
+```
+
+A form edits **`draft`**; **`commit()`** normalizes it into **`committed`** and writes the owned
+params to the URL, leaving every other param alone. **`update(fn)`** commits one change eagerly —
+a page turn — without dragging half-typed filters along; **`revert()`** drops the draft's edits and
+**`reset()`** returns both to the defaults. **`resetOnCommit`** names the fields that go back to
+their defaults whenever a commit changes anything else, which is what returns a new search to page 1.
+A URL change that does not change **`key()`** — a foreign param, a reorder — is ignored, so it never
+clobbers a draft; a real one, such as the back button, replaces both halves and calls `onSynced`.
+
+The handlers never throw on a hand-edited URL: a value they cannot read falls back to the field's
+default — `number` rejects `NaN` and empty values and honours `min`, `max` and `integer`, `boolean`
+takes only `"true"` and `"false"`, `date` reads `YYYY-MM-DD` as local midnight and refuses
+impossible days, and an invalid `Date` is never written. A value equal to its default stays out of
+the URL. `list` reads a repeated param, and its default is always the empty list.
+
+Every commit is a `goto` with focus and scroll kept, and pushes a history entry. **`replace`**
+rewrites the current entry instead — `true` for search-as-you-type, or a function of the previous
+and next owned params, where `changedParams` helps:
+`replace: (prev, next) => changedParams(prev, next).every((name) => name === "q")`. Several states
+on one page can commit in the same tick; the writes merge into one navigation.
+
+Create it while a component initializes: it follows the URL through an `$effect`. Effects do not
+run on the server, so a server-rendered or prerendered page renders the defaults and picks up the
+URL once it hydrates. A page whose first paint has to reflect the query string reads it in its own
+`load` and is not prerendered.
+
+`key()` is what a fetch is keyed by. With TanStack Query it goes straight into the key:
+
+```ts
+const books = createQuery(() => ({
+  queryKey: ["books", filters.key()],
+  queryFn: () => api.get(`/books?${catalog.serialize(filters.normalized())}`),
+}));
+```
+
+`SyncedState` works without the URL too, and takes any `ExternalStore` — `read`, `write` and a
+`subscribe` that must not call back synchronously — for state kept somewhere else.
+
 ## Development
 
 ```sh

package/dist/components/DateRangePicker.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { untrack } from "svelte";
   import type { ClassValue } from "svelte/elements";
+  import SegmentedControl from "./SegmentedControl.svelte";
   import {
     anchorSelection,
     buildRange,
@@ -8,27 +9,38 @@
     CUSTOM_PRESET_ID,
     DEFAULT_PRESETS,
     isoToLocalInput,
+    isValidDayRange,
     isValidRange,
     localInputToIso,
+    parseDay,
+    selectionFor,
     type DateRange,
+    type DateRangeMode,
     type DateRangePreset,
   } from "./date-range.js";
 
   interface Props {
     class?: ClassValue;
     /**
-     * The selected window, as UTC ISO instants. Bindable, and also reported through
-     * {@link Props.onchange} — a consumer needs one or the other, never both.
+     * `"datetime"` (the default) picks a window of instants, emitted as UTC ISO strings, with
+     * date-and-time fields. `"date"` picks a span of calendar days, emitted as `YYYY-MM-DD`, with
+     * date fields either of which may stay empty to leave that side open.
+     */
+    mode?: DateRangeMode;
+    /**
+     * The selected window — UTC ISO instants, or days in `"date"` mode. Bindable, and also reported
+     * through {@link Props.onchange} — a consumer needs one or the other, never both.
      *
      * It is an output, not an input: a relative preset overwrites it on every anchor. Passing one
-     * in only seeds the picker, and only alongside `preset="custom"`.
+     * in only seeds the picker: it opens on the preset that names that window right now, or on
+     * custom with the pair in the fields.
      */
     value?: DateRange;
     /** The buttons offered. `id` may not be `"custom"`, which the picker reserves. */
     presets?: readonly DateRangePreset[];
     /**
-     * Which button starts selected — a preset id, or `"custom"`. Defaults to the first preset, or
-     * to custom when `value` was seeded without naming a preset.
+     * Which button starts selected — a preset id, or `"custom"`. Defaults to the preset matching a
+     * seeded `value`, to custom when none does, and to the first preset when there is no `value`.
      */
     preset?: string;
     /**
@@ -56,6 +68,7 @@
 
   let {
     class: cls,
+    mode = "datetime",
     value = $bindable(),
     presets = DEFAULT_PRESETS,
     preset,
@@ -76,7 +89,13 @@
   // The selection is the picker's own state rather than a bound prop: the pair is the entire
   // output, and a second bound value would be a second thing for a consumer to keep in step.
   let selection = $state(
-    untrack(() => preset ?? (value ? CUSTOM_PRESET_ID : (presets[0]?.id ?? CUSTOM_PRESET_ID))),
+    untrack(
+      () =>
+        preset ??
+        (value
+          ? selectionFor(value, presets, Date.now(), mode)
+          : (presets[0]?.id ?? CUSTOM_PRESET_ID)),
+    ),
   );
 
   // Wall-clock text for the two fields. Empty until custom mode is entered, because reading the
@@ -86,6 +105,12 @@
   let customTo = $state("");
 
   const isCustom = $derived(selection === CUSTOM_PRESET_ID);
+  const days = $derived(mode === "date");
+
+  const options = $derived([
+    ...presets.map(({ id, label }) => ({ id, label })),
+    { id: CUSTOM_PRESET_ID, label: customLabel },
+  ]);
 
   const emit = (next: DateRange) => {
     if (value?.from === next.from && value?.to === next.to) return;
@@ -95,17 +120,37 @@
   };
 
   const anchor = () => {
-    const next = anchorSelection(selection, presets, Date.now());
+    const next = anchorSelection(selection, presets, Date.now(), mode);
     if (next) emit(next);
   };
 
   const seedCustomFields = (range: DateRange | undefined) => {
-    customFrom = isoToLocalInput(range?.from) ?? "";
-    customTo = isoToLocalInput(range?.to) ?? "";
+    const toField = days ? parseDay : isoToLocalInput;
+    customFrom = toField(range?.from) ?? "";
+    customTo = toField(range?.to) ?? "";
+  };
+
+  /**
+   * The typed pair, read back: `undefined` while either field is not yet a value — half typed —
+   * and otherwise the pair with whether it is in order. In `"date"` mode an empty field is a value,
+   * an open end, where in `"datetime"` mode it is not yet one.
+   */
+  const typedPair = (): { range: DateRange; ordered: boolean } | undefined => {
+    if (days) {
+      const from = parseDay(customFrom);
+      const to = parseDay(customTo);
+      if (from === null || to === null) return undefined;
+      return { range: { from, to }, ordered: isValidDayRange(from, to) };
+    }
+
+    const from = localInputToIso(customFrom);
+    const to = localInputToIso(customTo);
+    if (from === null || to === null) return undefined;
+    return { range: { from, to }, ordered: isValidRange(from, to) };
   };
 
   const enterCustom = () => {
-    const current = value ?? (presets[0] ? buildRange(presets[0]) : undefined);
+    const current = value ?? (presets[0] ? buildRange(presets[0], Date.now(), mode) : undefined);
 
     seedCustomFields(current);
     selection = CUSTOM_PRESET_ID;
@@ -117,27 +162,26 @@
   };
 
   const commitCustom = () => {
-    const from = localInputToIso(customFrom);
-    const to = localInputToIso(customTo);
-
-    if (from === null || to === null || !isValidRange(from, to)) return;
-
-    emit({ from, to });
+    const pair = typedPair();
+    if (pair?.ordered) emit(pair.range);
   };
 
   const rangeError = $derived.by(() => {
     if (!isCustom) return null;
 
-    const from = localInputToIso(customFrom);
-    const to = localInputToIso(customTo);
-
     // A half-typed field is not yet wrong, so it says nothing rather than flashing an error at
     // someone who is still filling the form in.
-    if (from === null || to === null) return null;
+    const pair = typedPair();
+    if (pair === undefined) return null;
 
-    return isValidRange(from, to) ? null : invalidRangeLabel;
+    return pair.ordered ? null : invalidRangeLabel;
   });
 
+  const pick = (id: string) => {
+    if (id === CUSTOM_PRESET_ID) enterCustom();
+    else selection = id;
+  };
+
   $effect(() => {
     const intervalMs = reAnchorMs;
     if (selection === CUSTOM_PRESET_ID) return;
@@ -175,17 +219,21 @@
 
 <!--
 @component
-A from/to picker built as a plain form control: relative presets, a custom pair of local
-date-times, and `{ from, to }` as UTC ISO strings on the way out. It fetches nothing, knows no
-query parameter, and reads no URL — what the pair means is the consumer's business.
-
-A relative preset re-anchors on a timer (`reAnchorMs`, 60s by default, `0` to disable), so a
-dashboard left open keeps sliding forward. The timer suspends while the tab is hidden and fires
-once on return. A custom range is never touched by it.
-
-The two custom fields are `<input type="datetime-local">`, which means they are wall-clock time in
-the viewer's own zone with no offset attached, while the emitted pair stays in UTC. The conversion
-runs to whole minutes in both directions; see `isoToLocalInput` / `localInputToIso`.
+A from/to picker built as a plain form control: presets, a custom pair the reader types, and
+`{ from, to }` on the way out. It fetches nothing, knows no query parameter, and reads no URL — what
+the pair means is the consumer's business.
+
+It works in one of two modes. `"datetime"`, the default, is a window of instants: the custom
+fields are `<input type="datetime-local">`, wall-clock time in the viewer's own zone, while the
+emitted pair stays in UTC — the conversion runs to whole minutes in both directions; see
+`isoToLocalInput` / `localInputToIso`. `"date"` is a span of calendar days: the fields are
+`<input type="date">`, the pair is `YYYY-MM-DD`, and an empty end leaves that side open.
+
+A preset is a duration back from now ("24h") or a window computed from the calendar ("this month",
+built with `thisMonth`, `lastMonth`, `lastMonths` and `allTime`). Either re-anchors on a timer
+(`reAnchorMs`, 60s by default, `0` to disable), so a dashboard left open keeps sliding forward and
+"this month" turns into the next one. The timer suspends while the tab is hidden and fires once on
+return. A custom range is never touched by it.
 
 Every word it renders is a prop with an English default — `label`, `customLabel`, `fromLabel`,
 `toLabel` and `invalidRangeLabel` — because the library ships no translations. Only the wording
@@ -194,33 +242,19 @@ buttons are labelled by the list itself, through `DateRangePreset.label`.
 
 ```svelte
 <DateRangePicker bind:value={range} preset="24h" onchange={(r) => load(r)} />
+
+<DateRangePicker
+  mode="date"
+  presets={[allTime("All time"), thisMonth("This month"), lastMonth("Last month")]}
+  onchange={(r) => load(r)}
+/>
 ```
 -->
 
 <div class={["flex flex-wrap items-end gap-x-4 gap-y-3", cls]}>
-  <div class="join" role="group" aria-label={label}>
-    {#each presets as option (option.id)}
-      <button
-        type="button"
-        class="btn join-item min-h-11"
-        class:btn-primary={selection === option.id}
-        aria-pressed={selection === option.id}
-        onclick={() => (selection = option.id)}
-      >
-        {option.label}
-      </button>
-    {/each}
-
-    <button
-      type="button"
-      class="btn join-item min-h-11"
-      class:btn-primary={isCustom}
-      aria-pressed={isCustom}
-      onclick={enterCustom}
-    >
-      {customLabel}
-    </button>
-  </div>
+  <!-- A segmented control rather than a joined row: a calendar picker easily offers six windows,
+       and a joined row cannot wrap onto a second line at phone width. -->
+  <SegmentedControl {options} value={selection} {label} onchange={pick} />
 
   {#if isCustom}
     <div class="flex flex-wrap items-end gap-x-4 gap-y-3">
@@ -230,8 +264,9 @@ buttons are labelled by the list itself, through `DateRangePreset.label`.
           id={fromId}
           class="input min-h-11"
           class:input-error={rangeError !== null}
-          type="datetime-local"
+          type={days ? "date" : "datetime-local"}
           value={customFrom}
+          max={days && customTo ? customTo : undefined}
           aria-invalid={rangeError !== null}
           aria-describedby={rangeError === null ? undefined : errorId}
           oninput={({ currentTarget }) => {
@@ -247,8 +282,9 @@ buttons are labelled by the list itself, through `DateRangePreset.label`.
           id={toId}
           class="input min-h-11"
           class:input-error={rangeError !== null}
-          type="datetime-local"
+          type={days ? "date" : "datetime-local"}
           value={customTo}
+          min={days && customFrom ? customFrom : undefined}
           aria-invalid={rangeError !== null}
           aria-describedby={rangeError === null ? undefined : errorId}
           oninput={({ currentTarget }) => {

package/dist/components/DateRangePicker.svelte.d.ts

@@ -1,20 +1,27 @@
 import type { ClassValue } from "svelte/elements";
-import { type DateRange, type DateRangePreset } from "./date-range.js";
+import { type DateRange, type DateRangeMode, type DateRangePreset } from "./date-range.js";
 interface Props {
     class?: ClassValue;
     /**
-     * The selected window, as UTC ISO instants. Bindable, and also reported through
-     * {@link Props.onchange} — a consumer needs one or the other, never both.
+     * `"datetime"` (the default) picks a window of instants, emitted as UTC ISO strings, with
+     * date-and-time fields. `"date"` picks a span of calendar days, emitted as `YYYY-MM-DD`, with
+     * date fields either of which may stay empty to leave that side open.
+     */
+    mode?: DateRangeMode;
+    /**
+     * The selected window — UTC ISO instants, or days in `"date"` mode. Bindable, and also reported
+     * through {@link Props.onchange} — a consumer needs one or the other, never both.
      *
      * It is an output, not an input: a relative preset overwrites it on every anchor. Passing one
-     * in only seeds the picker, and only alongside `preset="custom"`.
+     * in only seeds the picker: it opens on the preset that names that window right now, or on
+     * custom with the pair in the fields.
      */
     value?: DateRange;
     /** The buttons offered. `id` may not be `"custom"`, which the picker reserves. */
     presets?: readonly DateRangePreset[];
     /**
-     * Which button starts selected — a preset id, or `"custom"`. Defaults to the first preset, or
-     * to custom when `value` was seeded without naming a preset.
+     * Which button starts selected — a preset id, or `"custom"`. Defaults to the preset matching a
+     * seeded `value`, to custom when none does, and to the first preset when there is no `value`.
      */
     preset?: string;
     /**
@@ -40,17 +47,21 @@ interface Props {
     onchange?: (value: DateRange) => void;
 }
 /**
- * A from/to picker built as a plain form control: relative presets, a custom pair of local
- * date-times, and `{ from, to }` as UTC ISO strings on the way out. It fetches nothing, knows no
- * query parameter, and reads no URL — what the pair means is the consumer's business.
+ * A from/to picker built as a plain form control: presets, a custom pair the reader types, and
+ * `{ from, to }` on the way out. It fetches nothing, knows no query parameter, and reads no URL — what
+ * the pair means is the consumer's business.
  *
- * A relative preset re-anchors on a timer (`reAnchorMs`, 60s by default, `0` to disable), so a
- * dashboard left open keeps sliding forward. The timer suspends while the tab is hidden and fires
- * once on return. A custom range is never touched by it.
+ * It works in one of two modes. `"datetime"`, the default, is a window of instants: the custom
+ * fields are `<input type="datetime-local">`, wall-clock time in the viewer's own zone, while the
+ * emitted pair stays in UTC — the conversion runs to whole minutes in both directions; see
+ * `isoToLocalInput` / `localInputToIso`. `"date"` is a span of calendar days: the fields are
+ * `<input type="date">`, the pair is `YYYY-MM-DD`, and an empty end leaves that side open.
  *
- * The two custom fields are `<input type="datetime-local">`, which means they are wall-clock time in
- * the viewer's own zone with no offset attached, while the emitted pair stays in UTC. The conversion
- * runs to whole minutes in both directions; see `isoToLocalInput` / `localInputToIso`.
+ * A preset is a duration back from now ("24h") or a window computed from the calendar ("this month",
+ * built with `thisMonth`, `lastMonth`, `lastMonths` and `allTime`). Either re-anchors on a timer
+ * (`reAnchorMs`, 60s by default, `0` to disable), so a dashboard left open keeps sliding forward and
+ * "this month" turns into the next one. The timer suspends while the tab is hidden and fires once on
+ * return. A custom range is never touched by it.
  *
  * Every word it renders is a prop with an English default — `label`, `customLabel`, `fromLabel`,
  * `toLabel` and `invalidRangeLabel` — because the library ships no translations. Only the wording
@@ -59,6 +70,12 @@ interface Props {
  *
  * ```svelte
  * <DateRangePicker bind:value={range} preset="24h" onchange={(r) => load(r)} />
+ *
+ * <DateRangePicker
+ * mode="date"
+ * presets={[allTime("All time"), thisMonth("This month"), lastMonth("Last month")]}
+ * onchange={(r) => load(r)}
+ * />
  * ```
  */
 declare const DateRangePicker: import("svelte").Component<Props, {}, "value">;