@connextar/house 0.2.0 → 0.4.0

package/README.md

@@ -39,6 +39,27 @@ The 0.2.0 modules are the second half of that rule. AltEd built a versioned
 changelog, a navigation trail, a block editor and guide tables; every other app
 was about to write each of them for the second time.
 
+`ux`, in 0.3.0, is the clearest case of that clause yet. Every app in the
+portfolio writes over `fetch` and refreshes afterwards, so every one of them has
+the same dead-click problem — a tick that goes nowhere for half a second, a
+button that looks broken while working perfectly — and none of them had solved
+it. It is also the kind of code nobody should write twice: the rules about when
+to let go of an optimistic change are small, subtle and easy to get quietly
+wrong.
+
+`wizard`, in 0.4.0, is the first module extracted from five copies that had
+already been written. It is here because of what those copies cost: four of the
+five shipped a defect in it, and not one of the four was a mistake about
+wizards. PharmaLine created a booking from step two, because a `type="button"`
+Continue and a `type="submit"` Create shared a slot and React switched the one
+DOM node's type mid-click. Three PM Tool forms refused to save with nothing on
+screen saying why. MAS checked no step at all on submit, so a second press after
+a successful create sent a record whose first step had been cleared. Every one of
+those is a mistake about what a form must do before it agrees to send, and there
+is one right answer to that — which is exactly the shape of thing that belongs
+here and nowhere else. The module is the union of the five, not a copy of the
+best one.
+
 ## Modules
 
 ### `@connextar/house/errors`
@@ -236,10 +257,166 @@ much for the editor to ask for theirs, and this is not a second design system.
 If an app also depends on `@tiptap/*` directly, keep it in the same range as this
 package so npm installs one copy. Two copies of `@tiptap/pm` break the editor.
 
+### `@connextar/house/ux`
+
+The interface answers the click: optimistic updates, pending state, and
+navigation feedback. Headless — no components, no design system, no toast
+library, no HTTP client.
+
+`useOptimisticList(rows, { key })` holds the server's rows as a _base_ and every
+change as a _patch_ beside them, folded in on render. `insert`, `update`,
+`remove`, `move` and `bulk` each take a commit function; `isPending(key)` marks
+one row without disabling the table. `useOptimisticValue` is the same for a
+switch, a status or a settings record; `useAction` and `useKeyedAction` are for
+work that should not be guessed at — a payment, a model call, a sign-in — and
+give a control the `pending` flag it needs and nothing more.
+
+```tsx
+const tasks = useOptimisticList(rows, { key: (t) => t.id, onSettled: router.refresh });
+
+tasks.update(task.id, { done: true }, () => save(task.id, { done: true }));
+```
+
+**Why not `useOptimistic`.** React 19's hook is right when the write _is_ the
+transition — a server action. It is wrong for an app that writes over `fetch` and
+then calls `router.refresh()`, because `router.refresh()` is not awaitable: the
+transition ends before the new rows arrive and the optimistic value snaps back to
+the stale one, flashing the old answer on every single write.
+
+**When a change is let go of.** A patch is `pending` while its write is in
+flight, then dropped (it failed — the base alone is the truth again) or `settled`
+(it landed, and keeps being applied, because the base is still the _old_ rows
+until a refresh arrives). A settled patch goes when fresh rows account for it:
+either they agree, or they disagree with what they said when the write landed, in
+which case they win and the screen corrects itself. Evidence, never a timer — a
+screen that does not refetch has no truth to fall back to, and snapping to stale
+rows after N seconds is a bug that only appears on a slow connection.
+
+**The three seams that keep it portable.** A commit is
+`() => Promise<Row | void>` that **throws** on failure, which is the one failure
+contract every client already has; an app whose client returns a result object
+wraps it once. Failures are reported to an `ActionFeedbackProvider` as
+`{ tone, title, description }`, so the app decides what a message looks like.
+And `NavigationProgress` takes a `className` for its bar, so it never needs a
+token.
+
+`NavigationProgress` (from `@connextar/house/ux/navigation` — its own entry
+point, so `next` stays an optional peer) also marks the link that was clicked
+with `data-busy`, which `house.css` turns into a spinner. Two notes on it, both
+learned the hard way:
+
+- Its click listener is in the **capture** phase, and deliberately does not check
+  `defaultPrevented`. Next's `Link` cancels the click on its way to a
+  client-side navigation, so a bubble-phase listener guarding on
+  `defaultPrevented` fires for every link _except_ the app's own — which is
+  precisely backwards, and is what AltEd shipped unnoticed until it was measured
+  in a browser.
+- `useAppRouter()` is `useRouter()` with the same feedback on `push` and
+  `replace`. Swapping the import is the whole change; no call site moves.
+
+**Not everything should be optimistic.** Money, model calls, sign-in, imports and
+exports: anything whose result the person cannot predict, or would be alarmed to
+see undone. Guessing is only honest when the guess is nearly always right.
+
+### `@connextar/house/wizard`, `/wizard/react-hook-form`
+
+`FormWizard` — one long form split into steps that check themselves. **It renders
+the `<form>`**, because two of its promises cannot be kept from inside somebody
+else's: that Enter has one place to land, and that nothing reaches `onSubmit`
+unchecked.
+
+```tsx
+const check = useStepValidator(form); // react-hook-form; or write your own
+
+<FormWizard
+  steps={[
+    { id: "learner", title: "Learner", fields: ["studentId", "level"], content: <LearnerFields /> },
+    { id: "period", title: "Period", fields: ["startDate", "endDate"], content: <PeriodFields /> },
+    { id: "build", title: "Build", fields: [], content: <ReviewFields /> },
+  ]}
+  onValidateStep={check}
+  onSubmit={() => void form.handleSubmit(submit, report)()}
+  onCancel={() => router.push(routes.plans)}
+  submitLabel="Build my curriculum"
+  pending={pending}
+/>;
+```
+
+The rules it keeps, each one because a copy of it did not:
+
+- **Submitting checks every step, in order, and lands on the first that fails**,
+  with its message visible. Checking only the last step lets a marker jump back,
+  a cleared field and a press of Save refuse with the problem three screens away.
+  Checking none — MAS — sends the record anyway.
+- **Enter before the last step advances.** It validates the step it is on and
+  opens the next; only the last step's Enter submits. A booking that emails a
+  patient must not be creatable from the step before Confirm.
+- **One submit button, whose `type` never changes.** Never two controls sharing
+  the slot. jsdom's timing hid this, and only Chromium showed it, so the test
+  that guards it is structural: one `button[type=submit]`, the same node on every
+  step.
+- **Continue is never disabled for being incomplete.** A greyed-out button that
+  will not say what is missing is a refusal with no words. It is disabled only
+  while something is in flight.
+- **Visited markers are reachable, later steps locked** (`allReachable` opens
+  them all, for editing values that are already there).
+- **Every step stays mounted, hidden rather than unmounted**, so there is one
+  field register and nothing typed is lost stepping back.
+
+**Form-library-agnostic, because the five hosts are not the same.** A step is
+complete when the check says so, and a check may answer either way the cohort
+already writes them: `true`/`null` for complete, `false` for "not complete, and I
+am showing why beside the field", or **a sentence** for "not complete, and this is
+what to say" — which the wizard then shows in a `role="alert"` of its own. So
+react-hook-form, plain `useState` and MAS's state forms all host it unchanged. A
+check may live on the form (`onValidateStep`) or on the step (`step.validate`);
+both are asked, the step's first.
+
+`stepValidator(form, report)` and `useStepValidator(form)` are in
+`@connextar/house/wizard/react-hook-form` — its own entry point because
+`react-hook-form` is an **optional** peer dependency. Every import of it there is
+`import type`, so the emitted JavaScript never mentions it; what would break an
+app without it is a declaration file naming a package it has not installed, which
+is why the names sit behind a subpath MAS never reaches for.
+`src/wizard/entry-points.test.ts` keeps that honest against the built output.
+
+**When the error is somewhere nobody can look.** A wizard's fields live on steps
+that are mounted but hidden, and a form library will not call a submit handler
+while any field is invalid — so a message beside a field the person cannot see
+makes the button look broken. `useInvalidReporter()` returns the function to pass
+as the invalid handler (`form.handleSubmit(onSubmit, report)`); it waits for the
+form to re-render and the wizard to move, then says the message out loud **only
+if it is not already on screen**. It goes to the `ActionFeedbackProvider` from
+[`ux`](#connextarhouseux), so this module imports no toast library. A field's
+message opts in by carrying `data-error-for="<name>"` — `FieldError` does it, and
+an app's own message component adds one attribute.
+
+The look is theme-token classes, replaced part by part through `classNames`, the
+same way the guide renderer allows — there is still no `Button` in this package,
+so the wizard draws plain elements and wears the app's classes. The busy state is
+`data-busy`, which [`house.css`](#styles--connextarhousehousecss) already turns
+into a spinner.
+
+**What not to make a wizard.** A form of four fields is shorter than a wizard
+around it, and a stepper over one screen of content is decoration that costs a
+click. This is for a form long enough that a person would otherwise lose their
+place — five steps in the curriculum builder, a booking that has to reach Confirm
+— and specifically for one where **later steps depend on earlier answers**. Three
+independent sections are a form with three headings. A flow whose steps are
+separate saves, each landing before the next opens, is not one form and must not
+pretend to be: this wizard keeps one register and submits once.
+
 ### Styles — `@connextar/house/house.css`
 
 What the components need that utility classes cannot say: rich text, the editor's
-block gutter and suggestion highlight, the trail's tinted pills.
+block gutter and suggestion highlight, the trail's tinted pills, and the busy
+spinner `ux` puts on whatever was clicked.
+
+The spinner is `[data-busy="true"]::after`, drawn in `currentColor` with no theme
+token. A control that renders its own spinner marks it `.house-spinner` so it
+does not end up with two. For `prefers-reduced-motion` the ring stays and stops
+turning, rather than disappearing — it is the only thing on screen saying the
+click was heard.
 
 ## Tailwind setup (required for every component)
 
@@ -331,6 +508,40 @@ Traps found adopting it the first time:
   module"; delete `.next/dev` when no dev server is running.
 - If the app also depends on `@tiptap/*` directly, keep the range aligned or drop
   the direct dependency — two copies of `@tiptap/pm` break the editor.
+- **`FormWizard` renders the `<form>`, so the app's wrapper one has to go.** Every
+  local copy but two sat inside a host `<form onSubmit={preventDefault}>`; nested
+  forms are invalid HTML and the outer one is where the Enter bug lives. Keep the
+  app's `<Form {...form}>` provider if it has one — that is context, not an
+  element — and delete the `<form>` inside it. MAS also loses its
+  `finishControl`: the submit button is the wizard's now, and passing one back in
+  is the defect the wizard exists to prevent.
+- **Jest** (with `next/jest`) does not transform `node_modules`, and this package is
+  ESM, so the first import fails with `Unexpected token 'export'`. `next/jest` only
+  appends to `transformIgnorePatterns`, so export an async config that rewrites each
+  `/node_modules/(?!` rule to `/node_modules/(?!@connextar/house/)(?!`.
+- **Vitest needs one line to mock anything the package imports.** It loads
+  `node_modules` through native Node ESM, where `vi.mock` does not reach: a test
+  that mocks `next/navigation` keeps passing while the package's components call
+  the real router, until one of them throws `invariant expected app router to be
+mounted`. Inline the package so vite transforms it:
+
+  ```ts
+  test: {
+    server: {
+      deps: {
+        inline: [/@connextar\/house/];
+      }
+    }
+  }
+  ```
+
+- **Mock `next/navigation.js`, not just `next/navigation`.** This package is built
+  with `moduleResolution: nodenext`, and `next` ships no `exports` map — so an
+  extensionless subpath does not resolve and the source has to say
+  `next/navigation.js`. Vitest keys mocks by specifier, so an app's existing mock
+  of `next/navigation` does not cover the package. Register both, with the factory
+  written out twice: `vi.mock` is hoisted above every `const`, so a shared factory
+  variable throws `Cannot access ... before initialization`.
 
 **A note on local development.** Installing this with `npm install ../path` makes
 a symlink, and Next's Turbopack will not resolve a package whose real path is
@@ -340,7 +551,7 @@ behaves exactly like a registry install:
 
 ```bash
 npm pack --pack-destination /tmp        # in this repo
-npm install /tmp/connextar-house-0.2.0.tgz   # in the app
+npm install /tmp/connextar-house-0.4.0.tgz   # in the app
 ```
 
 ## Adding to it

package/dist/house.css

@@ -260,8 +260,74 @@
   }
 }
 
+/* ── Busy controls (@connextar/house/ux) ────────────────────────────────
+   One rule for "this is working on it", wherever the click landed.
+
+   `data-busy` is set by two things that never meet: the app's own button, for
+   an action whose spinner it cannot render inside (a button that forwards to a
+   `Link` has nowhere to put one), and `NavigationProgress`, for whichever link
+   or menu item was clicked. Neither knows what the other is, so the agreement
+   is an attribute and this stylesheet.
+
+   The spinner is a pseudo-element on purpose: the navigation watcher marks DOM
+   nodes it has never rendered and cannot re-render — a sidebar link, a row in
+   a table, a dropdown item from a page this package has never heard of — and
+   CSS is the only thing that reaches all of them. It lays out as a flex item
+   where the control is a flex container, and inline after the label where it
+   is not, so it takes its own space instead of sitting on top of the words.
+
+   `currentColor` throughout: no theme token, so it lands in any app's palette. */
+
+@layer components {
+  [data-busy="true"] {
+    cursor: progress;
+  }
+
+  [data-busy="true"]::after {
+    content: "";
+    display: inline-block;
+    flex: none;
+    width: 0.875rem;
+    height: 0.875rem;
+    margin-inline-start: 0.4rem;
+    vertical-align: -0.1875em;
+    border-radius: 9999px;
+    border: 2px solid currentColor;
+    border-inline-end-color: transparent;
+    opacity: 0.65;
+    animation: house-spin 0.6s linear infinite;
+  }
+
+  /* A flex control already spaces its children with `gap`. */
+  [data-busy="true"]:is(.inline-flex, .flex)::after {
+    margin-inline-start: 0;
+  }
+
+  /* A control that renders its own spinner marks it `.house-spinner`, so it
+     does not end up with two. */
+  [data-busy="true"]:has(> .house-spinner)::after {
+    content: none;
+  }
+}
+
+/* Keyframes must sit outside @layer. */
+@keyframes house-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .house-block-handle {
     transition: none;
   }
+
+  /* Stillness was asked for, but silence is not the alternative: the ring
+     stays, it just stops going round. Removing it altogether would take away
+     the only thing on screen saying the click was heard. */
+  [data-busy="true"]::after {
+    animation: none !important;
+    border-inline-end-color: currentColor;
+    opacity: 0.45;
+  }
 }

package/dist/ux/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one thing an optimistic commit has to be able to say: "that didn't work,
+ * and here is what to tell the person".
+ *
+ * The hooks in this folder take a commit function that throws on failure —
+ * the only failure contract every transport already has. An app whose client
+ * returns a result object instead of throwing wraps it once (see
+ * `commitApi` in `lib/api.ts`) rather than teaching this layer its envelope.
+ */
+export declare class ActionError extends Error {
+    /** HTTP status, where the transport had one. */
+    readonly status?: number;
+    /**
+     * Whatever the refusal carried. A conflict usually carries the record as it
+     * now is, which is what a caller merges into rather than rolling back to.
+     */
+    readonly data?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        data?: unknown;
+        cause?: unknown;
+    });
+}
+/** The wording to show for a thrown value, whatever it turned out to be. */
+export declare function errorMessage(error: unknown, fallback?: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/ux/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/ux/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAMhG;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAyB,GAAG,MAAM,CAItF"}

package/dist/ux/errors.js

@@ -0,0 +1,33 @@
+/**
+ * The one thing an optimistic commit has to be able to say: "that didn't work,
+ * and here is what to tell the person".
+ *
+ * The hooks in this folder take a commit function that throws on failure —
+ * the only failure contract every transport already has. An app whose client
+ * returns a result object instead of throwing wraps it once (see
+ * `commitApi` in `lib/api.ts`) rather than teaching this layer its envelope.
+ */
+export class ActionError extends Error {
+    /** HTTP status, where the transport had one. */
+    status;
+    /**
+     * Whatever the refusal carried. A conflict usually carries the record as it
+     * now is, which is what a caller merges into rather than rolling back to.
+     */
+    data;
+    constructor(message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "ActionError";
+        this.status = options.status;
+        this.data = options.data;
+    }
+}
+/** The wording to show for a thrown value, whatever it turned out to be. */
+export function errorMessage(error, fallback = "Something went wrong") {
+    if (error instanceof Error && error.message)
+        return error.message;
+    if (typeof error === "string" && error)
+        return error;
+    return fallback;
+}
+//# sourceMappingURL=errors.js.map

package/dist/ux/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/ux/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,gDAAgD;IACvC,MAAM,CAAU;IACzB;;;OAGG;IACM,IAAI,CAAW;IAExB,YAAY,OAAe,EAAE,UAAgE,EAAE;QAC7F,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,QAAQ,GAAG,sBAAsB;IAC5E,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACrD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/ux/feedback.d.ts

@@ -0,0 +1,23 @@
+import * as React from "react";
+/**
+ * How this layer tells someone what happened, without knowing what the app
+ * uses to tell them.
+ *
+ * A toast library is a design decision, and the whole point of these hooks is
+ * that they can be lifted into a shared package. So the hooks report an event
+ * and the app decides what an event looks like — one provider at the root,
+ * wired to whatever that app already has.
+ */
+export interface ActionFeedback {
+    tone: "success" | "error";
+    title: string;
+    description?: string;
+}
+export type ActionReporter = (feedback: ActionFeedback) => void;
+export declare function ActionFeedbackProvider({ report, children }: {
+    report: ActionReporter;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The app's reporter, or the console fallback. Stable across renders. */
+export declare function useActionReporter(): ActionReporter;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/ux/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/ux/feedback.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;AAchE,wBAAgB,sBAAsB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,qBAEjH;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,IAAI,cAAc,CAElD"}

package/dist/ux/feedback.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+const ReporterContext = React.createContext(null);
+/**
+ * Without a provider a failure still has to go somewhere: swallowing it is how
+ * an optimistic update becomes a lie. The console is a poor place to tell
+ * someone something, but it is not silence, and it shows up in a test.
+ */
+const fallbackReporter = (feedback) => {
+    if (feedback.tone !== "error")
+        return;
+    console.error(`[action] ${feedback.title}${feedback.description ? `: ${feedback.description}` : ""}`);
+};
+export function ActionFeedbackProvider({ report, children }) {
+    return _jsx(ReporterContext.Provider, { value: report, children: children });
+}
+/** The app's reporter, or the console fallback. Stable across renders. */
+export function useActionReporter() {
+    return React.useContext(ReporterContext) ?? fallbackReporter;
+}
+//# sourceMappingURL=feedback.js.map

package/dist/ux/feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.js","sourceRoot":"","sources":["../../src/ux/feedback.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAmB/B,MAAM,eAAe,GAAG,KAAK,CAAC,aAAa,CAAwB,IAAI,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,gBAAgB,GAAmB,CAAC,QAAQ,EAAE,EAAE;IACpD,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO;IACtC,OAAO,CAAC,KAAK,CAAC,YAAY,QAAQ,CAAC,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACxG,CAAC,CAAC;AAEF,MAAM,UAAU,sBAAsB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAyD;IAChH,OAAO,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YAAG,QAAQ,GAA4B,CAAC;AACxF,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB;IAC/B,OAAO,KAAK,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,gBAAgB,CAAC;AAC/D,CAAC"}

package/dist/ux/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@connextar/house/ux` — the interface answers the click.
+ *
+ * Optimistic updates and pending state, with no framework in them: React, and
+ * nothing else. The half that needs Next — the navigation bar and the spinner
+ * on the link you clicked — is `@connextar/house/ux/navigation`, kept apart so
+ * that `next` stays the optional peer dependency it is declared to be. A
+ * barrel that re-exported both made it mandatory for anyone importing so much
+ * as the pure patch engine, which a smoke test caught before 0.3.0 shipped.
+ *
+ * What this module needs from the host arrives as a function (`commit`), a
+ * provider (`ActionFeedbackProvider`) or a class name — never as an import.
+ */
+export { ActionError, errorMessage } from "./errors.js";
+export { ActionFeedbackProvider, useActionReporter, type ActionFeedback, type ActionReporter } from "./feedback.js";
+export { applyPatches, isRedundant, isTempKey, reconcile, sameRow, settlePatch, shouldDropSettled, supersede, tempKey, type Patch, type PatchKind, type RowKey, } from "./optimistic.js";
+export { useAction, useKeyedAction, type Action, type ActionOptions, type KeyedAction } from "./use-action.js";
+export { useOptimisticList, type OptimisticList, type OptimisticListOptions, type WriteOptions, } from "./use-optimistic-list.js";
+export { useOptimisticValue, type OptimisticValue, type OptimisticValueOptions } from "./use-optimistic-value.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ux/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,MAAM,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/ux/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@connextar/house/ux` — the interface answers the click.
+ *
+ * Optimistic updates and pending state, with no framework in them: React, and
+ * nothing else. The half that needs Next — the navigation bar and the spinner
+ * on the link you clicked — is `@connextar/house/ux/navigation`, kept apart so
+ * that `next` stays the optional peer dependency it is declared to be. A
+ * barrel that re-exported both made it mandatory for anyone importing so much
+ * as the pure patch engine, which a smoke test caught before 0.3.0 shipped.
+ *
+ * What this module needs from the host arrives as a function (`commit`), a
+ * provider (`ActionFeedbackProvider`) or a class name — never as an import.
+ */
+export { ActionError, errorMessage } from "./errors.js";
+export { ActionFeedbackProvider, useActionReporter } from "./feedback.js";
+export { applyPatches, isRedundant, isTempKey, reconcile, sameRow, settlePatch, shouldDropSettled, supersede, tempKey, } from "./optimistic.js";
+export { useAction, useKeyedAction } from "./use-action.js";
+export { useOptimisticList, } from "./use-optimistic-list.js";
+export { useOptimisticValue } from "./use-optimistic-value.js";
+//# sourceMappingURL=index.js.map

package/dist/ux/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAA4C,MAAM,eAAe,CAAC;AACpH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,OAAO,GAIR,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAqD,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EACL,iBAAiB,GAIlB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAqD,MAAM,2BAA2B,CAAC"}

package/dist/ux/navigation-index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@connextar/house/ux/navigation` — feedback for moving between screens.
+ *
+ * Its own entry point because it is the only part of `ux` that imports `next`,
+ * which is an optional peer dependency: an app on another framework (or any
+ * app's Vitest suite running under plain Node) can still have the optimistic
+ * hooks from `@connextar/house/ux` without Next installed.
+ */
+export { BUSY_ATTRIBUTE, NavigationProgress, startNavigation, startRouteProgress, useAppRouter, useNavigate, } from "./navigation-progress.js";
+//# sourceMappingURL=navigation-index.d.ts.map

package/dist/ux/navigation-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-index.d.ts","sourceRoot":"","sources":["../../src/ux/navigation-index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/ux/navigation-index.js

@@ -0,0 +1,10 @@
+/**
+ * `@connextar/house/ux/navigation` — feedback for moving between screens.
+ *
+ * Its own entry point because it is the only part of `ux` that imports `next`,
+ * which is an optional peer dependency: an app on another framework (or any
+ * app's Vitest suite running under plain Node) can still have the optimistic
+ * hooks from `@connextar/house/ux` without Next installed.
+ */
+export { BUSY_ATTRIBUTE, NavigationProgress, startNavigation, startRouteProgress, useAppRouter, useNavigate, } from "./navigation-progress.js";
+//# sourceMappingURL=navigation-index.js.map

package/dist/ux/navigation-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-index.js","sourceRoot":"","sources":["../../src/ux/navigation-index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,WAAW,GACZ,MAAM,0BAA0B,CAAC"}

package/dist/ux/navigation-progress.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+/** The attribute every busy control carries, action or navigation alike. */
+export declare const BUSY_ATTRIBUTE = "data-busy";
+/**
+ * Show the navigation feedback for something this module cannot see on its
+ * own — a programmatic `router.push`. Pass the control that caused it and it
+ * gets the spinner too.
+ */
+export declare function startNavigation(element?: Element | null): void;
+/** Backwards-compatible alias for the original name. */
+export declare const startRouteProgress: typeof startNavigation;
+/**
+ * `useRouter`, with the navigation feedback attached to `push` and `replace`.
+ *
+ * A click that runs `router.push(href)` is invisible to the watcher above —
+ * there is no anchor and no popstate — so those navigations were the ones with
+ * no feedback at all. The worst case is the one right after a save: the
+ * button's own spinner stops when the write lands, and then nothing happens
+ * for as long as the next screen takes to render.
+ *
+ * Swapping the import is the whole change; no call site moves. `refresh`,
+ * `back`, `forward` and `prefetch` pass straight through — a refresh re-renders
+ * the screen you are already on, which needs no bar.
+ */
+export declare function useAppRouter(): {
+    push: (href: string, options?: import("next/dist/shared/lib/app-router-context.shared-runtime.js").NavigateOptions | undefined) => void;
+    replace: (href: string, options?: import("next/dist/shared/lib/app-router-context.shared-runtime.js").NavigateOptions | undefined) => void;
+    back(): void;
+    forward(): void;
+    refresh(): void;
+    prefetch(href: string, options?: import("next/dist/shared/lib/app-router-context.shared-runtime.js").PrefetchOptions): void;
+    experimental_gesturePush?(href: string, options?: import("next/dist/shared/lib/app-router-context.shared-runtime.js").NavigateOptions): void;
+    bfcacheId: string;
+};
+/**
+ * `router.push` with the feedback attached, and the control that caused it
+ * marked as busy. For a button that navigates rather than saves.
+ */
+export declare function useNavigate(): (href: string, options?: {
+    replace?: boolean;
+    element?: Element | null;
+}) => void;
+/**
+ * Mount once, above everything else — including anything that suspends, or the
+ * bar disappears for exactly the navigations it is there for.
+ *
+ * `className` styles the filled part of the bar, so the host app picks its own
+ * colour without this module knowing any of its tokens.
+ */
+export declare function NavigationProgress({ className }: {
+    className?: string;
+}): React.JSX.Element;
+//# sourceMappingURL=navigation-progress.d.ts.map

package/dist/ux/navigation-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-progress.d.ts","sourceRoot":"","sources":["../../src/ux/navigation-progress.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAgC/B,4EAA4E;AAC5E,eAAO,MAAM,cAAc,cAAc,CAAC;AAqB1C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAI9D;AAED,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,wBAAkB,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY;;;;;;;;;EAkB3B;AAED;;;GAGG;AACH,wBAAgB,WAAW,WAGhB,MAAM,YAAY;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,UAO3E;AA0ID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,SAAS,EAAE,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,qBAMvE"}