@viniaraujo68/plinth 0.3.1 → 0.5.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,71 @@ 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`.
 
 `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 +382,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/ErrorDisplay.svelte

@@ -1,15 +1,23 @@
 <script lang="ts">
+  import type { Snippet } from "svelte";
+
   interface Props {
     /** Wire the `reset` a `svelte:boundary` hands to its `failed` snippet. Omitted, no button. */
     reset?: () => void;
     title?: string;
     message?: string;
+    eyebrow?: string;
+    retryLabel?: string;
+    icon?: Snippet;
   }
 
   let {
     reset,
     title = "Something went wrong",
     message = "The application ran into an unexpected problem.",
+    eyebrow = "Error",
+    retryLabel = "Try again",
+    icon,
   }: Props = $props();
 </script>
 
@@ -34,26 +42,32 @@ counted once per render. Wire `reportError` on the boundary's `onerror` instead.
   class="flex h-full w-full flex-col items-center justify-center gap-2 p-8 text-center"
   role="alert"
 >
-  <svg
-    class="size-12 text-base-content/40"
-    viewBox="0 0 24 24"
-    fill="none"
-    stroke="currentColor"
-    stroke-width="1.5"
-    stroke-linecap="round"
-    stroke-linejoin="round"
-    aria-hidden="true"
-  >
-    <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
-    <path d="M12 9v4" />
-    <path d="M12 17h.01" />
-  </svg>
-  <p class="text-xs font-medium tracking-widest text-base-content/55 uppercase">Error</p>
+  {#if icon}
+    {@render icon()}
+  {:else}
+    <svg
+      class="size-12 text-base-content/40"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="1.5"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" />
+      <path d="M12 9v4" />
+      <path d="M12 17h.01" />
+    </svg>
+  {/if}
+  {#if eyebrow}
+    <p class="text-xs font-medium tracking-widest text-base-content/55 uppercase">{eyebrow}</p>
+  {/if}
   <p class="text-xl font-semibold">{title}</p>
   <p class="max-w-md text-sm text-base-content/60">{message}</p>
   {#if reset}
     <div class="mt-4">
-      <button type="button" class="btn btn-primary" onclick={reset}>Try again</button>
+      <button type="button" class="btn btn-primary" onclick={reset}>{retryLabel}</button>
     </div>
   {/if}
 </div>

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

@@ -1,8 +1,12 @@
+import type { Snippet } from "svelte";
 interface Props {
     /** Wire the `reset` a `svelte:boundary` hands to its `failed` snippet. Omitted, no button. */
     reset?: () => void;
     title?: string;
     message?: string;
+    eyebrow?: string;
+    retryLabel?: string;
+    icon?: Snippet;
 }
 /**
  * Calm in-place fallback for a crashed subtree: it says what happened and offers the way out.

package/dist/components/JsonView.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+  import JsonViewFrame, {
+    type JsonViewProps,
+    type JsonViewRevealTarget,
+  } from "./JsonViewFrame.svelte";
+
+  const props: JsonViewProps = $props();
+
+  let scroller = $state<HTMLDivElement>();
+
+  const reveal = ({ line }: JsonViewRevealTarget) => {
+    const row = scroller?.querySelector<HTMLElement>(`[data-line="${line}"]`);
+    const target = row?.querySelector<HTMLElement>("[data-active]") ?? row;
+    target?.scrollIntoView({ block: "nearest", inline: "nearest" });
+  };
+</script>
+
+<JsonViewFrame {...props} {reveal}>
+  {#snippet viewport({ visible, line, rowId, widthCh })}
+    <div bind:this={scroller} class="plinth-json-scroller">
+      <div class="plinth-json-lines" style:min-width="max(100%, {widthCh}ch)">
+        {#each visible as index (rowId(index))}
+          {@render line(index)}
+        {/each}
+      </div>
+    </div>
+  {/snippet}
+</JsonViewFrame>
+
+<style>
+  .plinth-json-scroller {
+    flex: 1;
+    min-height: 0;
+    overflow: auto;
+    padding-block: 0.25rem;
+  }
+
+  .plinth-json-lines {
+    width: max-content;
+    min-width: 100%;
+    padding-inline-end: 1ch;
+  }
+</style>

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

@@ -0,0 +1,4 @@
+import { type JsonViewProps } from "./JsonViewFrame.svelte";
+declare const JsonView: import("svelte").Component<JsonViewProps, {}, "">;
+type JsonView = ReturnType<typeof JsonView>;
+export default JsonView;