@viniaraujo68/plinth 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 viniaraujo68
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,362 @@
-# Temporary Holding Version
+# plinth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A personal Svelte 5 design system, built on Tailwind 4 and daisyUI 5: a theme, an application
+shell, interface primitives and the patterns around them — routing metadata, an identity seam, a
+fetch wrapper and locale-aware formatters.
+
+One package, one entry point per area, so an app that only wants a formatter never pays for a
+shell. The library lives in `src/lib` and is published with `svelte-package`; everything in
+`src/routes` is the showcase, a static site that doubles as the documentation and is never
+published.
+
+**Showcase:** <https://viniaraujo68.github.io/plinth>
+
+## Install
+
+```sh
+npm i @viniaraujo68/plinth
+```
+
+An unreleased commit installs straight from GitHub with `npm i github:viniaraujo68/plinth#<ref>`:
+npm runs the `prepare` script for a git dependency — and installs the dev dependencies needed to
+do it — so `svelte-package` builds `dist` on the consumer's machine. Both give you the same import
+specifiers, which are what every example below uses.
+
+The package declares `svelte` and `@sveltejs/kit` as peer dependencies; Tailwind 4 and daisyUI 5
+are the consumer's own, because the theme is a stylesheet the consumer imports rather than a
+bundle the library emits. The `svelte` floor is `^5.57.0`, and it is a real floor rather than a
+precaution: the user context is built on the `[get, set, has]` form of `createContext`, which
+5.56 does not have — there `has` is `undefined` and the first component that reads the context
+throws.
+
+## Setup
+
+### 1. The stylesheet
+
+The app owns its CSS chain. A SvelteKit app with its entry stylesheet at `src/routes/layout.css`:
+
+```css
+/* The theme first: it is plain unlayered CSS, so it outranks everything daisyUI emits into a
+   cascade layer, and its `@import url(...)` for the fonts has to reach the top of the bundle. */
+@import "@viniaraujo68/plinth/theme.css";
+
+/* Tailwind only scans this project's own files. The library's classes live in a package it never
+   looks at, so point it at the shipped `dist` — the path is relative to THIS file. */
+@source "../../node_modules/@viniaraujo68/plinth/dist";
+
+@import "tailwindcss";
+
+@plugin "daisyui" {
+  exclude: rootscrollgutter;
+}
+```
+
+Then import it once, from the root layout: `import "./layout.css";`.
+
+If the library is linked rather than installed (`npm link`, a workspace, a `file:` dependency),
+`@source` has to point at wherever the real `dist` ended up — a symlinked path is not scanned
+through.
+
+### 2. The Vite build target
+
+**This one is not optional.** Every color in the theme is declared once through `light-dark()`,
+and that is what makes `[data-theme]` on any element re-theme its subtree. Lightning CSS — which
+Vite runs to minify CSS — rewrites `light-dark()` into a pair of inherited guard variables
+whenever the configured target browsers predate it. The rewrite is not equivalent: the guards
+resolve once at `:root`, and a nested `[data-theme]` stops working, silently, in the production
+build only.
+
+Name targets that support `light-dark()` natively:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  build: { cssTarget: ["chrome123", "edge123", "firefox120", "safari17.5"] },
+  plugins: [tailwindcss(), sveltekit()],
+});
+```
+
+### 3. The route declaration
+
+The route tree is the filesystem; this file only attaches presentation and access data to route
+ids SvelteKit already knows. Nothing here re-states the hierarchy.
+
+```ts
+// src/lib/routes.ts
+import type { RouteId } from "$app/types";
+import type { RoutingConfig } from "@viniaraujo68/plinth/routing";
+
+export const routes: RoutingConfig<RouteId> = {
+  meta: {
+    "/": { title: "Home", icon: "icon-[lucide--home]" },
+    "/orders": { title: "Orders", icon: "icon-[lucide--receipt]" },
+    "/orders/[id]": { title: ({ params }) => `Order ${params.id}` },
+    "/admin": { title: "Admin", icon: "icon-[lucide--shield]", requiredRoles: ["admin"] },
+  },
+
+  // The glob has to be written here, in the app, and never inside the library: Vite rewrites the
+  // literal call at build time against the file it appears in, so a library issuing it on the
+  // app's behalf would scan its own package and come back empty-handed. Only the keys are read.
+  pages: import.meta.glob("/src/routes/**/+page.svelte"),
+};
+```
+
+Keying `meta` with `RouteId` from `$app/types` is what makes a renamed or deleted route a compile
+error instead of a crumb that quietly stops appearing. `icon` is an uninterpreted string handed
+straight to markup as `<span class={meta.icon}>` — an icon font or an Iconify utility class fits
+without configuration; anything else goes through `AppShell`'s `icon` snippet.
+
+### 4. The root layout
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import "./layout.css";
+  import { browser } from "$app/environment";
+  import { page } from "$app/state";
+  import type { Snippet } from "svelte";
+  import { RoutingContext, setRoutingContext } from "@viniaraujo68/plinth/routing";
+  import { AppShell } from "@viniaraujo68/plinth/shell";
+  import {
+    readThemePreference,
+    setThemeContext,
+    ThemeContext,
+    ThemeController,
+    ThemeToggle,
+  } from "@viniaraujo68/plinth/theme";
+  import { Toaster } from "@viniaraujo68/plinth/toast";
+  import { setUserContext } from "@viniaraujo68/plinth/user";
+  import { routes } from "$lib/routes.js";
+
+  const { children }: { children: Snippet } = $props();
+
+  // Contexts are installed while this component initialises, so every route below inherits them.
+  setThemeContext(new ThemeContext(browser ? readThemePreference() : "system"));
+  // SvelteKit already matched the URL; the routing context only projects that match through the
+  // meta map, so `page` is handed in as-is.
+  setRoutingContext(new RoutingContext(routes, page));
+  setUserContext({
+    status: "authenticated",
+    data: { name: "Ada Lovelace", email: "ada@example.com" },
+    hasRole: (role) => role === "admin",
+    hasAnyRole: (roles) => roles.length === 0 || roles.includes("admin"),
+    hasAllRoles: (roles) => roles.every((role) => role === "admin"),
+  });
+</script>
+
+<ThemeController />
+
+<div class="h-dvh">
+  <AppShell>
+    {#snippet brand({ collapsed })}
+      <span class="font-semibold tracking-tight">{collapsed ? "A" : "Acme"}</span>
+    {/snippet}
+    {#snippet footer()}
+      <ThemeToggle iconOnly />
+    {/snippet}
+    {@render children()}
+  </AppShell>
+</div>
+
+<!-- Outside the routed subtree: a toast fired just before a navigation has to outlive the page
+     that fired it. -->
+<Toaster />
+```
+
+`ThemeController` is a hidden checkbox that must be mounted exactly once, unconditionally — it is
+what CSS keys the theme on, and every other picker in the app just writes `preference` on the
+theme context. `AppShell` fills its parent, so give it one with a height. Its navigation lists the
+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.
+
+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
+the first paint and nothing else.** The stylesheet gives it up the moment a checked controller is
+under it, and `ThemeController` drops it outright when it mounts, so from hydration onwards the
+preference is the only thing painting the page — including the "system" preference, which checks
+nothing and would otherwise keep losing to a stale stamp forever. Do not read the root
+`data-theme` back as the current theme: read `preference` on the theme context, or `dark` for the
+resolved one. A `data-theme` on any element **below** the root is a different thing entirely and
+is left alone — that is subtree theming, and it keeps working whatever the page theme is.
+
+`setUserContext` is optional: without it the library falls back to an anonymous context whose role
+checks all answer `true`, so a route tree annotated with `requiredRoles` still renders while there
+is no authentication to evaluate it against. Any object matching the `UserContext` interface will
+do — reactive if the answers can change, which a class with `$state` fields gives you.
+
+### 5. A page
+
+```svelte
+<!-- src/routes/orders/+page.svelte -->
+<script lang="ts">
+  import { Breadcrumbs } from "@viniaraujo68/plinth/shell";
+  import { DataTable } from "@viniaraujo68/plinth/table";
+  import type { Column } from "@viniaraujo68/plinth/table";
+  import { createFormatters } from "@viniaraujo68/plinth/formatters";
+  import { createHttpClient, errorMessage } from "@viniaraujo68/plinth/http";
+  import { toast } from "@viniaraujo68/plinth/toast";
+
+  interface Order {
+    id: string;
+    customer: string;
+    total: number;
+    placedAt: string;
+  }
+
+  const format = createFormatters("en-US");
+  const api = createHttpClient({ baseUrl: "/api", credentials: "include" });
+
+  // `key` alone reads the field, renders it and sorts by it. A formatted cell says what it shows
+  // with `value` and what it orders by with `sortBy`, so money sorts as a number and a date as a
+  // date rather than as the string on screen.
+  const columns: Column<Order>[] = [
+    { key: "id", label: "Order" },
+    { key: "customer", label: "Customer" },
+    {
+      key: "total",
+      label: "Total",
+      value: (row) => format.currency(row.total, "USD"),
+      sortBy: (row) => row.total,
+      numeric: true,
+    },
+    {
+      key: "placedAt",
+      label: "Placed",
+      value: (row) => format.date(row.placedAt),
+      sortBy: (row) => row.placedAt,
+    },
+  ];
+
+  let rows = $state<Order[]>([]);
+
+  $effect(() => {
+    api
+      .get<Order[]>("/orders")
+      .then((loaded) => (rows = loaded))
+      .catch((error: unknown) => toast.error(errorMessage(error)));
+  });
+</script>
+
+<div class="flex flex-col gap-4 p-6">
+  <Breadcrumbs />
+  <DataTable {columns} {rows} rowKey={(row) => row.id} />
+</div>
+```
+
+`Breadcrumbs` derives the trail from the routing context; it is never handed a list. `DataTable`
+sorts in the browser and turns into cards on a narrow screen; given `columnsLabel`, `resizable` and
+`storageKey`, it also lets the reader show, hide, reorder and resize its columns and remembers the
+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.
+
+## 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                                                                |
+| `@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`                                                                            |
+
+The components entry point ships `AsyncButton`, `Combobox`, `Copyable`, `DateRangePicker`,
+`Dialog`, `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.
+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.
+
+`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.
+
+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:
+
+- **`Select`** — a trigger and a panel of rows, for a list short enough to read at a glance. There
+  is nothing to type into; the arrows walk it, the first letters of a label jump to it as in a
+  native select, and the trigger keeps the focus. `required` holds a form back while nothing is
+  selected.
+- **`Combobox`** — the control bar IS the search field, for a list nobody is going to scroll.
+  Clicking it selects the text that is there so the next keystroke replaces it, the query filters
+  past accents and anywhere in the label, every word of it in any order, and anything that closes
+  the list without a pick puts the selected label back.
+
+**`Listbox`** is the list on its own, with no trigger and no panel: it renders in place, holds the
+focus on itself or on an optional search box, checks one value or an array of them, and jumps to
+a typed prefix. Inside a `Dropdown`, `autofocus` hands it the keyboard as the panel opens.
+
+**`MultiSelect`** picks several: the field shows the picks as removable chips, and opening it lists
+every option under a search box, with the picked ones checked; a row is checked or unchecked
+without closing the list. A disabled option that is already picked stays locked. `name` submits
+one entry per pick and `required` holds the form back while nothing is picked.
+
+Their panels — and `Dropdown`'s, and the one the `tooltip` attachment puts up — are placed with CSS
+anchor positioning, and place themselves from script in a browser that does not have it yet
+(Firefox, and Safari before iOS/macOS 26), so a panel is never left floating at the top of the
+screen instead of under its control.
+
+`Confirmer` is a component too, and it has its own showcase page, but it ships from
+`@viniaraujo68/plinth/confirm` rather than from the components entry point: like `Toaster` it is
+half of a pair, and the other half is a function any module calls with nothing plumbed through.
+
+```svelte
+<script lang="ts">
+  import { confirm } from "@viniaraujo68/plinth/confirm";
+
+  const remove = async (night: Night) => {
+    if (!(await confirm({ title: `Delete ${night.name}?`, danger: true }))) return;
+    await api.delete(`/nights/${night.id}`);
+  };
+</script>
+```
+
+`await confirm(...)` is the whole call site, and it replaces the browser's own `confirm()` one line
+for one line. `<Confirmer />` goes next to `<Toaster />` in the root layout and renders the queue
+over `Modal`, so modality, the focus trap, Escape and returning focus to the opener stay the
+browser's. Cancel, Escape, the close button, a click on the backdrop and the host unmounting all
+resolve `false`; only the confirm action resolves `true`. Focus opens on cancel — never on the
+destructive button — so a stray Enter cannot delete anything.
+
+A second call while one is open queues behind it rather than replacing it or rejecting: replacing
+would answer a question nobody was shown, and rejecting would throw at a call site written to read
+a boolean. `challenge` is the stronger gate — the confirm action stays disabled until that exact
+string has been typed, ends trimmed and nothing else folded — and focus opens in that input, where
+Enter confirms only once it matches. The library ships no translations, so `confirmLabel`,
+`cancelLabel`, `closeLabel` and `challengeLabel` on the host translate every confirm at once, and
+any call overrides them through its own options.
+
+## Development
+
+```sh
+npm install
+npm run dev        # showcase at localhost:5173
+npm run check      # svelte-check
+npm run lint       # prettier --check and eslint
+npm run test:unit  # vitest: a browser project and a node project
+npm run test       # the above, plus the playwright end-to-end run
+npm run build      # showcase build, then svelte-package and publint
+```
+
+`npm run test:unit` needs a Chromium build: `npx playwright install chromium`.
+
+`BASE_PATH=/plinth npm run build` reproduces what the Pages deploy does. Leave it unset anywhere
+else — dev, preview and the end-to-end run all serve from the root.
+
+Two workflows run on GitHub: every push to `main` deploys the showcase to Pages, and a `v*` tag
+gates on check, lint and unit tests before `npm publish`.
+
+## License
+
+MIT

package/dist/anchoring.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Whether the browser can place a popover against an anchor on its own.
+ *
+ * Both halves are asked for: an engine can ship the `anchor-name`/`anchor()` pair without
+ * `position-area`, and the library's stylesheets are written in terms of the areas.
+ *
+ * Memoised — the answer cannot change for the life of a document — and safe on the server, where
+ * there is no `CSS` object and the reply is `false`.
+ */
+export declare function supportsAnchorPositioning(): boolean;
+/**
+ * @internal Forces what {@link supportsAnchorPositioning} reports, or hands the question back to
+ * feature detection with `undefined`. A test seam and nothing else: the detection is memoised, so
+ * a spec that only stubs `CSS.supports` may find the answer already cached. Not exported from the
+ * package.
+ */
+export declare function overrideAnchorPositioningSupport(value: boolean | undefined): void;
+export interface AnchoredPlacement {
+    /**
+     * Which side of the anchor the panel prefers. It flips to the other one when the preferred side
+     * has no room for it, which is the `position-try: top` / `flip-block` parity. Defaults to
+     * `"bottom"`.
+     */
+    side?: "bottom" | "top";
+    /**
+     * How the panel lines up with the anchor across the inline axis. `position-area` centres a panel
+     * on its anchor, so `"center"` is the parity and the default; `"start"` only differs for a panel
+     * that is not as wide as the anchor.
+     */
+    align?: "center" | "start";
+    /** Pixels kept between the anchor and the panel — the margin the anchored path carries across
+        that axis. */
+    gap?: number;
+    /**
+     * Pixels kept between the panel and the edges of the screen when it has to be pulled back onto
+     * it — the margin the anchored path carries across the other axis, which is what a supporting
+     * browser keeps when it clamps an anchored panel in. Defaults to none, which is right for a
+     * panel whose anchored margin is `auto`: one as wide as a full-width control has nowhere to be
+     * pulled to.
+     */
+    inset?: number;
+    /** Whether the panel takes the anchor's width: the `width: anchor-size(width)` parity. */
+    matchWidth?: boolean;
+}
+/**
+ * Places `panel` against `anchor` from script, for a browser that cannot do it in CSS.
+ *
+ * Under the anchor by default, above it when asked for or when there is no room below, as wide as
+ * the anchor when the caller's stylesheet says `anchor-size(width)`, and never off the side of the
+ * screen. The panel is expected to be a shown popover: it is measured, so it has to have a box.
+ *
+ * The placement is kept up to date for as long as the panel is open — scrolling, resizing, a
+ * phone's on-screen keyboard, and a change of size at either end all move it — and the returned
+ * function is what ends that: it drops every listener and puts the inline styles back the way it
+ * found them. Call it on close, and call it again on the next open.
+ *
+ * `position-try: left, right` has no counterpart here: a panel that fits on neither side of the
+ * anchor is clamped into the viewport instead of moved beside it. It stays reachable, which is the
+ * whole point of the fallback, and no supporting browser takes this path.
+ */
+export declare function positionUnder(panel: HTMLElement, anchor: HTMLElement, placement?: AnchoredPlacement): () => void;

package/dist/anchoring.js

@@ -0,0 +1,151 @@
+/* Every popover in this library is placed with CSS anchor positioning -- `anchor-name`,
+   `position-area`, `position-try`, `anchor-size()` -- which is the right tool and also a very
+   recent one: Chromium 125, Safari only with iOS/macOS 26, and nothing stable in Firefox. A
+   browser without it does not degrade to something reasonable. The anchored declarations are
+   dropped, the UA popover rules (`position: fixed; inset: 0; margin: auto`) are what is left, and
+   the panel lands in the middle of the screen at an intrinsic width -- or, once an author margin
+   overrides part of that `auto`, pinned to the top edge, which is the shape the bug was reported
+   in from a real phone.
+
+   This module is the other half of the enhancement: where the CSS works nothing here runs, and
+   where it does not, script writes the same geometry the stylesheet would have produced. */
+let support;
+const detect = () => typeof CSS !== "undefined" &&
+    CSS.supports("anchor-name: --x") &&
+    CSS.supports("position-area: bottom");
+/**
+ * Whether the browser can place a popover against an anchor on its own.
+ *
+ * Both halves are asked for: an engine can ship the `anchor-name`/`anchor()` pair without
+ * `position-area`, and the library's stylesheets are written in terms of the areas.
+ *
+ * Memoised — the answer cannot change for the life of a document — and safe on the server, where
+ * there is no `CSS` object and the reply is `false`.
+ */
+export function supportsAnchorPositioning() {
+    support ??= detect();
+    return support;
+}
+/**
+ * @internal Forces what {@link supportsAnchorPositioning} reports, or hands the question back to
+ * feature detection with `undefined`. A test seam and nothing else: the detection is memoised, so
+ * a spec that only stubs `CSS.supports` may find the answer already cached. Not exported from the
+ * package.
+ */
+export function overrideAnchorPositioningSupport(value) {
+    support = value;
+}
+const clamp = (value, lowest, highest) => highest < lowest ? lowest : Math.min(Math.max(value, lowest), highest);
+/**
+ * Places `panel` against `anchor` from script, for a browser that cannot do it in CSS.
+ *
+ * Under the anchor by default, above it when asked for or when there is no room below, as wide as
+ * the anchor when the caller's stylesheet says `anchor-size(width)`, and never off the side of the
+ * screen. The panel is expected to be a shown popover: it is measured, so it has to have a box.
+ *
+ * The placement is kept up to date for as long as the panel is open — scrolling, resizing, a
+ * phone's on-screen keyboard, and a change of size at either end all move it — and the returned
+ * function is what ends that: it drops every listener and puts the inline styles back the way it
+ * found them. Call it on close, and call it again on the next open.
+ *
+ * `position-try: left, right` has no counterpart here: a panel that fits on neither side of the
+ * anchor is clamped into the viewport instead of moved beside it. It stays reachable, which is the
+ * whole point of the fallback, and no supporting browser takes this path.
+ */
+export function positionUnder(panel, anchor, placement = {}) {
+    const { side = "bottom", align = "center", gap = 0, inset = 0, matchWidth = false } = placement;
+    const original = new Map();
+    const write = (property, value) => {
+        if (!original.has(property))
+            original.set(property, panel.style.getPropertyValue(property));
+        panel.style.setProperty(property, value);
+    };
+    const place = () => {
+        const target = anchor.getBoundingClientRect();
+        /* Document coordinates, not viewport ones. A popover sits in the top layer, whose containing
+           block is the initial containing block, so an absolutely positioned panel is offset from the
+           document's origin and scrolls with the page on its own. `position: fixed` was the obvious
+           choice and the wrong one: iOS Safari renders fixed boxes against the visual viewport once
+           the keyboard is up or the page is zoomed, while `getBoundingClientRect()` keeps answering in
+           layout-viewport coordinates -- a `Combobox` list landed a keyboard's height away from its
+           field. Absolute boxes and client rects agree, whatever the visual viewport is doing. */
+        const scrollX = window.scrollX;
+        const scrollY = window.scrollY;
+        const targetTop = target.top + scrollY;
+        const targetBottom = target.bottom + scrollY;
+        const targetLeft = target.left + scrollX;
+        write("position", "absolute");
+        write("margin", "0");
+        /* Both of these are the initial values, so writing them costs nothing in the browser this
+           exists for -- it does not know the properties and drops the declarations. What they buy is
+           that nothing else can be positioning the panel at the same time: an engine that took
+           `anchor-name` but not `position-area`, and a supporting engine a test has forced down this
+           path, would otherwise resolve the `top` below against the anchored containing block. */
+        write("position-area", "none");
+        write("position-try-fallbacks", "none");
+        /* The UA popover rules leave `inset: 0` behind, and a box with both `left` and `right` set
+           stretches to fill its containing block instead of taking its own width. Zeroing `left`
+           before measuring also gives a panel with no width of its own the whole viewport to
+           shrink-to-fit against, so the reading below is the widest it can be -- and the clamp keeps
+           it there, so moving it cannot narrow it again. */
+        write("right", "auto");
+        write("bottom", "auto");
+        write("left", "0");
+        if (matchWidth)
+            write("width", `${target.width}px`);
+        const { width, height } = panel.getBoundingClientRect();
+        // A panel with no box is a panel that is not being shown -- a size observation that arrived
+        // after the close, most likely. Nothing to place, and nothing worth writing a stale top for.
+        if (width === 0 && height === 0)
+            return;
+        /* The visual viewport is the part of the page a person can actually see: what is left above
+           a phone's keyboard, or the zoomed-in window. That is the region the panel has to fit in and
+           be clamped to, and `pageTop`/`pageLeft` already put it in document coordinates. */
+        const visual = window.visualViewport;
+        const view = visual
+            ? { top: visual.pageTop, left: visual.pageLeft, width: visual.width, height: visual.height }
+            : {
+                top: scrollY,
+                left: scrollX,
+                width: document.documentElement.clientWidth,
+                height: document.documentElement.clientHeight,
+            };
+        // The gap goes between the anchor and the panel and the inset between the panel and the edge
+        // of the screen, which is what makes "it fits" the same question the clamp below answers.
+        const fitsBelow = height <= view.top + view.height - targetBottom - gap - inset;
+        const fitsAbove = height <= targetTop - view.top - gap - inset;
+        const above = side === "top" ? fitsAbove || !fitsBelow : !fitsBelow && fitsAbove;
+        const top = above ? targetTop - gap - height : targetBottom + gap;
+        const left = align === "start" ? targetLeft : targetLeft + (target.width - width) / 2;
+        write("top", `${clamp(top, view.top + inset, view.top + view.height - inset - height)}px`);
+        write("left", `${clamp(left, view.left + inset, view.left + view.width - inset - width)}px`);
+    };
+    place();
+    /* Capture, because a scroll that moves the anchor is very often a scroll inside something --
+       a modal's body, a scrolling table -- and a `scroll` event from an element never reaches the
+       window by bubbling. */
+    window.addEventListener("scroll", place, { capture: true, passive: true });
+    window.addEventListener("resize", place);
+    /* The visual viewport is the one a phone's on-screen keyboard and pinch-zoom change, and
+       neither of those fires `resize` on the window. */
+    window.visualViewport?.addEventListener("resize", place);
+    window.visualViewport?.addEventListener("scroll", place);
+    /* Either box changing size changes the placement: the flip and both clamps are measurements. It
+       is also what keeps a `Combobox` panel under its field while the query filters rows away, with
+       no reactive plumbing in the component. */
+    const observer = new ResizeObserver(place);
+    observer.observe(panel);
+    observer.observe(anchor);
+    return () => {
+        observer.disconnect();
+        window.removeEventListener("scroll", place, { capture: true });
+        window.removeEventListener("resize", place);
+        window.visualViewport?.removeEventListener("resize", place);
+        window.visualViewport?.removeEventListener("scroll", place);
+        for (const [property, value] of original)
+            if (value)
+                panel.style.setProperty(property, value);
+            else
+                panel.style.removeProperty(property);
+    };
+}

package/dist/async-action.svelte.d.ts

@@ -0,0 +1,37 @@
+/** Shape of the work an action wraps. `never[]` keeps `Parameters<T>` inferring at the call site. */
+export type AsyncFn = (...args: never[]) => Promise<unknown>;
+export type AsyncActionStatus = "idle" | "pending" | "success" | "error";
+/**
+ * A promise-returning function plus the four-state machine every button around one ends up
+ * re-implementing: idle, pending, success, error.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { AsyncAction } from "@viniaraujo68/plinth";
+ *
+ *   const save = new AsyncAction((draft: Draft) => api.save(draft));
+ * </script>
+ *
+ * <button disabled={save.isPending} onclick={() => save.run(draft)}>Save</button>
+ * {#if save.isError}<p class="text-error">Could not save.</p>{/if}
+ * ```
+ */
+export declare class AsyncAction<T extends AsyncFn> {
+    #private;
+    private fn;
+    status: AsyncActionStatus;
+    error: unknown;
+    isPending: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    constructor(fn: T);
+    reset: () => void;
+    /**
+     * Runs the action and records the outcome.
+     *
+     * It never rejects: an event handler has nowhere to catch, so a rethrow here would surface as an
+     * unhandled rejection instead of as UI. Failure is `error` and `isError`. A run that failed —
+     * or that was superseded by a later `run`/`reset` — resolves to `undefined`.
+     */
+    run: (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>> | undefined>;
+}