@kernhq/module-quire 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-quire",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Kern Quire: collaborative documents, spaces and page trees",
   "homepage": "https://kernaio.com",
   "license": "AGPL-3.0-only",
@@ -52,26 +52,38 @@
     "zod": "^4.1.0"
   },
   "peerDependencies": {
-    "svelte": "^5.0.0"
+    "@kernhq/ui": "^0.7.0",
+    "@tanstack/svelte-query": "^6.1.0",
+    "svelte": "^5.46.0"
   },
   "peerDependenciesMeta": {
+    "@kernhq/ui": {
+      "optional": true
+    },
+    "@tanstack/svelte-query": {
+      "optional": true
+    },
     "svelte": {
       "optional": true
     }
   },
   "devDependencies": {
     "@kernhq/tsconfig": "^0.1.0",
+    "@kernhq/ui": "^0.7.0",
+    "@tanstack/svelte-query": "^6.1.0",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.15.0",
     "drizzle-kit": "^0.31.0",
     "pg": "^8.16.0",
+    "svelte": "^5.46.0",
+    "svelte-check": "^4.0.0",
     "typescript": "~5.9.3",
     "vitest": "^4.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && svelte-check --tsconfig ./tsconfig.client.json --threshold error",
     "test": "vitest run",
     "db:generate": "drizzle-kit generate"
   }

package/src/client/api-instance.ts

@@ -0,0 +1,29 @@
+import { getHost } from '@kernhq/ui'
+import { createQuireClient, type QuireApi } from './index.js'
+import { createMockQuireApi } from './mock.js'
+
+/**
+ * This module's API client.
+ *
+ * An empty base URL keeps requests same-origin, so the dev proxy and the reverse proxy both work
+ * without CORS. `PUBLIC_API_MOCK=1` swaps in the in-memory implementation, which satisfies the same
+ * contract types — so no screen has a second code path for demos and end-to-end tests.
+ */
+export type { QuireApi }
+
+let cached: QuireApi | null = null
+
+export function getQuireApi(): QuireApi {
+  if (cached) return cached
+  cached = getHost().isMock
+    ? (createMockQuireApi() as unknown as QuireApi)
+    : createQuireClient({
+        baseUrl: getHost().apiBaseUrl,
+      })
+  return cached
+}
+
+/** Test seam. */
+export function __setQuireApi(api: QuireApi | null) {
+  cached = api
+}

package/src/client/components/CommentsPanel.svelte

@@ -0,0 +1,305 @@
+<script lang="ts">
+import { Avatar, Button, EmptyState, Icon, IconButton, relativeTime, Skeleton, session } from '@kernhq/ui'
+import { RichTextEditor } from '@kernhq/ui/editor'
+import { createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import type { CommentThread } from '../index.js'
+import { canQuire } from '../permissions.js'
+import { quireKeys } from '../query.js'
+
+/**
+ * The margin.
+ *
+ * Threads rather than a flat list, because a remark and its answers are one conversation — and
+ * because resolving is a property of the conversation, not of the last thing said in it.
+ *
+ * A thread whose anchored text has been deleted still appears, showing what it was about. Hiding it
+ * would quietly discard somebody's question the moment the sentence it referred to was rewritten,
+ * which is exactly when the question matters most.
+ */
+interface Props {
+  workspaceId: string
+  pageId: string
+  /** the thread the editor has highlighted, if any */
+  activeId: string | null
+  /** anchors whose text no longer resolves, so the panel can say so */
+  orphaned: Set<string>
+  onFocus?: (id: string | null) => void
+  /** a selection waiting for its first remark */
+  pending: { anchor: { from: string; to: string }; quotedText: string } | null
+  onPendingHandled?: () => void
+}
+const { workspaceId, pageId, activeId, orphaned, onFocus, pending, onPendingHandled }: Props = $props()
+
+const api = getQuireApi()
+const client = useQueryClient()
+
+const query = createQuery(() => ({
+  queryKey: [...quireKeys.page(workspaceId, pageId), 'comments'],
+  enabled: Boolean(workspaceId && pageId),
+  queryFn: () => api.comments.list({ workspaceId, pageId, includeResolved: false }),
+}))
+const threads = $derived(query.data ?? [])
+
+let draft = $state<unknown>(undefined)
+let replyTo = $state<string | null>(null)
+let replyDraft = $state<unknown>(undefined)
+let busy = $state(false)
+let error = $state<string | null>(null)
+
+const empty = (doc: unknown) => {
+  const text = JSON.stringify(doc ?? {})
+  return !text.includes('"text"')
+}
+
+async function submit(parentId: string | null, body: unknown) {
+  if (busy || empty(body)) return
+  busy = true
+  error = null
+  try {
+    await api.comments.create({
+      workspaceId,
+      pageId,
+      body: $state.snapshot(body) as Record<string, unknown>,
+      // An empty pair is how the page-level composer says "about the page, not a piece of it".
+      anchor: parentId || !pending?.anchor.from ? null : pending.anchor,
+      quotedText: parentId ? '' : (pending?.quotedText ?? ''),
+      parentId,
+    })
+    await query.refetch()
+    if (parentId) {
+      replyDraft = undefined
+      replyTo = null
+    } else {
+      draft = undefined
+      onPendingHandled?.()
+    }
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err)
+  } finally {
+    busy = false
+  }
+}
+
+async function resolve(thread: CommentThread) {
+  busy = true
+  try {
+    await api.comments.resolve({ workspaceId, commentId: thread.id, resolved: true })
+    await query.refetch()
+    await client.invalidateQueries({ queryKey: quireKeys.page(workspaceId, pageId) })
+  } finally {
+    busy = false
+  }
+}
+
+async function remove(commentId: string) {
+  busy = true
+  try {
+    await api.comments.remove({ workspaceId, commentId })
+    await query.refetch()
+  } finally {
+    busy = false
+  }
+}
+</script>
+
+<aside class="panel" aria-label={t('comments')}>
+  <h2 class="heading">{t('comments')}</h2>
+
+  {#if pending}
+    <div class="composer new">
+      {#if pending.quotedText}
+        <p class="quoted">“{pending.quotedText}”</p>
+      {/if}
+      <RichTextEditor bind:value={draft} placeholder={t('comment_placeholder')} minRows={2} />
+      <div class="actions">
+        <Button size="sm" variant="secondary" onclick={() => onPendingHandled?.()}>{t('common.cancel')}</Button>
+        <Button size="sm" disabled={busy || empty(draft)} onclick={() => submit(null, draft)}>
+          {t('comment_post')}
+        </Button>
+      </div>
+    </div>
+  {/if}
+
+  {#if error}<p class="error" role="alert">{error}</p>{/if}
+
+  {#if query.isLoading}
+    <Skeleton height="72px" />
+  {:else if threads.length === 0 && !pending}
+    <EmptyState
+      bare
+      compact
+      icon="message-circle"
+      title={t('comments_empty')}
+      description={t('comments_empty_desc')}
+    />
+  {:else}
+    {#each threads as thread (thread.id)}
+      <div
+        class="thread"
+        class:active={thread.id === activeId}
+        role="button"
+        tabindex="0"
+        onclick={() => onFocus?.(thread.id)}
+        onkeydown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+            onFocus?.(thread.id)
+          }
+        }}
+      >
+        {#if thread.root.quotedText}
+          <p class="quoted" class:orphan={orphaned.has(thread.id)}>“{thread.root.quotedText}”</p>
+          {#if orphaned.has(thread.id)}
+            <p class="orphan-note"><Icon name="circle-alert" size={12} /> {t('comment_orphaned')}</p>
+          {/if}
+        {/if}
+
+        {#each [thread.root, ...thread.replies] as comment (comment.id)}
+          <div class="comment">
+            <Avatar id={comment.authorId} size={22} />
+            <div class="bubble">
+              <div class="who">
+                <span class="time">{relativeTime(comment.createdAt)}</span>
+                {#if comment.editedAt}<span class="edited">{t('comment_edited')}</span>{/if}
+                {#if comment.authorId === session.user?.id}
+                  <span class="spacer"></span>
+                  <IconButton
+                    icon="trash-2"
+                    size={22}
+                    variant="ghost"
+                    label={t('common.delete')}
+                    onclick={() => remove(comment.id)}
+                  />
+                {/if}
+              </div>
+              <p class="text">{comment.bodyText}</p>
+            </div>
+          </div>
+        {/each}
+
+        <div class="thread-actions">
+          {#if replyTo === thread.id}
+            <RichTextEditor bind:value={replyDraft} placeholder={t('comment_reply')} minRows={1} />
+            <div class="actions">
+              <Button size="sm" variant="secondary" onclick={() => (replyTo = null)}>{t('common.cancel')}</Button>
+              <Button
+                size="sm"
+                disabled={busy || empty(replyDraft)}
+                onclick={() => submit(thread.root.id, replyDraft)}
+              >
+                {t('comment_post')}
+              </Button>
+            </div>
+          {:else if canQuire('pageComment')}
+            <Button size="sm" variant="ghost" onclick={() => (replyTo = thread.id)}>
+              {t('comment_reply')}
+            </Button>
+            <Button size="sm" variant="ghost" disabled={busy} onclick={() => resolve(thread)}>
+              {t('comment_resolve')}
+            </Button>
+          {/if}
+        </div>
+      </div>
+    {/each}
+  {/if}
+</aside>
+
+<style>
+.panel {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 20px 18px;
+  border-inline-start: 1px solid var(--kern-border);
+  background: var(--kern-surface);
+  overflow-y: auto;
+  min-height: 0;
+}
+.heading {
+  margin: 0;
+  font-size: 12.5px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--kern-ink-400);
+}
+.thread {
+  border: 1px solid var(--kern-border);
+  border-radius: var(--kern-r-card);
+  background: var(--kern-surface-raised);
+  padding: 12px;
+  cursor: pointer;
+}
+.thread.active {
+  border-color: var(--kern-accent);
+}
+.quoted {
+  margin: 0 0 10px;
+  padding-inline-start: 8px;
+  border-inline-start: 2px solid var(--kern-warning);
+  font-size: 12.5px;
+  line-height: 1.45;
+  color: var(--kern-ink-400);
+}
+.quoted.orphan {
+  border-inline-start-color: var(--kern-ink-350);
+  text-decoration: line-through;
+}
+.orphan-note {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  margin: -6px 0 10px;
+  font-size: 12px;
+  color: var(--kern-ink-400);
+}
+.comment {
+  display: flex;
+  gap: 8px;
+  margin-block-end: 10px;
+}
+.bubble {
+  flex: 1;
+  min-width: 0;
+}
+.who {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  color: var(--kern-ink-400);
+}
+.spacer {
+  flex: 1;
+}
+.text {
+  margin: 2px 0 0;
+  font-size: 13.5px;
+  line-height: 1.5;
+  color: var(--kern-ink-700);
+  white-space: pre-wrap;
+}
+.composer.new {
+  border: 1px solid var(--kern-accent);
+  border-radius: var(--kern-r-card);
+  padding: 12px;
+  background: var(--kern-surface-raised);
+}
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 6px;
+  margin-block-start: 8px;
+}
+.thread-actions {
+  display: flex;
+  gap: 4px;
+}
+.error {
+  margin: 0;
+  font-size: 13px;
+  color: var(--kern-danger);
+}
+</style>

package/src/client/components/NewSpaceDialog.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+import { Button, Dialog, Field, Input, Select, Textarea } from '@kernhq/ui'
+import { useQueryClient } from '@tanstack/svelte-query'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import type { Space } from '../index.js'
+import { quireKeys } from '../query.js'
+
+interface Props {
+  open: boolean
+  workspaceId: string
+  onCreated?: (space: Space) => void
+}
+let { open = $bindable(false), workspaceId, onCreated }: Props = $props()
+
+const api = getQuireApi()
+const client = useQueryClient()
+
+let name = $state('')
+let key = $state('')
+let description = $state('')
+let visibility = $state<Space['visibility']>('open')
+let saving = $state(false)
+let error = $state<string | null>(null)
+
+/**
+ * The key is derived from the name until somebody types one, and then left alone. Overwriting a key
+ * a person has edited — because they went back and fixed a typo in the name — is the kind of thing
+ * that only shows up after the space exists and the URL is wrong.
+ */
+let keyTouched = $state(false)
+const slugify = (v: string) =>
+  v
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+
+$effect(() => {
+  if (!keyTouched) key = slugify(name)
+})
+
+const valid = $derived(name.trim().length > 0 && key.length >= 2)
+
+function reset() {
+  name = ''
+  key = ''
+  description = ''
+  visibility = 'open'
+  keyTouched = false
+  error = null
+}
+
+async function submit() {
+  if (!valid || saving) return
+  saving = true
+  error = null
+  try {
+    const space = await api.spaces.create({
+      workspaceId,
+      key,
+      name: name.trim(),
+      description: description.trim(),
+      icon: null,
+      visibility,
+    })
+    await client.invalidateQueries({ queryKey: quireKeys.spaces(workspaceId) })
+    open = false
+    reset()
+    onCreated?.(space)
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err)
+  } finally {
+    saving = false
+  }
+}
+</script>
+
+<Dialog bind:open title={t('new_space')} description={t('new_space_desc')}>
+  <div class="form">
+    <Field label={t('space_name')}>
+      {#snippet children(id: string)}
+        <Input {id} bind:value={name} placeholder={t('space_name_hint')} />
+      {/snippet}
+    </Field>
+
+    <Field label={t('space_key')} hint={t('space_key_hint')}>
+      {#snippet children(id: string)}
+        <Input
+          {id}
+          value={key}
+          oninput={(e: Event) => {
+            keyTouched = true
+            key = slugify((e.currentTarget as HTMLInputElement).value)
+          }}
+        />
+      {/snippet}
+    </Field>
+
+    <Field label={t('space_description')}>
+      {#snippet children(id: string)}
+        <Textarea {id} bind:value={description} rows={2} />
+      {/snippet}
+    </Field>
+
+    <Field label={t('space_visibility')}>
+      {#snippet children(id: string)}
+        <Select
+          {id}
+          value={visibility}
+          options={[
+            { value: 'open', label: t('visibility_open') },
+            { value: 'restricted', label: t('visibility_restricted') },
+            { value: 'private', label: t('visibility_private') },
+          ]}
+          onValueChange={(v: string) => (visibility = v as Space['visibility'])}
+        />
+      {/snippet}
+    </Field>
+
+    {#if error}<p class="error">{error}</p>{/if}
+  </div>
+
+  {#snippet footer()}
+    <Button variant="secondary" onclick={() => (open = false)}>{t('common.cancel')}</Button>
+    <Button disabled={!valid || saving} onclick={submit}>{t('common.create')}</Button>
+  {/snippet}
+</Dialog>
+
+<style>
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+.error {
+  margin: 0;
+  font-size: 13px;
+  color: var(--kern-danger);
+}
+</style>

package/src/client/components/PageEditor.svelte

@@ -0,0 +1,83 @@
+<script lang="ts">
+import {
+  CollaborativeEditor,
+  type CollabPeer,
+  type CollabStatus,
+  type CommentRange,
+  EmptyState,
+  getHost,
+  session,
+} from '@kernhq/ui'
+import { t } from '../i18n.js'
+import { type Page, pageDocumentName } from '../index.js'
+
+/**
+ * The body of a page, synchronised through the collab service.
+ *
+ * The document name is built with `formatCollabDocument` rather than assembled here: the gateway
+ * parses it with the matching function from the same package, and a name it cannot parse is a
+ * rejected connection with no useful error.
+ */
+interface Props {
+  doc: Page
+  onpeers?: (peers: CollabPeer[]) => void
+  onstatus?: (status: CollabStatus) => void
+  commentRanges?: CommentRange[]
+  activeComment?: string | null
+  onCommentClick?: (id: string) => void
+  oncomment?: (anchor: { from: string; to: string }, quotedText: string) => void
+}
+const {
+  doc,
+  onpeers,
+  onstatus,
+  commentRanges = [],
+  activeComment = null,
+  onCommentClick,
+  oncomment,
+}: Props = $props()
+
+const name = $derived(pageDocumentName(doc))
+
+/**
+ * Same-origin by default, so the dev proxy and the reverse proxy both work without configuration.
+ * The shell owns the endpoint: same origin under `/collab` in every ordinary deployment, and an
+ * explicit one for an instance that puts the collab service somewhere else.
+ */
+const url = $derived(
+  getHost().collabUrl ??
+    (typeof location === 'undefined' ? '' : `${location.origin.replace(/^http/, 'ws')}/collab`),
+)
+
+const user = $derived({
+  id: session.user?.id ?? '',
+  name: session.user?.name ?? '',
+  avatarUrl: session.user?.avatarUrl ?? null,
+})
+</script>
+
+{#if getHost().isMock}
+  <!--
+    There is no collab service behind `dev:mock`, and an editor that silently fails to sync is worse
+    than one that says so — this is the environment used for demos, where "it looked like it saved"
+    is exactly the wrong impression to leave.
+  -->
+  <EmptyState icon="wifi-off" title={t('editor_mock')} description={t('editor_mock_desc')} />
+{:else if !user.id}
+  <EmptyState icon="triangle-alert" title={t('editor_no_session')} description={t('editor_no_session_desc')} />
+{:else}
+  {#key name}
+    <CollaborativeEditor
+      {url}
+      {name}
+      {user}
+      placeholder={t('editor_placeholder')}
+      {onpeers}
+      {onstatus}
+      {commentRanges}
+      {activeComment}
+      {onCommentClick}
+      {oncomment}
+    />
+  {/key}
+{/if}

package/src/client/components/PageInline.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+import { Icon, navigation, session } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { quireKeys } from '../query.js'
+
+/**
+ * How a Quire page reads when another module links to one — a mention in an issue, a search hit, a
+ * notification. Inline presenters are how a module renders its own objects somewhere it does not own.
+ */
+interface Props {
+  id: string
+}
+const { id }: Props = $props()
+
+const api = getQuireApi()
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspaceId = $derived(session.workspaces.find((w) => w.slug === workspaceSlug)?.id ?? '')
+
+const query = createQuery(() => ({
+  queryKey: quireKeys.page(workspaceId, id),
+  enabled: Boolean(workspaceId && id),
+  queryFn: () => api.pages.get({ workspaceId, pageId: id }),
+}))
+const title = $derived(query.data?.title?.trim() || t('untitled'))
+</script>
+
+<span class="inline">
+  <Icon name="file-text" size={14} />
+  <span class="t">{query.isLoading ? '…' : title}</span>
+</span>
+
+<style>
+.inline {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  color: var(--kern-ink-700);
+}
+.t {
+  font-weight: 500;
+}
+</style>