@connextar/house 0.3.0 → 0.5.0

package/README.md

@@ -47,6 +47,19 @@ 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`
@@ -305,6 +318,179 @@ learned the hard way:
 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.
+
+### `@connextar/house/setup-guide`
+
+The checklist a new account works through, and what finishing a step earns.
+
+The checklist is not the hard part. The three things underneath it are, and each
+has one right answer:
+
+- **What is done is never stored.** A step is done when the account _holds_ what
+  it asks for — a learner, a price, a published course — read fresh every time.
+  So a thing made from the grid, from an import, or by an administrator counts
+  exactly as much as one made from the guide, and there is no status column to
+  drift away from the truth.
+- **A reward is paid once.** That is the only thing written down: one entry per
+  step per account, keyed on the step, refused by a unique index the second
+  time. Two tabs asking at the same moment pay one reward between them.
+- **It is said while the person is still looking at what earned it.** Most saves
+  never refresh a page, so the guide listens for the app's own write event,
+  waits for a burst of saves to settle, and asks once.
+
+```tsx
+const ITEMS: SetupItemDef[] = [
+  {
+    key: "learner",
+    title: "Add your first learner",
+    description: "Every timetable, task and plan hangs off a learner.",
+    href: "/dashboard?add=learner",
+    actionLabel: "Add your first learner",
+    steps: [
+      {
+        key: "learner.add", // permanent: the reward is keyed on it
+        title: "Add your first learner",
+        reward: 5,
+        how: { title: "How to add a learner", steps: ["Select **Add learner**.", "Type their _name_."] },
+        guide: { href: "/guides/learners#add-a-learner", title: "Learners" },
+      },
+    ],
+  },
+];
+
+<SetupGuideProvider
+  initial={guideFromTheServer}
+  transport={{ sync, setHidden }} // your API calls; this package makes none
+  words={{ one: "AI credit", many: "AI credits" }}
+  changeEvent="myapp:data-changed"
+  link={NextLink}
+>
+  <SetupCard variant="full" title="Let's get you set up" lead="A few things to do." />
+</SetupGuideProvider>;
+```
+
+**Three surfaces.** `SetupCard` leads a home page (`full`) or sits as one band
+above it once there is real work to show (`compact`). `SetupStrip` goes on the
+screen where an item's steps are actually done, with a progress bar, and
+disappears the moment they are all paid — a screen somebody uses every day
+should not keep a checklist on it for ever. `SetupLauncherButton` is the header
+pill. Each step carries an ⓘ with how to do it and a link to its guide.
+
+**The panel is yours.** Every app already has a sheet, with its own idea of how
+a thing slides in and what closes it, so this ships what goes _inside_ one:
+
+```tsx
+<SetupLauncherButton />
+<Sheet open={setup.panelOpen} onOpenChange={setup.setPanelOpen}>
+  <SheetContent>
+    <SetupGuideSummary />
+    <SetupGuideList onGo={() => setup.setPanelOpen(false)} />
+  </SheetContent>
+</Sheet>
+```
+
+**What the host supplies** is everything genuinely its own: the step
+definitions, how each is read from its records, where the reward is written, and
+what a reward is even called. `rewardsOwed(items, done, earned)` is the pure
+half of paying — the host loops over it and writes one row each, letting its own
+unique index refuse the second. `doneSteps(facts, earned)` is the other rule
+worth not rewriting: a reward, once earned, is not taken back, so a step whose
+thing has since been deleted stays ticked rather than reopening and asking to be
+paid again.
+
+An app that gives nothing at all leaves `reward` off every step and gets a
+checklist that still works. `src/setup-guide/entry-points.test.ts` holds the
+module to React and its icons — no router, no toast library, no design system —
+because the moment it reaches for one of those, the claim that six apps can host
+it stops being true.
+
 ### Styles — `@connextar/house/house.css`
 
 What the components need that utility classes cannot say: rich text, the editor's
@@ -335,9 +521,19 @@ added.
 
 (The `@source` path is relative to the stylesheet.)
 
-**Tailwind v3** — add `"./node_modules/@connextar/house/dist/**/*.js"` to
-`content` in `tailwind.config`, and import `@connextar/house/house.css` at the top
-of the global stylesheet, before the `@tailwind` directives.
+**Tailwind v3** — three pieces, and two of them were only found by adopting it:
+
+1. Add `"./node_modules/@connextar/house/dist/**/*.js"` to `content` in
+   `tailwind.config`.
+2. Import the file by its real path, `@connextar/house/dist/house.css`, at the top
+   of the global stylesheet, before the `@tailwind` directives. **Not** the
+   `@connextar/house/house.css` export the v4 setup uses: `postcss-import`
+   resolves a bare specifier with the classic `node_modules` algorithm, which
+   predates `exports` maps, so the export name fails the build outright.
+3. Run `postcss-import` ahead of Tailwind in `postcss.config`, so the import is
+   inlined into the app's own stylesheet. Left to the bundler, `house.css`
+   arrives as its own PostCSS entry, where its `@layer components` block has no
+   matching `@tailwind components` directive and the build fails.
 
 `house.css` reads the app's theme tokens (`--foreground`, `--muted-foreground`,
 `--primary`, `--muted`, `--border`, `--card`, `--accent`) through a `--house-*`
@@ -407,11 +603,51 @@ 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
-  nothing.
+  `/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`.
+- **Both factories must hand back the same spies.** The two specifiers resolve to
+  one module, so the second registration wins. A fresh `vi.fn()` in the second
+  factory silently replaces the first, and an assertion on `router.refresh` then
+  watches a spy nothing ever called — a test that passes while proving nothing.
+  Build the spies once at module scope and return those from both factories.
+- **A locale-aware app inlines its i18n package too.** `next-intl`'s
+  `createNavigation` also imports `next/navigation` extensionlessly, so with only
+  the package inlined the whole suite fails to load: `inline: [/@connextar\/house/, /next-intl/]`.
+  For the same reason an app whose router is locale-aware keeps its own
+  `useAppRouter` over `next-intl`'s router — swapping in the package's would drop
+  the locale prefix from every push, silently.
 
 **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
@@ -421,7 +657,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/setup-guide/bits.d.ts

@@ -0,0 +1,89 @@
+import * as React from "react";
+import { type SetupGuideClassNames } from "./class-names.js";
+import { type RewardWords, type SetupLinkComponent } from "./context.js";
+import type { GuideItem, SetupGuideLink, SetupHowTo, StepState } from "./guide.js";
+/** The small parts every drawing of the guide shares. */
+export type ClassNameOverrides = Partial<SetupGuideClassNames>;
+export declare function useClassNames(overrides?: ClassNameOverrides): SetupGuideClassNames;
+/** The words and the link component, with sane answers outside a provider so a part can be rendered alone. */
+export declare function useGuideChrome(): {
+    words: RewardWords;
+    Link: SetupLinkComponent;
+};
+export type RewardState = "todo" | "earned" | "on-complete";
+/** What a step pays. */
+export declare function RewardChip({ reward, state, tone, words, className, classNames, }: {
+    reward: number;
+    state?: RewardState;
+    tone?: "light" | "dark";
+    words?: RewardWords;
+    className?: string;
+    classNames?: ClassNameOverrides;
+}): React.JSX.Element;
+export declare function StepCircle({ state, n, size, className, classNames, }: {
+    state: StepState;
+    n?: number;
+    size?: "sm" | "md";
+    className?: string;
+    classNames?: ClassNameOverrides;
+}): React.JSX.Element;
+/** The share earned, as a ring with the number inside. */
+export declare function RewardRing({ earned, total, size, tone, words, }: {
+    earned: number;
+    total: number;
+    size?: number;
+    tone?: "dark" | "light";
+    words?: RewardWords;
+}): React.JSX.Element;
+/** A small progress ring, for a header. */
+export declare function ProgressRing({ value, size }: {
+    value: number;
+    size?: number;
+}): React.JSX.Element;
+/** One bar per item, lit when it is done. */
+export declare function Segments({ done, total, tone, classNames, }: {
+    done: number;
+    total: number;
+    tone?: "dark" | "light";
+    classNames?: ClassNameOverrides;
+}): React.JSX.Element;
+export declare function MiniProgress({ done, total, className }: {
+    done: number;
+    total: number;
+    className?: string;
+}): React.JSX.Element;
+/** `**label**` in bold and `_example_` in italics — the only markup the instructions use. */
+export declare function HowText({ text }: {
+    text: string;
+}): React.JSX.Element;
+/**
+ * The ⓘ: how to do this step, beside the step itself.
+ *
+ * Built here rather than on a popover library, because this package cannot pick
+ * one for six apps. It is a disclosure, not a dialog: Escape closes it, a click
+ * outside closes it, and focus is left where the person put it — nothing here
+ * is worth trapping focus for.
+ */
+export declare function HowToButton({ how, guide, footer, className, classNames, }: {
+    how: SetupHowTo;
+    guide?: SetupGuideLink;
+    footer?: React.ReactNode;
+    className?: string;
+    classNames?: ClassNameOverrides;
+}): React.JSX.Element;
+/** The book: the guide for the feature, in a new tab. */
+export declare function GuideIconLink({ guide, className, classNames, }: {
+    guide?: SetupGuideLink;
+    className?: string;
+    classNames?: ClassNameOverrides;
+}): React.JSX.Element | null;
+/**
+ * Both icons for one step — or, for an item with several, its steps listed in
+ * the ⓘ and the first step's guide on the book.
+ */
+export declare function ItemHelp({ item, className, classNames, }: {
+    item: GuideItem;
+    className?: string;
+    classNames?: ClassNameOverrides;
+}): React.JSX.Element | null;
+//# sourceMappingURL=bits.d.ts.map

package/dist/setup-guide/bits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.d.ts","sourceRoot":"","sources":["../../src/setup-guide/bits.tsx"],"names":[],"mappings":"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"}

package/dist/setup-guide/bits.js

@@ -0,0 +1,134 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { BookOpen, Check, Info, Sparkles } from "lucide-react";
+import * as React from "react";
+import { cx } from "../internal/cx.js";
+import { SETUP_GUIDE_CLASS_NAMES } from "./class-names.js";
+import { rewardWord, useSetupGuide } from "./context.js";
+export function useClassNames(overrides) {
+    return React.useMemo(() => ({ ...SETUP_GUIDE_CLASS_NAMES, ...overrides }), [overrides]);
+}
+/** The words and the link component, with sane answers outside a provider so a part can be rendered alone. */
+export function useGuideChrome() {
+    const setup = useSetupGuide();
+    const fallback = React.useCallback(({ children, ...rest }) => _jsx("a", { ...rest, children: children }), []);
+    return { words: setup?.words ?? { one: "credit", many: "credits" }, Link: setup?.Link ?? fallback };
+}
+/** What a step pays. */
+export function RewardChip({ reward, state = "todo", tone = "light", words, className, classNames, }) {
+    const c = useClassNames(classNames);
+    const chrome = useGuideChrome();
+    const said = words ?? chrome.words;
+    const unit = rewardWord(reward, said);
+    if (state === "earned") {
+        return (_jsxs("span", { className: cx(c.chipEarned, tone === "dark" && "text-white", className), children: [_jsx(Check, { className: "size-3.5", "aria-hidden": true }), reward, " earned", _jsxs("span", { className: c.srOnly, children: [" ", unit] })] }));
+    }
+    return (_jsxs("span", { className: cx(c.chip, tone === "dark" && c.chipDark, state === "on-complete" && tone !== "dark" && c.chipOnComplete, className), children: [_jsx(Sparkles, { className: "size-3", "aria-hidden": true }), "+", reward, state === "on-complete" ? " on build" : null, _jsxs("span", { className: c.srOnly, children: [" ", unit] })] }));
+}
+export function StepCircle({ state, n, size = "md", className, classNames, }) {
+    const c = useClassNames(classNames);
+    return (_jsx("span", { "aria-hidden": true, className: cx(c.circle, size === "sm" ? "size-6" : "size-7", state === "done" && c.circleDone, state === "next" && c.circleNext, state === "ready" && c.circleReady, state === "todo" && c.circleTodo, className), children: state === "done" || state === "ready" ? _jsx(Check, { className: size === "sm" ? "size-3.5" : "size-4" }) : n }));
+}
+/** The share earned, as a ring with the number inside. */
+export function RewardRing({ earned, total, size = 84, tone = "dark", words, }) {
+    const chrome = useGuideChrome();
+    const said = words ?? chrome.words;
+    const share = total === 0 ? 0 : Math.round((earned / total) * 100);
+    return (_jsx("span", { role: "img", "aria-label": `${earned} of ${total} ${rewardWord(total, said)} earned`, className: "flex shrink-0 items-center justify-center rounded-full", style: {
+            width: size,
+            height: size,
+            background: tone === "dark"
+                ? `conic-gradient(#ffffff 0 ${share}%, rgb(255 255 255 / 0.12) 0)`
+                : `conic-gradient(var(--primary) 0 ${share}%, color-mix(in oklab, var(--primary) 14%, transparent) 0)`,
+        }, children: _jsxs("span", { className: cx("flex flex-col items-center justify-center rounded-full leading-none", tone === "dark" ? "bg-[#0e2f27] text-white" : "bg-card text-foreground"), style: { width: size - 14, height: size - 14 }, children: [_jsx("span", { className: "font-bold", style: { fontSize: Math.round(size * 0.34) }, children: earned }), _jsxs("span", { className: cx("mt-1 text-[11px]", tone === "dark" ? "text-slate-400" : "text-muted-foreground"), children: ["of ", total] })] }) }));
+}
+/** A small progress ring, for a header. */
+export function ProgressRing({ value, size = 24 }) {
+    return (_jsx("span", { "aria-hidden": true, className: "flex shrink-0 items-center justify-center rounded-full", style: {
+            width: size,
+            height: size,
+            background: `conic-gradient(var(--primary) 0 ${value}%, var(--secondary) 0)`,
+        }, children: _jsx("span", { className: "block rounded-full bg-background", style: { width: size - 8, height: size - 8 } }) }));
+}
+/** One bar per item, lit when it is done. */
+export function Segments({ done, total, tone = "dark", classNames, }) {
+    const c = useClassNames(classNames);
+    return (_jsx("div", { className: "flex gap-1.5", "aria-hidden": true, children: Array.from({ length: total }, (_, index) => (_jsx("span", { className: cx(c.segment, index < done
+                ? tone === "dark"
+                    ? c.segmentDoneDark
+                    : c.segmentDone
+                : tone === "dark"
+                    ? c.segmentTodoDark
+                    : c.segmentTodo) }, index))) }));
+}
+export function MiniProgress({ done, total, className }) {
+    return (_jsxs("span", { className: cx("inline-flex items-center gap-2", className), children: [_jsx("span", { className: "h-1.5 w-20 overflow-hidden rounded-full bg-secondary", "aria-hidden": true, children: _jsx("span", { className: "block h-full rounded-full bg-primary", style: { width: `${total === 0 ? 0 : Math.round((done / total) * 100)}%` } }) }), _jsxs("span", { className: "text-xs text-muted-foreground tabular-nums", children: [done, " of ", total, " done"] })] }));
+}
+/** `**label**` in bold and `_example_` in italics — the only markup the instructions use. */
+export function HowText({ text }) {
+    const parts = text.split(/(\*\*[^*]+\*\*|_[^_]+_)/g).filter(Boolean);
+    return (_jsx(_Fragment, { children: parts.map((part, index) => part.startsWith("**") && part.endsWith("**") && part.length > 4 ? (_jsx("strong", { className: "font-semibold", children: part.slice(2, -2) }, index)) : part.startsWith("_") && part.endsWith("_") && part.length > 2 ? (_jsx("em", { children: part.slice(1, -1) }, index)) : (_jsx("span", { children: part }, index))) }));
+}
+/**
+ * The ⓘ: how to do this step, beside the step itself.
+ *
+ * Built here rather than on a popover library, because this package cannot pick
+ * one for six apps. It is a disclosure, not a dialog: Escape closes it, a click
+ * outside closes it, and focus is left where the person put it — nothing here
+ * is worth trapping focus for.
+ */
+export function HowToButton({ how, guide, footer, className, classNames, }) {
+    const c = useClassNames(classNames);
+    const { Link } = useGuideChrome();
+    const [open, setOpen] = React.useState(false);
+    const wrapper = React.useRef(null);
+    const panelId = React.useId();
+    React.useEffect(() => {
+        if (!open)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === "Escape")
+                setOpen(false);
+        };
+        const onPointerDown = (event) => {
+            const node = event.target;
+            if (node instanceof Node && wrapper.current?.contains(node))
+                return;
+            setOpen(false);
+        };
+        document.addEventListener("keydown", onKeyDown);
+        document.addEventListener("mousedown", onPointerDown);
+        return () => {
+            document.removeEventListener("keydown", onKeyDown);
+            document.removeEventListener("mousedown", onPointerDown);
+        };
+    }, [open]);
+    return (_jsxs("span", { ref: wrapper, className: "relative inline-flex", children: [_jsx("button", { type: "button", onClick: () => setOpen((current) => !current), "aria-expanded": open, "aria-controls": open ? panelId : undefined, "aria-label": how.title, title: how.title, className: cx(c.iconButton, className), children: _jsx(Info, { className: "size-4", "aria-hidden": true }) }), open ? (_jsxs("span", { id: panelId, role: "group", "aria-label": how.title, className: c.popover, children: [_jsx("span", { className: cx(c.popoverTitle, "block"), children: how.title }), _jsx("ol", { className: "mt-3 flex flex-col gap-2", children: how.steps.map((step, index) => (_jsxs("li", { className: c.popoverStep, children: [_jsx("span", { "aria-hidden": true, className: c.popoverNumber, children: index + 1 }), _jsx("span", { children: _jsx(HowText, { text: step }) })] }, index))) }), footer, guide ? (_jsxs("span", { className: cx(c.popoverFooter, "flex"), children: [_jsxs(Link, { href: guide.href, target: "_blank", rel: "noopener", className: "inline-flex items-center gap-1.5 text-[13px] font-medium text-primary underline-offset-4 hover:underline", children: [_jsx(BookOpen, { className: "size-3.5", "aria-hidden": true }), guide.title, " guide"] }), _jsx("span", { className: "text-xs text-muted-foreground", children: "Opens in a new tab" })] })) : null] })) : null] }));
+}
+/** The book: the guide for the feature, in a new tab. */
+export function GuideIconLink({ guide, className, classNames, }) {
+    const c = useClassNames(classNames);
+    const { Link } = useGuideChrome();
+    if (!guide)
+        return null;
+    const label = `Guide: ${guide.title}`;
+    return (_jsx(Link, { href: guide.href, target: "_blank", rel: "noopener", "aria-label": label, title: label, className: cx(c.iconButton, className), children: _jsx(BookOpen, { className: "size-4", "aria-hidden": true }) }));
+}
+/**
+ * Both icons for one step — or, for an item with several, its steps listed in
+ * the ⓘ and the first step's guide on the book.
+ */
+export function ItemHelp({ item, className, classNames, }) {
+    const { words } = useGuideChrome();
+    const [first] = item.steps;
+    if (!first)
+        return null;
+    if (item.steps.length === 1) {
+        return (_jsxs("span", { className: cx("inline-flex items-center", className), children: [first.how ? _jsx(HowToButton, { how: first.how, guide: first.guide, classNames: classNames }) : null, _jsx(GuideIconLink, { guide: first.guide, classNames: classNames })] }));
+    }
+    return (_jsxs("span", { className: cx("inline-flex items-center", className), children: [_jsx(HowToButton, { classNames: classNames, how: {
+                    title: `What “${item.title}” asks for`,
+                    steps: item.steps.map((step) => `${step.done ? "Done — " : ""}**${step.title}**${step.reward > 0 ? ` · ${step.reward} ${rewardWord(step.reward, words)}` : ""}`),
+                }, guide: first.guide, footer: _jsxs("p", { className: "mt-3 text-xs text-muted-foreground", children: ["Each step, with how to do it, is on the screen it's done on.", item.paysOnComplete ? " Its rewards land once the whole thing is built." : ""] }) }), _jsx(GuideIconLink, { guide: first.guide, classNames: classNames })] }));
+}
+//# sourceMappingURL=bits.js.map

package/dist/setup-guide/bits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.js","sourceRoot":"","sources":["../../src/setup-guide/bits.tsx"],"names":[],"mappings":"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"}

package/dist/setup-guide/card.d.ts

@@ -0,0 +1,33 @@
+import * as React from "react";
+import { type ClassNameOverrides } from "./bits.js";
+/** Replaces an item's — or one step's — default action, by its key. */
+export type SetupActions = Partial<Record<string, React.ReactNode>>;
+export interface SetupCardProps {
+    /**
+     * `full` leads a page that has little else on it: the band with what has been
+     * earned, and every item as a row. `compact` is one band above the day's work
+     * once the account has some, showing progress and what is next.
+     */
+    variant: "full" | "compact";
+    title: string;
+    lead: string;
+    /** Extra words under the progress in the band. */
+    aside?: React.ReactNode;
+    actions?: SetupActions;
+    /** An item whose steps are done on this very page, listed inside its row. */
+    inlineItemKey?: string;
+    /** What to show when there is no guide to draw — hidden, or an account without one. */
+    fallback?: React.ReactNode;
+    /** Shown when every step is done and paid, e.g. a link to what was earned. */
+    completeAction?: React.ReactNode;
+    /** How long the whole thing takes, if the app wants to promise. */
+    timeNote?: string;
+    /** A line about what the reward is for, under the ring. */
+    rewardNote?: string;
+    /** Replaces the band's background outright. `{}` falls back to the card's own. */
+    bandStyle?: React.CSSProperties;
+    className?: string;
+    classNames?: ClassNameOverrides;
+}
+export declare function SetupCard({ variant, title, lead, aside, actions, inlineItemKey, fallback, completeAction, timeNote, rewardNote, bandStyle, className, classNames, }: SetupCardProps): React.JSX.Element;
+//# sourceMappingURL=card.d.ts.map

package/dist/setup-guide/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../src/setup-guide/card.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAUL,KAAK,kBAAkB,EACxB,MAAM,WAAW,CAAC;AAKnB,uEAAuE;AACvE,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAEpE,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,8EAA8E;IAC9E,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED,wBAAgB,SAAS,CAAC,EACxB,OAAO,EACP,KAAK,EACL,IAAI,EACJ,KAAK,EACL,OAAY,EACZ,aAAa,EACb,QAAe,EACf,cAAc,EACd,QAAQ,EACR,UAAU,EACV,SAA4B,EAC5B,SAAS,EACT,UAAU,GACX,EAAE,cAAc,qBAiJhB"}