@connextar/house 0.1.1 → 0.3.0

package/dist/house.css

@@ -0,0 +1,333 @@
+/*
+ * @connextar/house — the styles its components need that utility classes
+ * cannot say: rich text, the editor's own chrome, and the trail's tinted pills.
+ *
+ * Import it once in the app's global stylesheet, after Tailwind:
+ *
+ *   @import "tailwindcss";
+ *   @import "@connextar/house/house.css";
+ *   @source "../node_modules/@connextar/house/dist";
+ *
+ * The @source line is not optional. Tailwind does not scan node_modules, so
+ * without it every utility class that appears only inside this package — and
+ * the components use many — is silently missing from the build.
+ *
+ * Colours come from the app's own theme tokens (--primary, --border, …) through
+ * a --house-* variable at each use, so a theme that stores tokens as HSL
+ * triplets ("222 47% 11%") can map them once without forking this file:
+ *
+ *   :root { --house-primary: hsl(var(--primary)); --house-border: hsl(var(--border)); … }
+ */
+
+@layer components {
+  /* ── Rich text — the editor while writing, and RichTextContent while reading ── */
+
+  .house-prose {
+    color: var(--house-foreground, var(--foreground));
+    line-height: 1.65;
+    font-size: 0.925rem;
+  }
+
+  .house-prose h1,
+  .house-prose h2,
+  .house-prose h3 {
+    font-weight: 650;
+    color: var(--house-foreground, var(--foreground));
+    line-height: 1.25;
+    margin: 1.4em 0 0.5em;
+  }
+
+  .house-prose h1 {
+    font-size: 1.5em;
+  }
+  .house-prose h2 {
+    font-size: 1.25em;
+  }
+  .house-prose h3 {
+    font-size: 1.1em;
+  }
+
+  .house-prose h1:first-child,
+  .house-prose h2:first-child,
+  .house-prose h3:first-child,
+  .house-prose p:first-child {
+    margin-top: 0;
+  }
+
+  .house-prose p {
+    margin: 0.45em 0;
+  }
+
+  .house-prose ul,
+  .house-prose ol {
+    margin: 0.45em 0;
+    padding-left: 1.4em;
+  }
+
+  .house-prose ul {
+    list-style: disc;
+  }
+  .house-prose ol {
+    list-style: decimal;
+  }
+  .house-prose li {
+    margin: 0.2em 0;
+  }
+  .house-prose li > ul,
+  .house-prose li > ol {
+    margin: 0.15em 0;
+  }
+
+  /* Task lists — both the editor's data-type DOM and the renderer's own. */
+  .house-prose ul[data-type="taskList"],
+  .house-prose ul.house-task-list {
+    list-style: none;
+    padding-left: 0.2em;
+  }
+
+  .house-prose ul[data-type="taskList"] li,
+  .house-prose ul.house-task-list li {
+    display: flex;
+    align-items: baseline;
+    gap: 0.55em;
+  }
+
+  .house-prose ul[data-type="taskList"] li > label {
+    flex: 0 0 auto;
+    user-select: none;
+  }
+
+  .house-prose ul[data-type="taskList"] li > div {
+    flex: 1 1 auto;
+  }
+
+  .house-prose input[type="checkbox"] {
+    accent-color: var(--house-primary, var(--primary));
+    width: 0.95em;
+    height: 0.95em;
+    position: relative;
+    top: 0.08em;
+  }
+
+  .house-prose li[data-checked="true"] > div,
+  .house-prose li.house-task-done > span {
+    color: var(--house-muted-foreground, var(--muted-foreground));
+    text-decoration: line-through;
+  }
+
+  .house-prose blockquote {
+    margin: 0.7em 0;
+    border-left: 3px solid color-mix(in oklab, var(--house-primary, var(--primary)) 60%, transparent);
+    padding: 0.1em 0 0.1em 0.9em;
+    color: var(--house-muted-foreground, var(--muted-foreground));
+    font-style: italic;
+  }
+
+  .house-prose code {
+    background: var(--house-muted, var(--muted));
+    border-radius: 0.3em;
+    padding: 0.12em 0.35em;
+    font-size: 0.86em;
+    font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  }
+
+  .house-prose pre {
+    background: var(--house-muted, var(--muted));
+    border: 1px solid var(--house-border, var(--border));
+    border-radius: 0.5rem;
+    padding: 0.7em 0.9em;
+    margin: 0.7em 0;
+    overflow-x: auto;
+  }
+
+  .house-prose pre code {
+    background: transparent;
+    padding: 0;
+    font-size: 0.85em;
+  }
+
+  .house-prose hr {
+    border: 0;
+    border-top: 1px solid var(--house-border, var(--border));
+    margin: 1.2em 0;
+  }
+
+  .house-prose a {
+    color: var(--house-primary, var(--primary));
+    font-weight: 500;
+    text-decoration: underline;
+    text-decoration-color: color-mix(in oklab, var(--house-primary, var(--primary)) 40%, transparent);
+    text-underline-offset: 2px;
+  }
+
+  /* An inline #hashtag, a quiet chip in read views. */
+  .house-prose .house-hashtag {
+    color: var(--house-primary, var(--primary));
+    background: color-mix(in oklab, var(--house-primary, var(--primary)) 10%, transparent);
+    border-radius: 0.35em;
+    padding: 0.05em 0.3em;
+    font-weight: 500;
+    font-size: 0.92em;
+  }
+
+  /* ── The editor ─────────────────────────────────────────────────────────── */
+
+  /* The content area (Tiptap adds .tiptap to the contenteditable). */
+  .house-rich-text .tiptap {
+    outline: none;
+    min-height: var(--rich-text-min-height, 7rem);
+    padding: 0.65rem 0.85rem;
+  }
+
+  /* A page editor: a gutter on the left for each block's `+` and grip, and no
+     box — the page is the surface. */
+  .house-rich-text--document {
+    --rich-text-min-height: 20rem;
+  }
+
+  .house-rich-text--document .tiptap {
+    padding: 0.5rem 1rem 6rem 2.75rem;
+  }
+
+  /* The empty document's prompt, and "Type / for blocks" on an empty block. */
+  .house-rich-text .tiptap .is-empty::before {
+    content: attr(data-placeholder);
+    float: left;
+    height: 0;
+    pointer-events: none;
+    color: var(--house-muted-foreground, var(--muted-foreground));
+  }
+
+  /* The block gutter: `+` and grip beside the hovered block. The extension
+     positions it; this only styles it and fades it in. */
+  .house-block-handle {
+    display: flex;
+    align-items: center;
+    gap: 1px;
+    margin-right: 0.25rem;
+    opacity: 0;
+    transition: opacity 120ms ease;
+  }
+
+  .house-block-handle[data-show="true"],
+  .house-block-handle:hover,
+  .house-block-handle:focus-within,
+  .house-rich-text--document:hover .house-block-handle {
+    opacity: 1;
+  }
+
+  /* A block picked up by its grip, or selected whole. */
+  .house-rich-text .tiptap .ProseMirror-selectednode,
+  .house-rich-text .tiptap [draggable="true"]:active {
+    background: color-mix(in oklab, var(--house-primary, var(--primary)) 8%, transparent);
+    border-radius: 0.375rem;
+  }
+
+  .house-rich-text .tiptap.dragging,
+  .house-rich-text .tiptap.dragging * {
+    cursor: grabbing;
+  }
+
+  /* The in-flight text of a lookup, before it resolves. */
+  .house-rich-text .house-suggestion {
+    color: var(--house-primary, var(--primary));
+    background: color-mix(in oklab, var(--house-primary, var(--primary)) 8%, transparent);
+    border-radius: 0.25em;
+  }
+
+  /* ── The trail ──────────────────────────────────────────────────────────── */
+
+  /* Each step deeper a shade further from the card, so the rail reads as depth. */
+  .house-trail-pill {
+    background: color-mix(
+      in oklab,
+      var(--house-card, var(--card)) calc(100% - var(--house-trail-step, 0) * 6%),
+      var(--house-accent, var(--accent))
+    );
+  }
+
+  .house-trail-pill[data-current] {
+    box-shadow: inset 3px 0 0 var(--house-primary, var(--primary));
+  }
+}
+
+/* The trail bar shows below the lg breakpoint and adds its height less the page
+   padding it overlaps. A screen that fills the viewport subtracts --trail-bar so
+   the page doesn't scroll by that much. */
+@media (width < 64rem) {
+  :root:has([data-trail-bar]) {
+    --trail-bar: 37px;
+  }
+}
+
+/* ── 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/internal/cx.d.ts

@@ -0,0 +1,3 @@
+/** Join class names, dropping the falsy ones. The package's own `cn`, so it imports no app's. */
+export declare function cx(...parts: Array<string | false | null | undefined>): string;
+//# sourceMappingURL=cx.d.ts.map

package/dist/internal/cx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cx.d.ts","sourceRoot":"","sources":["../../src/internal/cx.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,wBAAgB,EAAE,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAE7E"}

package/dist/internal/cx.js

@@ -0,0 +1,5 @@
+/** Join class names, dropping the falsy ones. The package's own `cn`, so it imports no app's. */
+export function cx(...parts) {
+    return parts.filter(Boolean).join(" ");
+}
+//# sourceMappingURL=cx.js.map

package/dist/internal/cx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cx.js","sourceRoot":"","sources":["../../src/internal/cx.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,MAAM,UAAU,EAAE,CAAC,GAAG,KAA+C;IACnE,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC"}

package/dist/internal/next-link.d.ts

@@ -0,0 +1,23 @@
+import NextLink from "next/link.js";
+/**
+ * `next/link`, typed as the component it is.
+ *
+ * next/link is CommonJS, and Next ends that file with
+ * `module.exports = exports.default`, so a default import is the component under
+ * a bundler and under Node's own ESM loader (Vitest) alike. Only TypeScript
+ * disagrees: under `nodenext` it types a CommonJS default import as the whole
+ * module. The cast fixes the type and nothing else.
+ *
+ * It must stay a cast. In a server component the import is a client reference,
+ * and reading any property of one — `.default` included — throws "You cannot
+ * dot into a client module from a server component" and fails the page's
+ * prerender. `next-link.test.ts` holds that line.
+ *
+ * The specifier carries `.js` because `next` publishes no exports map. Next
+ * aliases the fully specified path to the App Router's Link exactly as it does
+ * the bare one (see its build/create-compiler-aliases.js).
+ */
+type LinkComponent = typeof NextLink.default;
+export declare const Link: LinkComponent;
+export {};
+//# sourceMappingURL=next-link.d.ts.map

package/dist/internal/next-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-link.d.ts","sourceRoot":"","sources":["../../src/internal/next-link.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,cAAc,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,KAAK,aAAa,GAAG,OAAO,QAAQ,CAAC,OAAO,CAAC;AAE7C,eAAO,MAAM,IAAI,EAA0B,aAAa,CAAC"}

package/dist/internal/next-link.js

@@ -0,0 +1,3 @@
+import NextLink from "next/link.js";
+export const Link = NextLink;
+//# sourceMappingURL=next-link.js.map

package/dist/internal/next-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-link.js","sourceRoot":"","sources":["../../src/internal/next-link.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,cAAc,CAAC;AAsBpC,MAAM,CAAC,MAAM,IAAI,GAAG,QAAoC,CAAC"}

package/dist/markdown/guide.d.ts

@@ -0,0 +1,98 @@
+import type { ReactNode } from "react";
+import { type MarkdownTableClassNames } from "./table-view.js";
+/**
+ * The help-centre guide renderer: Markdown files under `docs/guides/` drawn as a
+ * public page, with no Markdown library.
+ *
+ * Five apps each carried a copy of this, and the copies had drifted in the ways
+ * copies do. Two drew tables and three printed them as a paragraph of pipes; one
+ * kept a wrapped list line in its item and four broke it into a stray paragraph;
+ * one refused `javascript:` links and four passed them through; four numbered a
+ * repeated heading `-2` and one `-1`; and three let an `####` heading shift the
+ * numbering of the `##` headings after it, so a "Jump to" link could land on the
+ * wrong section. This is the union of the fixes.
+ *
+ * The syntax is the constrained subset guides use: `##`–`####` headings,
+ * paragraphs, blockquotes, ordered and unordered lists, tables, fenced code,
+ * horizontal rules, and inline bold, italic, code and links. Raw HTML is never
+ * interpreted, so a guide cannot put markup on a public page.
+ *
+ * Server-safe: no hooks, no client boundary.
+ */
+export interface ParsedGuide {
+    /** The H1, with any trailing " — User Guide" removed. */
+    title: string;
+    /** The blockquote straight under the title — the page's lede — if there is one. */
+    lede?: string;
+    /** Everything after the title and lede. */
+    body: string;
+}
+export interface GuideHeading {
+    id: string;
+    text: string;
+    level: 2 | 3;
+}
+export interface HowToStep {
+    name: string;
+    text: string;
+}
+/** Split a raw guide into its title, lede and body. */
+export declare function parseGuideFrontmatter(markdown: string): ParsedGuide;
+/** Inline Markdown reduced to plain text, for structured data and search. */
+export declare function stripInline(text: string): string;
+/** A heading's text as a URL fragment, before de-duplication. */
+export declare function headingSlug(text: string): string;
+/**
+ * Hands out unique fragments in document order: the second "Tips" is `tips-2`.
+ * The renderer and `extractHeadings` each take one, and both feed it exactly the
+ * `##` and `###` headings outside code fences — which is what keeps a contents
+ * link and the heading it points at in step.
+ */
+export declare function createHeadingIds(): (text: string) => string;
+/** The `##` and `###` headings, in order, with the ids the renderer gives them. */
+export declare function extractHeadings(body: string): GuideHeading[];
+/**
+ * The `###` steps of a guide's "## Step by step" section as plain text, for
+ * HowTo structured data. Each step's text is its prose and list lines, capped
+ * so the schema stays lean. Empty when the guide has no such section.
+ */
+export declare function extractHowToSteps(body: string): HowToStep[];
+export interface GuideLinkOptions {
+    /** The public route guides live under. */
+    guidesPath?: string;
+    /** The file name (without `.md`) of the guide index, which links to `guidesPath` itself. */
+    indexSlug?: string;
+}
+/**
+ * Where a link in a guide goes. `other-guide.md#part` becomes
+ * `/guides/other-guide#part`; same-site paths, fragments, `mailto:` and web
+ * addresses pass through; anything else — `javascript:`, `data:`, a
+ * protocol-relative `//host` — becomes `#`.
+ */
+export declare function resolveGuideHref(href: string, { guidesPath, indexSlug }?: GuideLinkOptions): string;
+/** Every element a guide draws. Each value replaces the default for that element. */
+export interface GuideClassNames {
+    h2: string;
+    h3: string;
+    h4: string;
+    paragraph: string;
+    blockquote: string;
+    orderedList: string;
+    unorderedList: string;
+    listItem: string;
+    link: string;
+    strong: string;
+    code: string;
+    pre: string;
+    hr: string;
+    table: Partial<MarkdownTableClassNames>;
+}
+/** The house look, on the shared theme tokens. */
+export declare const GUIDE_CLASS_NAMES: GuideClassNames;
+export interface GuideMarkdownProps extends GuideLinkOptions {
+    content: string;
+    classNames?: Partial<GuideClassNames>;
+}
+/** Render a guide body. */
+export declare function GuideMarkdown({ content, guidesPath, indexSlug, classNames }: GuideMarkdownProps): ReactNode;
+//# sourceMappingURL=guide.d.ts.map

package/dist/markdown/guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/markdown/guide.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,OAAO,EAAqB,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AASD,uDAAuD;AACvD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CA0BnE;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAShD;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAQ3D;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CAkB5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAmC3D;AAED,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,UAAsB,EAAE,SAAS,EAAE,GAAE,gBAAqB,GAAG,MAAM,CAUnH;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACzC;AAED,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAE,eAe/B,CAAC;AAEF,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACvC;AAED,2BAA2B;AAC3B,wBAAgB,aAAa,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAoL3G"}