@kernhq/module-quire 0.6.0 → 0.7.0

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>

package/src/client/components/PageTreeRow.svelte

@@ -0,0 +1,147 @@
+<script lang="ts">
+import { Icon, IconButton, SidebarItem } from '@kernhq/ui'
+import { t } from '../i18n.js'
+import type { PageTreeNode } from '../index.js'
+import PageTreeRow from './PageTreeRow.svelte'
+
+/**
+ * One row of the page tree, and its children.
+ *
+ * Recursive rather than flattened: the disclosure state belongs to the row that owns it, and a
+ * flattened list has to carry a depth on every node just to indent it. `SidebarItem` draws the row
+ * so indentation, the active state and RTL come from the design system rather than from here —
+ * `indent` caps at 2 there, so deeper levels stop stepping in rather than marching off the edge of a
+ * 268px column.
+ */
+interface Props {
+  node: PageTreeNode
+  depth: number
+  activeId: string | null
+  expanded: Set<string>
+  onToggle: (id: string) => void
+  onOpen: (id: string) => void
+  onCreateChild: (id: string) => void
+  canCreate: boolean
+}
+
+const { node, depth, activeId, expanded, onToggle, onOpen, onCreateChild, canCreate }: Props = $props()
+
+const isOpen = $derived(expanded.has(node.id))
+const title = $derived(node.title.trim() || t('untitled'))
+const indent = $derived(Math.min(depth, 2) as 0 | 1 | 2)
+</script>
+
+<div class="row">
+  <SidebarItem
+    label={title}
+    icon={node.kind === 'live' ? 'square-pen' : 'file-text'}
+    active={activeId === node.id}
+    {indent}
+    onclick={() => onOpen(node.id)}
+  >
+    {#snippet trailing()}
+      {#if node.archivedAt}
+        <span class="flag" title={t('archived')}><Icon name="archive" size={12} /></span>
+      {/if}
+      {#if canCreate}
+        <span class="add">
+          <IconButton
+            icon="plus"
+            size={22}
+            variant="ghost"
+            label={t('new_child_page')}
+            onclick={(e: MouseEvent) => {
+              e.stopPropagation()
+              onCreateChild(node.id)
+            }}
+          />
+        </span>
+      {/if}
+    {/snippet}
+  </SidebarItem>
+
+  {#if node.hasChildren}
+    <button
+      class="twisty"
+      type="button"
+      style:inset-inline-start="{indent * 22 - 4}px"
+      aria-label={isOpen ? t('collapse') : t('expand')}
+      aria-expanded={isOpen}
+      onclick={() => onToggle(node.id)}
+    >
+      <span class:open={isOpen}><Icon name="chevron-right" size={11} strokeWidth={2} /></span>
+    </button>
+  {/if}
+</div>
+
+{#if isOpen}
+  {#each node.children as child (child.id)}
+    <PageTreeRow
+      node={child}
+      depth={depth + 1}
+      {activeId}
+      {expanded}
+      {onToggle}
+      {onOpen}
+      {onCreateChild}
+      {canCreate}
+    />
+  {/each}
+{/if}
+
+<style>
+.row {
+  position: relative;
+}
+/*
+ * The twisty sits over the item's icon well rather than inside the row, so expanding a page is not
+ * the same click target as opening it — a tree where one is inside the other makes it impossible to
+ * expand without navigating.
+ */
+.twisty {
+  position: absolute;
+  inset-block-start: 50%;
+  transform: translateY(-50%);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border: 0;
+  background: none;
+  padding: 0;
+  color: var(--kern-ink-350);
+  cursor: pointer;
+  border-radius: var(--kern-r-xs);
+}
+.twisty:hover {
+  color: var(--kern-ink-900);
+}
+.twisty span {
+  display: inline-flex;
+  transition: transform var(--kern-dur-fast) var(--kern-ease-out);
+}
+.twisty span.open {
+  transform: rotate(90deg);
+}
+/* The chevron points along the reading direction, so it mirrors with the document. */
+:global([dir='rtl']) .twisty span {
+  transform: scaleX(-1);
+}
+:global([dir='rtl']) .twisty span.open {
+  transform: rotate(-90deg);
+}
+.flag {
+  display: inline-flex;
+  color: var(--kern-ink-400);
+  flex: none;
+}
+.add {
+  opacity: 0;
+  flex: none;
+}
+.row:hover .add,
+.row:focus-within .add {
+  opacity: 1;
+}
+</style>

package/src/client/components/SidebarSpaces.svelte

@@ -0,0 +1,248 @@
+<script lang="ts">
+import {
+  Button,
+  EmptyState,
+  navigation,
+  SearchBox,
+  SectionLabel,
+  Select,
+  Skeleton,
+  session,
+} from '@kernhq/ui'
+import { createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { buildPageTree, type PageTreeNode } from '../index.js'
+import { canQuire } from '../permissions.js'
+import { quireKeys } from '../query.js'
+import PageTreeRow from './PageTreeRow.svelte'
+
+/**
+ * Quire's spaces and pages, in the application sidebar (DESIGN.md §2.3).
+ *
+ * The sidebar belongs to whichever module you are in — that is why a wiki gets a space switcher, a
+ * "Search this space" box and its page tree here rather than a third column. The tree is the table
+ * of contents, so it shows every level at once and comes from one request per space.
+ */
+const api = getQuireApi()
+const client = useQueryClient()
+
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspace = $derived(session.workspaces.find((w) => w.slug === workspaceSlug))
+const workspaceId = $derived(workspace?.id ?? '')
+
+const spaceKeyInUrl = $derived(navigation.params.space ?? null)
+const activePageId = $derived(navigation.params.page ?? null)
+
+const spacesQuery = createQuery(() => ({
+  queryKey: quireKeys.spaces(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.spaces.list({ workspaceId, includeArchived: false }),
+}))
+
+const spaceList = $derived(spacesQuery.data ?? [])
+const activeSpace = $derived(spaceList.find((space) => space.key === spaceKeyInUrl) ?? spaceList[0] ?? null)
+
+const treeQuery = createQuery(() => ({
+  queryKey: quireKeys.tree(workspaceId, activeSpace?.id ?? ''),
+  enabled: Boolean(workspaceId && activeSpace),
+  queryFn: () => api.pages.tree({ workspaceId, spaceId: activeSpace?.id ?? '', includeArchived: false }),
+}))
+
+let search = $state('')
+let expanded = $state(new Set<string>())
+
+const nodes = $derived(treeQuery.data ?? [])
+const roots = $derived(buildPageTree(nodes))
+
+/**
+ * Searching replaces the tree in the same scroll area rather than appearing under it, so the results
+ * are where the list was and never below the fold. It filters what is already loaded — the whole
+ * space is in memory — so it costs no request and answers as you type.
+ */
+const query = $derived(search.trim().toLowerCase())
+const matches = $derived(
+  query ? nodes.filter((n) => (n.title || t('untitled')).toLowerCase().includes(query)) : [],
+)
+
+/** A page opened from a link may be nested; its ancestors have to be open for it to be visible. */
+$effect(() => {
+  if (!activePageId || nodes.length === 0) return
+  const byId = new Map(nodes.map((n) => [n.id, n]))
+  const next = new Set(expanded)
+  let cursor = byId.get(activePageId)?.parentId ?? null
+  let guard = 0
+  while (cursor && guard++ < 100) {
+    next.add(cursor)
+    cursor = byId.get(cursor)?.parentId ?? null
+  }
+  if (next.size !== expanded.size) expanded = next
+})
+
+function toggle(id: string) {
+  const next = new Set(expanded)
+  if (!next.delete(id)) next.add(id)
+  expanded = next
+}
+
+function openPage(id: string) {
+  if (!activeSpace) return
+  void navigation.go(
+    `/${workspaceSlug}/quire/${encodeURIComponent(activeSpace.key)}/${encodeURIComponent(id)}`,
+  )
+}
+
+function switchSpace(key: string) {
+  void navigation.go(`/${workspaceSlug}/quire/${encodeURIComponent(key)}`)
+}
+
+let creating = $state(false)
+
+async function createPage(parentId: string | null) {
+  if (!activeSpace || creating) return
+  creating = true
+  try {
+    const created = await api.pages.create({
+      workspaceId,
+      spaceId: activeSpace.id,
+      parentId,
+      title: '',
+      kind: 'page',
+      icon: null,
+      afterId: null,
+    })
+    await client.invalidateQueries({ queryKey: quireKeys.tree(workspaceId, activeSpace.id) })
+    if (parentId) expanded = new Set(expanded).add(parentId)
+    openPage(created.id)
+  } finally {
+    creating = false
+  }
+}
+</script>
+
+<div class="wrap">
+  {#if spaceList.length > 1}
+    <div class="switcher">
+      <Select
+        value={activeSpace?.key ?? ''}
+        options={spaceList.map((space) => ({ value: space.key, label: space.name }))}
+        onValueChange={(v: string) => switchSpace(v)}
+      />
+    </div>
+  {/if}
+
+  <div class="strip">
+    <SearchBox bind:value={search} placeholder={t('search_space')} />
+  </div>
+
+  <div class="scroll">
+    {#if spacesQuery.isLoading || treeQuery.isLoading}
+      <div class="loading">
+        {#each [1, 2, 3, 4, 5] as n (n)}
+          <Skeleton height="34px" />
+        {/each}
+      </div>
+    {:else if spacesQuery.isError || treeQuery.isError}
+      <EmptyState
+        icon="triangle-alert"
+        title={t('tree_error')}
+        description={t('tree_error_desc')}
+      >
+        {#snippet actions()}
+          <Button
+            variant="secondary"
+            size="sm"
+            onclick={() => {
+              void spacesQuery.refetch()
+              void treeQuery.refetch()
+            }}
+          >
+            {t('common.retry')}
+          </Button>
+        {/snippet}
+      </EmptyState>
+    {:else if spaceList.length === 0}
+      <EmptyState icon="scroll-text" title={t('no_spaces')} description={t('no_spaces_desc')} />
+    {:else if query}
+      <SectionLabel label={t('search_results')} />
+      {#if matches.length === 0}
+        <p class="none">{t('search_none')}</p>
+      {:else}
+        {#each matches as node (node.id)}
+          <PageTreeRow
+            node={{ ...node, children: [] } as PageTreeNode}
+            depth={0}
+            activeId={activePageId}
+            expanded={new Set()}
+            onToggle={() => {}}
+            onOpen={openPage}
+            onCreateChild={createPage}
+            canCreate={false}
+          />
+        {/each}
+      {/if}
+    {:else}
+      <SectionLabel label={activeSpace?.name ?? t('nav')} />
+      {#if roots.length === 0}
+        <p class="none">{t('space_empty')}</p>
+      {:else}
+        {#each roots as node (node.id)}
+          <PageTreeRow
+            {node}
+            depth={0}
+            activeId={activePageId}
+            {expanded}
+            onToggle={toggle}
+            onOpen={openPage}
+            onCreateChild={createPage}
+            canCreate={canQuire('pageCreate')}
+          />
+        {/each}
+      {/if}
+
+      {#if canQuire('pageCreate') && activeSpace}
+        <div class="new">
+          <Button variant="ghost" size="sm" icon="plus" disabled={creating} onclick={() => createPage(null)}>
+            {t('new_page')}
+          </Button>
+        </div>
+      {/if}
+    {/if}
+  </div>
+</div>
+
+<style>
+.wrap {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  flex: 1;
+}
+.switcher {
+  padding: 10px 12px 0;
+}
+.strip {
+  padding: 12px 12px 4px;
+}
+.scroll {
+  flex: 1;
+  overflow-y: auto;
+  padding: 0 12px 14px;
+  min-height: 0;
+}
+.loading {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding-block-start: 8px;
+}
+.none {
+  padding: 10px;
+  font-size: 13px;
+  color: var(--kern-ink-400);
+  margin: 0;
+}
+.new {
+  padding-block-start: 6px;
+}
+</style>

package/src/client/components/VersionHistory.svelte

@@ -0,0 +1,159 @@
+<script lang="ts">
+import { Avatar, Badge, Button, EmptyState, ListRow, relativeTime, Sheet, Skeleton } from '@kernhq/ui'
+import { createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import type { PageVersion } from '../index.js'
+import { canQuire } from '../permissions.js'
+import { quireKeys } from '../query.js'
+
+/**
+ * What a page used to say, and how to put it back.
+ *
+ * Restoring is offered without a confirmation on purpose: it captures the state it replaces first,
+ * so it is undoable by restoring the version it just made. A confirmation dialog on a reversible
+ * action trains people to click through the ones that are not.
+ */
+interface Props {
+  open: boolean
+  workspaceId: string
+  pageId: string
+  publishedVersionId: string | null
+}
+let { open = $bindable(false), workspaceId, pageId, publishedVersionId }: Props = $props()
+
+const api = getQuireApi()
+const client = useQueryClient()
+
+const query = createQuery(() => ({
+  queryKey: [...quireKeys.page(workspaceId, pageId), 'versions'],
+  enabled: open && Boolean(workspaceId && pageId),
+  queryFn: () => api.versions.list({ workspaceId, pageId, limit: 50 }),
+}))
+
+const versions = $derived(query.data?.items ?? [])
+
+let restoring = $state<string | null>(null)
+let error = $state<string | null>(null)
+
+async function restore(version: PageVersion) {
+  if (restoring) return
+  restoring = version.id
+  error = null
+  try {
+    await api.versions.restore({ workspaceId, versionId: version.id })
+    await client.invalidateQueries({ queryKey: quireKeys.page(workspaceId, pageId) })
+    await query.refetch()
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err)
+  } finally {
+    restoring = null
+  }
+}
+
+const kindLabel = (v: PageVersion) =>
+  v.kind === 'publish'
+    ? t('version_published')
+    : v.kind === 'restore'
+      ? t('version_restored')
+      : v.kind === 'import'
+        ? t('version_imported')
+        : t('version_auto')
+</script>
+
+<Sheet bind:open title={t('history')} width={420}>
+  {#if query.isLoading}
+    <div class="rows">
+      {#each [1, 2, 3, 4] as n (n)}<Skeleton height="56px" />{/each}
+    </div>
+  {:else if query.isError}
+    <EmptyState icon="triangle-alert" title={t('history_error')} description={t('common.retry')}>
+      {#snippet actions()}
+        <Button variant="secondary" onclick={() => void query.refetch()}>{t('common.retry')}</Button>
+      {/snippet}
+    </EmptyState>
+  {:else if versions.length === 0}
+    <EmptyState icon="scroll-text" title={t('history_empty')} description={t('history_empty_desc')} />
+  {:else}
+    {#if error}<p class="error" role="alert">{error}</p>{/if}
+    <div class="rows">
+      {#each versions as version (version.id)}
+        <ListRow>
+          <div class="row">
+            <Avatar id={version.authorId} size={24} />
+            <div class="meta">
+              <div class="line">
+                <span class="when">{relativeTime(version.createdAt)}</span>
+                {#if version.id === publishedVersionId}
+                  <Badge tone="active">{t('version_live')}</Badge>
+                {:else}
+                  <span class="kind">{version.label || kindLabel(version)}</span>
+                {/if}
+              </div>
+              {#if version.preview}
+                <p class="preview">{version.preview}</p>
+              {/if}
+            </div>
+            {#if canQuire('pageEdit') && version.id !== publishedVersionId}
+              <Button
+                size="sm"
+                variant="secondary"
+                disabled={restoring !== null}
+                onclick={() => restore(version)}
+              >
+                {restoring === version.id ? t('restoring') : t('restore')}
+              </Button>
+            {/if}
+          </div>
+        </ListRow>
+      {/each}
+    </div>
+  {/if}
+</Sheet>
+
+<style>
+.rows {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.row {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  width: 100%;
+}
+.meta {
+  flex: 1;
+  min-width: 0;
+}
+.line {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.when {
+  font-size: 13.5px;
+  font-weight: 500;
+  color: var(--kern-ink-900);
+}
+.kind {
+  font-size: 12.5px;
+  color: var(--kern-ink-400);
+}
+.preview {
+  margin: 3px 0 0;
+  font-size: 12.5px;
+  line-height: 1.45;
+  color: var(--kern-ink-400);
+  overflow: hidden;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+.error {
+  margin: 0 0 10px;
+  font-size: 13px;
+  color: var(--kern-danger);
+}
+</style>