@connextar/house 0.1.1 → 0.3.0

package/README.md

@@ -12,16 +12,16 @@ small, and the reason it is small is worth reading before adding to it.
 The portfolio was measured before anything was extracted. Divergence, against
 Quickie, of files that exist in six or more apps:
 
-| File | copies | divergence |
-| --- | --- | --- |
-| `error-shell.tsx` | 6/6 | **0%** |
-| `check-motion.mjs` | 3/6 | 11% |
-| `e2e-local.sh` | 6/6 | 30% |
-| `button.tsx` | 6/6 | 42% |
-| `dialog.tsx` | 5/6 | 62% |
-| `card.tsx` | 5/6 | 106% |
-| `lib/api.ts` | 6/6 | 152% |
-| `auth.ts` | 4/6 | 42–103% |
+| File               | copies | divergence |
+| ------------------ | ------ | ---------- |
+| `error-shell.tsx`  | 6/6    | **0%**     |
+| `check-motion.mjs` | 3/6    | 11%        |
+| `e2e-local.sh`     | 6/6    | 30%        |
+| `button.tsx`       | 6/6    | 42%        |
+| `dialog.tsx`       | 5/6    | 62%        |
+| `card.tsx`         | 5/6    | 106%       |
+| `lib/api.ts`       | 6/6    | 152%       |
+| `auth.ts`          | 4/6    | 42–103%    |
 
 Everything below about 15% is an extraction. Everything above it is a rewrite
 wearing an extraction's clothes, and pulling it in here would mean thirteen apps
@@ -35,6 +35,18 @@ That is why there is no `Button` here, and why the error shell takes its actions
 as props instead of rendering its own. Bringing a second design system into an
 app that already has one is a cost with no matching benefit.
 
+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.
+
 ## Modules
 
 ### `@connextar/house/errors`
@@ -79,7 +91,7 @@ decorative: a stolen mailbox is still enough.
 
 This module decides which routes to refuse, and why. It is here rather than in
 each app because it has to be the same everywhere and because getting it wrong is
-silent — two-factor keeps *looking* enabled while doing nothing.
+silent — two-factor keeps _looking_ enabled while doing nothing.
 
 The lookup is injected, because only the app knows its own user table:
 
@@ -100,7 +112,7 @@ TOTP. A link in an inbox is.
 ### `@connextar/house/account`
 
 The contract for "your data" and "delete my account" — types, the export notice,
-and the sole-owner refusal message. The *implementation* stays per-app, because
+and the sole-owner refusal message. The _implementation_ stays per-app, because
 an export is a walk over that app's Prisma schema. What must not be per-app is
 the shape of the answer, since that is what a person receives and a regulator
 reads.
@@ -119,9 +131,234 @@ Two decisions are encoded here rather than left to be rediscovered:
 App-specific sections go in `extras`, so one app's furniture does not become
 everyone's obligation.
 
+### `@connextar/house/release`
+
+Version arithmetic and the release-history guard behind every app's changelog.
+`releaseHistoryProblems(changelog, { pkg, lock })` returns, as sentences, every
+way the changelog, `package.json` and the lockfile disagree — a version that
+skips a step, dates out of order, a release with no title. An app's
+`lib/release.test.ts` asserts it is empty. `nextVersion(current, kind)` applies
+the 0.x rule (a MAJOR-class change bumps the minor before 1.0.0).
+
+The process itself — how to classify a change, how to write the notes, the
+runbook — is [`docs/ReleaseProcess.md`](docs/ReleaseProcess.md), shipped in the
+package. Each app's own `docs/operations/ReleaseProcess.md` links to it and adds
+only what is its own: its public API, its trigger documents, its history note.
+
+### `@connextar/house/changelog`
+
+`<Changelog releases={CHANGELOG} />` — the body of a `/changelog` page. Each
+release shows its version, whether it was a major, minor or patch release, its
+date and a one-line summary; changes are grouped under headings, each with a bold
+headline and a tag. A list of releases sits beside the content on wide screens
+and becomes a scrolling strip on a phone. The app keeps its hero and calls to
+action around it, and maps the four change types onto its palette with
+`tagClassNames`.
+
+### `@connextar/house/markdown`
+
+The help-centre guide renderer, and the GitHub-flavoured table parser under it.
+Five apps carried a copy that had drifted: some rendered tables as a paragraph of
+pipes, some broke a wrapped list line into a stray paragraph, some passed
+`javascript:` links through, and three let an `####` heading shift the numbering
+of the `##` anchors after it. `GuideMarkdown` is the union of the fixes;
+`extractHeadings` gives exactly the ids it renders.
+
+An app's `lib/markdown.tsx` becomes a thin binding that keeps its own export names,
+so no page changes:
+
+```tsx
+import { GuideMarkdown } from "@connextar/house/markdown";
+
+import { constants } from "@lib/constants";
+
+export {
+  extractHeadings as extractGuideHeadings,
+  extractHowToSteps,
+  parseGuideFrontmatter,
+  stripInline,
+} from "@connextar/house/markdown";
+
+export function Markdown({ content }: { content: string }) {
+  return <GuideMarkdown content={content} guidesPath={constants.routes.guides} />;
+}
+```
+
+`classNames` replaces the look of any element for an app without theme tokens.
+
+### `@connextar/house/trail`
+
+Where you came from, rather than where the URL says you are. A breadcrumb built
+from the path can only show the hierarchy the routes happen to have; a trail
+shows the chain the person actually walked — a learner, then their plan, then a
+lesson — and keeps it when they follow a reference to somewhere else.
+
+Pages declare their chain (`useTrail(chain)` or `<TrailHere chain={…} />`); the
+trail lives per tab in session storage under a `scope`; a link marked
+`data-trail-carry` (every internal link in `RichTextContent`) carries it across.
+`<TrailRail />` draws it as pills down the left on wide screens, `<TrailBar />` as
+a pinned bar with Back on phones.
+
+```tsx
+// components/navigation/dashboard-shell.tsx
+"use client";
+import { ScrollToHash, TrailBar, TrailProvider, TrailRail } from "@connextar/house/trail";
+
+// `scope` keeps one signed-in person's trail from surfacing for the next on a shared browser.
+export function DashboardShell({ userId, children }: { userId: string; children: React.ReactNode }) {
+  return (
+    <TrailProvider scope={userId}>
+      <ScrollToHash />
+      <div className="flex">
+        <TrailRail top="4rem" />
+        <main className="min-w-0 flex-1">
+          <TrailBar top="4rem" />
+          {children}
+        </main>
+      </div>
+    </TrailProvider>
+  );
+}
+```
+
+### `@connextar/house/editor`, `/editor/content`, `/editor/emoji`
+
+`RichTextEditor` — Notion-style writing for any prose field. Formatting appears
+as a bubble over a selection (with Turn into); new blocks come from typing `/` or
+the `+` beside a block; every block has a grip to drag or open its menu (turn
+into, duplicate, move up, move down, delete); `:` completes an emoji shortcode.
+`@` references and `#` tags work when the app passes `sources`, because only the
+app knows what its people, records and tags are. **Storage is plain Markdown with
+no new node types** — a reference is `[@Ann Lee](/people/1)` — so every existing
+text column keeps working and a server can read mentions with a regex.
+
+`RichTextContent` (from `/editor/content`) is the read-only side: Markdown to
+React with no HTML, an allow-list of link schemes, and bounded patterns, safe for
+text a stranger wrote. `EmojiPicker` and the curated set of ~360 emoji are in
+`/editor` and `/editor/emoji`.
+
+The editor draws its own menus and popovers on Radix with the house token
+classes. They are internal and not exported: the apps' primitive sets differ too
+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.
+
+### 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, 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)
+
+Tailwind does not scan `node_modules`. Every utility class that appears only
+inside this package is silently missing from an app's build unless the app
+points Tailwind at it. This was measured, not assumed: a probe compile of an
+app's stylesheet emitted none of the package's classes until the line below was
+added.
+
+**Tailwind v4** — in the global stylesheet:
+
+```css
+@import "tailwindcss";
+@import "@connextar/house/house.css";
+@source "../node_modules/@connextar/house/dist";
+```
+
+(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.
+
+`house.css` reads the app's theme tokens (`--foreground`, `--muted-foreground`,
+`--primary`, `--muted`, `--border`, `--card`, `--accent`) through a `--house-*`
+variable at each use. An app that stores tokens as HSL triplets
+(`--primary: 222 47% 11%`) maps them once:
+
+```css
+:root {
+  --house-foreground: hsl(var(--foreground));
+  --house-muted-foreground: hsl(var(--muted-foreground));
+  --house-primary: hsl(var(--primary));
+  --house-muted: hsl(var(--muted));
+  --house-border: hsl(var(--border));
+  --house-card: hsl(var(--card));
+  --house-accent: hsl(var(--accent));
+}
+```
+
 ## Publishing
 
-The scope is public and the contents are a design system and two policy modules —
+The scope is public and the contents are shared components and policy modules —
 nothing here is a secret. Public publishing is what keeps thirteen repositories
 across two GitHub owners able to install it with no token in any Vercel project,
 which is the failure mode that would otherwise take every deploy down at once.
@@ -136,24 +373,45 @@ npm publish            # publishConfig.access is already "public"
 
 ## Adopting it in an app
 
-Once published:
-
 ```bash
 npm install @connextar/house
 ```
 
-Then replace the local copies. For Quickie the exact change is saved as a patch,
-generated from the working migration and verified against a real packed tarball:
-
-```bash
-git apply ../../Shared/cx-house/migrations/quickie-adopt-house.patch
-npm run check && npm test && npm run build
-```
-
-For the other apps the shape is the same: `global-error.tsx` becomes a call to
-`GlobalErrorShell`, `components/errors/error-shell.tsx` re-exports `ErrorShell`
-and keeps only its own `ErrorAction`, and any two-factor policy defers to
-`@connextar/house/auth`.
+Then, per module the app takes up:
+
+1. **Tailwind first.** Add the `@source` line (or the v3 `content` glob) from
+   [Tailwind setup](#tailwind-setup-required-for-every-component). Without it the
+   components render unstyled and nothing errors.
+2. **Replace the local copy with a binding, not a rewrite of its callers.** The
+   app's `lib/markdown.tsx`, `components/editor/rich-text-editor.tsx` or
+   `lib/changelog.ts` stays where its importers expect it and shrinks to the
+   app's own part: its routes, its type scale, its `@` and `#` lookups, its data.
+   A binding that grows past a screen is the package being re-implemented.
+3. **Move the tests with the code.** A local test of behaviour the package now
+   owns is deleted; a test of the app's binding stays.
+4. **Changelog and releases** follow [`docs/ReleaseProcess.md`](docs/ReleaseProcess.md)
+   §7: the old entries become numbered releases once, `lib/release.test.ts` guards
+   them from then on, and the app's own `docs/operations/ReleaseProcess.md` says
+   only what is its own.
+5. **Gates, then the pages.** `npm run check`, `npm test`, `npm run build`, and
+   grep the built CSS for a class that only the package uses — the one check that
+   proves step 1.
+
+Traps found adopting it the first time:
+
+- A **server component** receives a client module as a reference that throws on
+  any property access. Never dot into an import from a client module in shared
+  code; the package's own `next/link` helper is a type-only cast for this reason.
+- Next writes route types under `.next/dev/types` during `next dev`. After routes
+  are deleted, a stale copy fails `next build`'s type check with "Cannot find
+  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.
+- **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.
 
 **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
@@ -163,7 +421,7 @@ behaves exactly like a registry install:
 
 ```bash
 npm pack --pack-destination /tmp        # in this repo
-npm install /tmp/connextar-house-0.1.0.tgz   # in the app
+npm install /tmp/connextar-house-0.2.0.tgz   # in the app
 ```
 
 ## Adding to it

package/dist/changelog/changelog.d.ts

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+import { type ChangeType, type ChangelogRelease } from "../release/changelog.js";
+import { type ReleaseKind } from "../release/version.js";
+/**
+ * The body of a /changelog page: an index of releases beside the releases
+ * themselves.
+ *
+ * Each release shows its version, whether it is a major, minor or patch
+ * release, and its date, then a headline and a one-sentence summary. Changes
+ * sit under the product-area headings they were grouped by, each with a tag
+ * and a bold headline. The index is a sticky rail on wide screens and a
+ * scrolling strip of versions on a phone.
+ *
+ * Only the body: the page's header, hero, footer and metadata are the app's,
+ * because that is where every product already differs. Server-safe, no hooks.
+ *
+ * Tag colours default to tokens every house app has (`primary`, `accent`,
+ * `muted`, `border`). An app with `success` and `warning` tokens can pass
+ * `tagClassNames` for the fuller palette.
+ */
+export declare const DEFAULT_TAG_CLASS_NAMES: Record<ChangeType, string>;
+export declare const TAG_LABELS: Record<ChangeType, string>;
+export declare const KIND_LABELS: Record<ReleaseKind, string>;
+export interface ChangelogProps {
+    releases: readonly ChangelogRelease[];
+    /** Tag classes per change type; merged over the defaults. */
+    tagClassNames?: Partial<Record<ChangeType, string>>;
+    /** The release headline. Defaults to a plain 2xl semibold heading. */
+    releaseTitleClassName?: string;
+    /** The small uppercase label above the index. */
+    eyebrowClassName?: string;
+    /** The one-sentence summary under a release headline. */
+    summaryClassName?: string;
+    /** The "Latest" pill's colours. */
+    latestClassName?: string;
+    /** A section heading ("Notes", "Fixes"). */
+    sectionHeadingClassName?: string;
+    /** The "3 changes" count beside a section heading. */
+    sectionCountClassName?: string;
+    /**
+     * How a change's text is drawn. Defaults to rendering `**bold**` as strong —
+     * release notes name UI labels that way — and everything else as text.
+     */
+    renderText?: (text: string) => ReactNode;
+    /** Locale for release dates. */
+    locale?: string;
+    /** How far below the top a sticky index sits, and where an anchor lands. */
+    stickyTop?: string;
+    className?: string;
+}
+/** `**label**` → <strong>label</strong>; nothing else is interpreted. */
+export declare function renderReleaseText(text: string): ReactNode;
+export declare function Changelog({ releases, tagClassNames, releaseTitleClassName, eyebrowClassName, summaryClassName, latestClassName, sectionHeadingClassName, sectionCountClassName, renderText, locale, stickyTop, className, }: ChangelogProps): import("react").JSX.Element;
+/** Figures for a page hero: the latest version, how many releases, how many changes. */
+export declare function changelogStats(releases: readonly ChangelogRelease[]): {
+    latest: string | null;
+    releases: number;
+    changes: number;
+};
+//# sourceMappingURL=changelog.d.ts.map

package/dist/changelog/changelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/changelog/changelog.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEtE;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAK9D,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAKjD,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAInD,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,sEAAsE;IACtE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,sDAAsD;IACtD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC;IACzC,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAWzD;AAED,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,aAAa,EACb,qBAAwF,EACxF,gBAA4F,EAC5F,gBAAgF,EAChF,eAAqE,EACrE,uBAAyF,EACzF,qBAAmG,EACnG,UAA8B,EAC9B,MAAgB,EAChB,SAAkB,EAClB,SAAS,GACV,EAAE,cAAc,+BA0GhB;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,CAMA"}

package/dist/changelog/changelog.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../internal/cx.js";
+import { countChanges, formatReleaseDate, releaseAnchor, } from "../release/changelog.js";
+import { releaseKind } from "../release/version.js";
+/**
+ * The body of a /changelog page: an index of releases beside the releases
+ * themselves.
+ *
+ * Each release shows its version, whether it is a major, minor or patch
+ * release, and its date, then a headline and a one-sentence summary. Changes
+ * sit under the product-area headings they were grouped by, each with a tag
+ * and a bold headline. The index is a sticky rail on wide screens and a
+ * scrolling strip of versions on a phone.
+ *
+ * Only the body: the page's header, hero, footer and metadata are the app's,
+ * because that is where every product already differs. Server-safe, no hooks.
+ *
+ * Tag colours default to tokens every house app has (`primary`, `accent`,
+ * `muted`, `border`). An app with `success` and `warning` tokens can pass
+ * `tagClassNames` for the fuller palette.
+ */
+export const DEFAULT_TAG_CLASS_NAMES = {
+    new: "border-primary/40 bg-primary/10 text-primary",
+    improved: "border-border bg-accent text-accent-foreground",
+    changed: "border-foreground/30 bg-background text-foreground",
+    fixed: "border-border bg-muted text-muted-foreground",
+};
+export const TAG_LABELS = {
+    new: "New",
+    improved: "Improved",
+    changed: "Changed",
+    fixed: "Fixed",
+};
+export const KIND_LABELS = {
+    major: "Major release",
+    minor: "Minor release",
+    patch: "Patch release",
+};
+/** `**label**` → <strong>label</strong>; nothing else is interpreted. */
+export function renderReleaseText(text) {
+    const parts = text.split(/(\*\*[^*\n]+\*\*)/g);
+    return parts.map((part, i) => part.startsWith("**") && part.endsWith("**") && part.length > 4 ? (_jsx("strong", { className: "font-semibold text-foreground", children: part.slice(2, -2) }, i)) : (part));
+}
+export function Changelog({ releases, tagClassNames, releaseTitleClassName = "text-2xl font-semibold tracking-tight text-balance sm:text-3xl", eyebrowClassName = "text-xs font-semibold tracking-[0.14em] text-muted-foreground uppercase", summaryClassName = "max-w-prose text-base leading-relaxed text-muted-foreground", latestClassName = "border-primary bg-primary text-primary-foreground", sectionHeadingClassName = "text-xs font-bold tracking-[0.14em] text-foreground uppercase", sectionCountClassName = "text-[11px] font-medium tracking-normal text-muted-foreground normal-case", renderText = renderReleaseText, locale = "en-GB", stickyTop = "7rem", className, }) {
+    const tags = { ...DEFAULT_TAG_CLASS_NAMES, ...tagClassNames };
+    return (_jsxs("div", { className: cx("mx-auto grid max-w-6xl gap-10 px-4 py-12 lg:grid-cols-[14rem_minmax(0,1fr)] lg:gap-16", className), children: [_jsx("nav", { "aria-label": "Releases", className: "min-w-0", children: _jsxs("div", { className: "lg:sticky", style: { top: stickyTop }, children: [_jsx("p", { className: eyebrowClassName, children: "Releases" }), _jsx("ol", { className: "-mx-4 mt-4 flex gap-2 overflow-x-auto px-4 pb-2 lg:mx-0 lg:block lg:max-h-[calc(100vh-10rem)] lg:space-y-0.5 lg:overflow-y-auto lg:border-l lg:border-border lg:px-0 lg:pb-0", children: releases.map((release) => (_jsx("li", { className: "shrink-0", children: _jsxs("a", { href: `#${releaseAnchor(release.version)}`, className: "block rounded-full border border-border px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:border-primary hover:text-foreground lg:-ml-px lg:rounded-none lg:border-0 lg:border-l-2 lg:border-transparent lg:py-1.5 lg:pr-2 lg:pl-4", children: [_jsxs("span", { className: "font-mono text-xs font-semibold text-foreground", children: ["v", release.version] }), _jsx("span", { className: "hidden truncate lg:block", children: release.title })] }) }, release.version))) })] }) }), _jsx("div", { className: "min-w-0 space-y-20", children: releases.map((release, i) => {
+                    const anchor = releaseAnchor(release.version);
+                    const previous = releases[i + 1];
+                    const kind = previous ? releaseKind(previous.version, release.version) : null;
+                    return (_jsxs("article", { id: anchor, "aria-labelledby": `${anchor}-title`, style: { scrollMarginTop: stickyTop }, children: [_jsxs("header", { className: "border-b border-border pb-7", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-2", children: [_jsxs("span", { className: "rounded-full border border-primary/40 bg-primary/10 px-2.5 py-0.5 font-mono text-xs font-semibold text-primary", children: ["v", release.version] }), i === 0 ? (_jsx("span", { className: cx("rounded-full border px-2.5 py-0.5 text-[11px] font-semibold", latestClassName), children: "Latest" })) : null, kind ? _jsx("span", { className: "text-xs text-muted-foreground", children: KIND_LABELS[kind] }) : null, _jsx("span", { className: "text-xs text-muted-foreground", "aria-hidden": "true", children: "\u00B7" }), _jsx("time", { dateTime: release.date, className: "text-xs text-muted-foreground", children: formatReleaseDate(release.date, locale) })] }), _jsx("h2", { id: `${anchor}-title`, className: cx("mt-4", releaseTitleClassName), children: release.title }), _jsx("p", { className: cx("mt-3", summaryClassName), children: release.summary })] }), _jsx("div", { className: "mt-9 space-y-10", children: release.sections.map((section) => (_jsxs("section", { "aria-label": `${section.heading} — v${release.version}`, children: [_jsxs("h3", { className: cx("flex items-baseline gap-2", sectionHeadingClassName), children: [section.heading, _jsxs("span", { className: sectionCountClassName, children: [section.changes.length, " ", section.changes.length === 1 ? "change" : "changes"] })] }), _jsx("ul", { className: "mt-4 divide-y divide-border overflow-hidden rounded-2xl border border-border bg-card", children: section.changes.map((change) => (_jsxs("li", { className: "grid gap-2.5 p-5 sm:grid-cols-[5.5rem_minmax(0,1fr)] sm:gap-5", children: [_jsx("span", { className: cx("inline-flex h-fit w-fit items-center rounded-full border px-2 py-0.5 text-[11px] font-semibold", tags[change.type]), children: TAG_LABELS[change.type] }), _jsxs("div", { children: [_jsx("p", { className: "leading-snug font-semibold text-card-foreground", children: change.title }), _jsx("p", { className: "mt-1.5 text-sm leading-relaxed text-muted-foreground", children: renderText(change.text) })] })] }, change.title))) })] }, section.heading))) })] }, release.version));
+                }) })] }));
+}
+/** Figures for a page hero: the latest version, how many releases, how many changes. */
+export function changelogStats(releases) {
+    return {
+        latest: releases[0]?.version ?? null,
+        releases: releases.length,
+        changes: releases.reduce((n, release) => n + countChanges(release), 0),
+    };
+}
+//# sourceMappingURL=changelog.js.map

package/dist/changelog/changelog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/changelog/changelog.tsx"],"names":[],"mappings":";AAEA,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AACvC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,GAGd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAoB,MAAM,uBAAuB,CAAC;AAEtE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAA+B;IACjE,GAAG,EAAE,8CAA8C;IACnD,QAAQ,EAAE,gDAAgD;IAC1D,OAAO,EAAE,oDAAoD;IAC7D,KAAK,EAAE,8CAA8C;CACtD,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAA+B;IACpD,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAgC;IACtD,KAAK,EAAE,eAAe;IACtB,KAAK,EAAE,eAAe;IACtB,KAAK,EAAE,eAAe;CACvB,CAAC;AA8BF,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAC3B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAChE,iBAAgB,SAAS,EAAC,+BAA+B,YACtD,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IADP,CAAC,CAEL,CACV,CAAC,CAAC,CAAC,CACF,IAAI,CACL,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,EACxB,QAAQ,EACR,aAAa,EACb,qBAAqB,GAAG,gEAAgE,EACxF,gBAAgB,GAAG,yEAAyE,EAC5F,gBAAgB,GAAG,6DAA6D,EAChF,eAAe,GAAG,mDAAmD,EACrE,uBAAuB,GAAG,+DAA+D,EACzF,qBAAqB,GAAG,2EAA2E,EACnG,UAAU,GAAG,iBAAiB,EAC9B,MAAM,GAAG,OAAO,EAChB,SAAS,GAAG,MAAM,EAClB,SAAS,GACM;IACf,MAAM,IAAI,GAAG,EAAE,GAAG,uBAAuB,EAAE,GAAG,aAAa,EAAE,CAAC;IAE9D,OAAO,CACL,eACE,SAAS,EAAE,EAAE,CAAC,uFAAuF,EAAE,SAAS,CAAC,aAEjH,4BAAgB,UAAU,EAAC,SAAS,EAAC,SAAS,YAC5C,eAAK,SAAS,EAAC,WAAW,EAAC,KAAK,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,aAClD,YAAG,SAAS,EAAE,gBAAgB,yBAAc,EAC5C,aAAI,SAAS,EAAC,8KAA8K,YACzL,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CACzB,aAA0B,SAAS,EAAC,UAAU,YAC5C,aACE,IAAI,EAAE,IAAI,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAC1C,SAAS,EAAC,oPAAoP,aAE9P,gBAAM,SAAS,EAAC,iDAAiD,kBAAG,OAAO,CAAC,OAAO,IAAQ,EAC3F,eAAM,SAAS,EAAC,0BAA0B,YAAE,OAAO,CAAC,KAAK,GAAQ,IAC/D,IAPG,OAAO,CAAC,OAAO,CAQnB,CACN,CAAC,GACC,IACD,GACF,EAEN,cAAK,SAAS,EAAC,oBAAoB,YAChC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE;oBAC3B,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;oBAC9C,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;oBACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;oBAE9E,OAAO,CACL,mBAEE,EAAE,EAAE,MAAM,qBACO,GAAG,MAAM,QAAQ,EAClC,KAAK,EAAE,EAAE,eAAe,EAAE,SAAS,EAAE,aAErC,kBAAQ,SAAS,EAAC,6BAA6B,aAC7C,eAAK,SAAS,EAAC,6CAA6C,aAC1D,gBAAM,SAAS,EAAC,gHAAgH,kBAC5H,OAAO,CAAC,OAAO,IACZ,EACN,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CACT,eACE,SAAS,EAAE,EAAE,CAAC,6DAA6D,EAAE,eAAe,CAAC,uBAGxF,CACR,CAAC,CAAC,CAAC,IAAI,EACP,IAAI,CAAC,CAAC,CAAC,eAAM,SAAS,EAAC,+BAA+B,YAAE,WAAW,CAAC,IAAI,CAAC,GAAQ,CAAC,CAAC,CAAC,IAAI,EACzF,eAAM,SAAS,EAAC,+BAA+B,iBAAa,MAAM,uBAE3D,EACP,eAAM,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,SAAS,EAAC,+BAA+B,YACpE,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,GACnC,IACH,EACN,aAAI,EAAE,EAAE,GAAG,MAAM,QAAQ,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,EAAE,qBAAqB,CAAC,YACpE,OAAO,CAAC,KAAK,GACX,EACL,YAAG,SAAS,EAAE,EAAE,CAAC,MAAM,EAAE,gBAAgB,CAAC,YAAG,OAAO,CAAC,OAAO,GAAK,IAC1D,EAET,cAAK,SAAS,EAAC,iBAAiB,YAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CACjC,iCAA2C,GAAG,OAAO,CAAC,OAAO,OAAO,OAAO,CAAC,OAAO,EAAE,aACnF,cAAI,SAAS,EAAE,EAAE,CAAC,2BAA2B,EAAE,uBAAuB,CAAC,aACpE,OAAO,CAAC,OAAO,EAChB,gBAAM,SAAS,EAAE,qBAAqB,aACnC,OAAO,CAAC,OAAO,CAAC,MAAM,OAAG,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,IACxE,IACJ,EACL,aAAI,SAAS,EAAC,sFAAsF,YACjG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAC/B,cAEE,SAAS,EAAC,+DAA+D,aAEzE,eACE,SAAS,EAAE,EAAE,CACX,gGAAgG,EAChG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAClB,YAEA,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,GACnB,EACP,0BACE,YAAG,SAAS,EAAC,iDAAiD,YAAE,MAAM,CAAC,KAAK,GAAK,EACjF,YAAG,SAAS,EAAC,sDAAsD,YAChE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,GACtB,IACA,KAhBD,MAAM,CAAC,KAAK,CAiBd,CACN,CAAC,GACC,KA7BO,OAAO,CAAC,OAAO,CA8BnB,CACX,CAAC,GACE,KAjED,OAAO,CAAC,OAAO,CAkEZ,CACX,CAAC;gBACJ,CAAC,CAAC,GACE,IACF,CACP,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,cAAc,CAAC,QAAqC;IAKlE,OAAO;QACL,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI;QACpC,QAAQ,EAAE,QAAQ,CAAC,MAAM;QACzB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;KACvE,CAAC;AACJ,CAAC"}

package/dist/changelog/index.d.ts

@@ -0,0 +1,2 @@
+export { Changelog, changelogStats, DEFAULT_TAG_CLASS_NAMES, KIND_LABELS, renderReleaseText, TAG_LABELS, type ChangelogProps, } from "./changelog.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/changelog/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,cAAc,EACd,uBAAuB,EACvB,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/changelog/index.js

@@ -0,0 +1,2 @@
+export { Changelog, changelogStats, DEFAULT_TAG_CLASS_NAMES, KIND_LABELS, renderReleaseText, TAG_LABELS, } from "./changelog.js";
+//# sourceMappingURL=index.js.map

package/dist/changelog/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/changelog/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,cAAc,EACd,uBAAuB,EACvB,WAAW,EACX,iBAAiB,EACjB,UAAU,GAEX,MAAM,gBAAgB,CAAC"}

package/dist/editor/block-handle.d.ts

@@ -0,0 +1,15 @@
+import type { Editor } from "@tiptap/react";
+/**
+ * The gutter beside whichever block the pointer is over: a `+` that starts a new
+ * block underneath (with the `/` menu already open, as Notion does) and a grip
+ * that drags the block to reorder it or, clicked, opens the block menu — turn
+ * into, duplicate, move up, move down, delete.
+ *
+ * Everything works on the block's document position rather than the caret, so a
+ * block can be acted on without ever being clicked into. The drag itself is the
+ * extension's: it understands nested lists and shows the drop cursor.
+ */
+export declare function BlockHandle({ editor }: {
+    editor: Editor;
+}): import("react").JSX.Element;
+//# sourceMappingURL=block-handle.d.ts.map

package/dist/editor/block-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-handle.d.ts","sourceRoot":"","sources":["../../src/editor/block-handle.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AA+B5C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,+BAuJzD"}