@kernhq/module-quire 0.6.0 → 0.7.0

package/src/client/pages/PageView.svelte

@@ -0,0 +1,406 @@
+<script lang="ts">
+import {
+  Avatar,
+  Button,
+  type CollabPeer,
+  DropdownMenu,
+  EmptyState,
+  Icon,
+  IconButton,
+  navigation,
+  Page,
+  relativeTime,
+  Skeleton,
+  session,
+} from '@kernhq/ui'
+import { createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getQuireApi } from '../api-instance.js'
+import CommentsPanel from '../components/CommentsPanel.svelte'
+import PageEditor from '../components/PageEditor.svelte'
+import VersionHistory from '../components/VersionHistory.svelte'
+import { t } from '../i18n.js'
+import { canQuire } from '../permissions.js'
+import { quireKeys } from '../query.js'
+
+/**
+ * One page (DESIGN.md §3.6): 780px measure, a 30px title, a byline under a hairline.
+ *
+ * The body is not here yet. The collaborative editor is the next slice, and until it exists this
+ * says so rather than drawing an empty box that looks broken — a surface that pretends to be
+ * editable and silently drops what you type is worse than one that admits it is not finished.
+ */
+interface Props {
+  spaceKey: string
+  pageId: string
+}
+const { spaceKey, pageId }: Props = $props()
+
+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 query = createQuery(() => ({
+  queryKey: quireKeys.page(workspaceId, pageId),
+  enabled: Boolean(workspaceId && pageId),
+  queryFn: () => api.pages.get({ workspaceId, pageId }),
+}))
+const doc = $derived(query.data ?? null)
+
+const editable = $derived(canQuire('pageEdit'))
+let title = $state('')
+let dirty = $state(false)
+let titleEl = $state<HTMLInputElement | null>(null)
+let peers = $state<CollabPeer[]>([])
+let historyOpen = $state(false)
+let busy = $state(false)
+let activeComment = $state<string | null>(null)
+let pendingComment = $state<{ anchor: { from: string; to: string }; quotedText: string } | null>(null)
+
+/**
+ * Anchors for the editor to highlight, from the threads the panel has loaded.
+ *
+ * The panel owns the query; this reads the same cache rather than asking again, so the margin and
+ * the highlights can never disagree about which threads exist.
+ */
+const threads = createQuery(() => ({
+  queryKey: [...quireKeys.page(workspaceId, pageId), 'comments'],
+  enabled: Boolean(workspaceId && pageId),
+  queryFn: () => api.comments.list({ workspaceId, pageId, includeResolved: false }),
+}))
+
+const commentRanges = $derived(
+  (threads.data ?? [])
+    .filter((t) => t.root.anchor)
+    .map((t) => ({ id: t.id, from: t.root.anchor!.from, to: t.root.anchor!.to })),
+)
+
+/**
+ * Threads whose text is gone.
+ *
+ * A relative position resolves to nothing once the content it pointed at is deleted, which is the
+ * whole reason for using one. The panel says so rather than the thread quietly vanishing — that is
+ * exactly when somebody's question matters most.
+ */
+let orphaned = $state(new Set<string>())
+
+/** The margin appears when there is something in it, or when somebody is about to put something there. */
+const showComments = $derived(pendingComment !== null || (threads.data ?? []).length > 0)
+
+/**
+ * A page created from the sidebar arrives with no title, and the only thing anybody wants to do next
+ * is name it. Without this the page is called "Untitled" and you have to go and find the field.
+ * Guarded on the title being empty so opening an existing page never steals the caret.
+ */
+$effect(() => {
+  const el = titleEl
+  if (el && doc && doc.title === '' && !dirty) el.focus()
+})
+
+/** Reset the field when a different page loads, but never over something being typed. */
+$effect(() => {
+  const loaded = doc
+  if (!loaded) return
+  if (!dirty) title = loaded.title
+})
+$effect(() => {
+  void pageId
+  dirty = false
+})
+
+async function saveTitle() {
+  if (!doc || !dirty) return
+  const next = title.trim()
+  if (next === doc.title) {
+    dirty = false
+    return
+  }
+  await api.pages.update({ workspaceId, pageId, title: next })
+  dirty = false
+  await client.invalidateQueries({ queryKey: quireKeys.page(workspaceId, pageId) })
+  await client.invalidateQueries({ queryKey: quireKeys.tree(workspaceId, doc.spaceId) })
+}
+
+async function archive(archived: boolean) {
+  if (!doc) return
+  await api.pages.archive({ workspaceId, pageId, archived })
+  await client.invalidateQueries({ queryKey: quireKeys.page(workspaceId, pageId) })
+  await client.invalidateQueries({ queryKey: quireKeys.tree(workspaceId, doc.spaceId) })
+}
+
+/**
+ * A page has a published face and a draft; a live doc has neither. Everything below is therefore
+ * only offered for a `page` — a live doc with a "publish" button would be a control that does
+ * nothing, which is worse than an absent one.
+ */
+async function publish() {
+  if (!doc || busy) return
+  busy = true
+  try {
+    await api.publishing.publish({ workspaceId, pageId, label: null })
+    await client.invalidateQueries({ queryKey: quireKeys.page(workspaceId, pageId) })
+  } finally {
+    busy = false
+  }
+}
+
+async function revert() {
+  if (!doc || busy) return
+  busy = true
+  try {
+    await api.publishing.revert({ workspaceId, pageId })
+    await client.invalidateQueries({ queryKey: quireKeys.page(workspaceId, pageId) })
+  } finally {
+    busy = false
+  }
+}
+
+async function trash() {
+  if (!doc) return
+  await api.pages.trashPage({ workspaceId, pageId })
+  await client.invalidateQueries({ queryKey: quireKeys.tree(workspaceId, doc.spaceId) })
+  void navigation.go(`/${workspaceSlug}/quire/${encodeURIComponent(spaceKey)}`)
+}
+</script>
+
+<div class="with-margin" class:open={showComments}>
+<Page padding="docs" maxWidth="780px">
+  {#if query.isLoading}
+    <Skeleton height="36px" />
+    <div class="gap"></div>
+    <Skeleton height="18px" />
+  {:else if query.isError}
+    <EmptyState icon="triangle-alert" title={t('page_error')} description={t('page_error_desc')}>
+      {#snippet actions()}
+        <Button variant="secondary" onclick={() => void query.refetch()}>{t('common.retry')}</Button>
+      {/snippet}
+    </EmptyState>
+  {:else if !doc}
+    <EmptyState icon="circle-help" title={t('page_missing')} description={t('page_missing_desc')} />
+  {:else}
+    <div class="head">
+      {#if editable}
+        <input
+          bind:this={titleEl}
+          class="title"
+          value={title}
+          placeholder={t('untitled')}
+          aria-label={t('page_title')}
+          oninput={(e) => {
+            title = (e.currentTarget as HTMLInputElement).value
+            dirty = true
+          }}
+          onblur={saveTitle}
+          onkeydown={(e) => {
+            if (e.key === 'Enter') {
+              e.preventDefault()
+              ;(e.currentTarget as HTMLInputElement).blur()
+            }
+          }}
+        />
+      {:else}
+        <h1 class="title">{doc.title.trim() || t('untitled')}</h1>
+      {/if}
+
+      <DropdownMenu
+        items={[
+          {
+            id: 'comments',
+            label: t('comments'),
+            icon: 'message-circle',
+            onSelect: () => {
+              // Nothing selected, so this is a remark about the page rather than a piece of it.
+              pendingComment = { anchor: { from: '', to: '' }, quotedText: '' }
+            },
+          },
+          {
+            id: 'history',
+            label: t('history'),
+            icon: 'rotate-ccw',
+            onSelect: () => (historyOpen = true),
+          },
+          ...(doc.kind === 'page' && canQuire('pageEdit')
+            ? [
+                {
+                  id: 'publish',
+                  label: t('publish'),
+                  icon: 'circle-check',
+                  disabled: busy,
+                  onSelect: () => void publish(),
+                },
+              ]
+            : []),
+          {
+            id: 'archive',
+            label: doc.archivedAt ? t('unarchive') : t('archive'),
+            icon: 'archive',
+            disabled: !editable,
+            onSelect: () => void archive(!doc.archivedAt),
+          },
+          {
+            id: 'trash',
+            label: t('move_to_trash'),
+            icon: 'trash-2',
+            danger: true,
+            disabled: !editable,
+            onSelect: () => void trash(),
+          },
+        ]}
+      >
+        {#snippet trigger(props: Record<string, unknown>)}
+          <IconButton icon="ellipsis" label={t('page_actions')} variant="ghost" {...props} />
+        {/snippet}
+      </DropdownMenu>
+    </div>
+
+    <div class="byline">
+      <Avatar id={doc.updatedBy} size={24} />
+      <span>{t('edited_ago', { when: relativeTime(doc.updatedAt) })}</span>
+      {#if doc.kind === 'live'}
+        <span class="chip"><Icon name="square-pen" size={12} /> {t('kind_live')}</span>
+      {/if}
+      {#if doc.archivedAt}
+        <span class="chip"><Icon name="archive" size={12} /> {t('archived')}</span>
+      {/if}
+      {#if peers.length > 0}
+        <span class="chip">{t('people_here', { count: peers.length })}</span>
+      {/if}
+    </div>
+
+    {#if doc.kind === 'page' && doc.hasUnpublishedChanges}
+      <div class="banner" role="status">
+        <Icon name="circle-alert" size={15} />
+        <span>{t('unpublished')}</span>
+        <span class="spacer"></span>
+        <Button size="sm" variant="secondary" disabled={busy} onclick={revert}>{t('revert')}</Button>
+        {#if canQuire('pageEdit')}
+          <Button size="sm" disabled={busy} onclick={publish}>{t('publish')}</Button>
+        {/if}
+      </div>
+    {/if}
+
+    <div class="body">
+      <PageEditor
+        {doc}
+        onpeers={(p) => (peers = p)}
+        {commentRanges}
+        {activeComment}
+        onCommentClick={(id) => (activeComment = id)}
+        oncomment={(anchor, quotedText) => {
+          pendingComment = { anchor, quotedText }
+          activeComment = null
+        }}
+      />
+    </div>
+  {/if}
+</Page>
+
+{#if doc && showComments}
+  <CommentsPanel
+    {workspaceId}
+    {pageId}
+    activeId={activeComment}
+    {orphaned}
+    onFocus={(id) => (activeComment = id)}
+    pending={pendingComment}
+    onPendingHandled={() => (pendingComment = null)}
+  />
+{/if}
+</div>
+
+{#if doc}
+  <VersionHistory
+    bind:open={historyOpen}
+    {workspaceId}
+    {pageId}
+    publishedVersionId={doc.publishedVersionId}
+  />
+{/if}
+
+<style>
+.gap {
+  height: 14px;
+}
+.head {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+}
+.title {
+  flex: 1;
+  min-width: 0;
+  font-size: 30px;
+  font-weight: 600;
+  letter-spacing: -0.03em;
+  line-height: 1.2;
+  color: var(--kern-ink-900);
+  margin: 0;
+  border: 0;
+  background: none;
+  padding: 0;
+  font-family: inherit;
+}
+.title:focus {
+  outline: none;
+}
+.byline {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  margin-block-start: 14px;
+  padding-block-end: 20px;
+  border-block-end: 1px solid var(--kern-border);
+  font-size: 13px;
+  color: var(--kern-ink-400);
+}
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+.body {
+  margin-block-start: 22px;
+}
+/*
+ * The margin is a column beside the page rather than an overlay: a comment is about a specific
+ * sentence, and an overlay covers the sentence you are reading it against.
+ */
+.with-margin {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+  min-width: 0;
+}
+.with-margin.open :global(> .kpage) {
+  min-width: 0;
+}
+.with-margin.open > :global(aside) {
+  width: 320px;
+  flex: none;
+}
+@media (max-width: 900px) {
+  .with-margin.open > :global(aside) {
+    width: 260px;
+  }
+}
+/*
+ * Above the body rather than beside the title: it is about what a reader currently sees, which is
+ * a statement about the text underneath it.
+ */
+.banner {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-block-start: 18px;
+  padding: 10px 12px;
+  border-radius: var(--kern-r-lg);
+  background: var(--kern-warning-tint);
+  color: var(--kern-ink-700);
+  font-size: 13px;
+}
+.spacer {
+  flex: 1;
+}
+</style>

package/src/client/pages/SpacePage.svelte

@@ -0,0 +1,79 @@
+<script lang="ts">
+import { Button, EmptyState, navigation, Skeleton, session } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { canQuire } from '../permissions.js'
+import { quireKeys } from '../query.js'
+import PageView from './PageView.svelte'
+
+/**
+ * A space with no page chosen.
+ *
+ * If the space has a home page, that is what opening it means; otherwise this is the first thing
+ * somebody sees, so it has to offer the one action that gets them out of it.
+ */
+interface Props {
+  spaceKey: string
+}
+const { spaceKey }: Props = $props()
+
+const api = getQuireApi()
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspaceId = $derived(session.workspaces.find((w) => w.slug === workspaceSlug)?.id ?? '')
+
+const spacesQuery = createQuery(() => ({
+  queryKey: quireKeys.spaces(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.spaces.list({ workspaceId, includeArchived: false }),
+}))
+const space = $derived((spacesQuery.data ?? []).find((s) => s.key === spaceKey) ?? null)
+
+let creating = $state(false)
+async function createFirst() {
+  if (!space || creating) return
+  creating = true
+  try {
+    const created = await api.pages.create({
+      workspaceId,
+      spaceId: space.id,
+      parentId: null,
+      title: '',
+      kind: 'page',
+      icon: null,
+      afterId: null,
+    })
+    void navigation.go(
+      `/${workspaceSlug}/quire/${encodeURIComponent(spaceKey)}/${encodeURIComponent(created.id)}`,
+    )
+  } finally {
+    creating = false
+  }
+}
+</script>
+
+{#if spacesQuery.isLoading}
+  <div class="pad"><Skeleton height="36px" /></div>
+{:else if !space}
+  <div class="pad">
+    <EmptyState icon="scroll-text" title={t('space_missing')} description={t('space_missing_desc')} />
+  </div>
+{:else if space.homepageId}
+  <PageView {spaceKey} pageId={space.homepageId} />
+{:else}
+  <div class="pad">
+    <EmptyState icon="file-text" title={t('space_empty')} description={t('space_empty_desc')}>
+      {#snippet actions()}
+        {#if canQuire('pageCreate')}
+          <Button disabled={creating} onclick={createFirst}>{t('new_page')}</Button>
+        {/if}
+      {/snippet}
+    </EmptyState>
+  </div>
+{/if}
+
+<style>
+.pad {
+  padding: 28px 32px 48px;
+}
+</style>

package/src/client/pages/SpacesPage.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+import { Button, Card, EmptyState, Icon, navigation, Page, PageHeader, Skeleton, session } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getQuireApi } from '../api-instance.js'
+import NewSpaceDialog from '../components/NewSpaceDialog.svelte'
+import { t } from '../i18n.js'
+import { canQuire } from '../permissions.js'
+import { quireKeys } from '../query.js'
+
+/**
+ * The spaces in this workspace.
+ *
+ * Quire's front door is a list of spaces rather than a page, because a space is the unit people
+ * think in — "the handbook", "engineering" — and the tree in the sidebar only makes sense once one
+ * is chosen. A space with a home page opens straight to it.
+ */
+const api = getQuireApi()
+
+const workspaceSlug = $derived(navigation.workspaceSlug)
+const workspace = $derived(session.workspaces.find((w) => w.slug === workspaceSlug))
+const workspaceId = $derived(workspace?.id ?? '')
+
+const spacesQuery = createQuery(() => ({
+  queryKey: quireKeys.spaces(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.spaces.list({ workspaceId, includeArchived: false }),
+}))
+const spaceList = $derived(spacesQuery.data ?? [])
+
+let newOpen = $state(navigation.search.new === '1')
+
+function open(key: string) {
+  void navigation.go(`/${workspaceSlug}/quire/${encodeURIComponent(key)}`)
+}
+</script>
+
+<PageHeader
+  crumbs={[{ label: workspace?.name ?? '' }, { label: t('title') }]}
+  title={t('title')}
+  subtitle={t('subtitle')}
+>
+  {#snippet actions()}
+    {#if canQuire('spaceManage')}
+      <Button size="sm" onclick={() => (newOpen = true)}>{t('new_space')}</Button>
+    {/if}
+  {/snippet}
+</PageHeader>
+
+<Page>
+  {#if spacesQuery.isLoading}
+    <div class="grid">
+      {#each [1, 2, 3] as n (n)}<Skeleton height="112px" />{/each}
+    </div>
+  {:else if spacesQuery.isError}
+    <EmptyState icon="triangle-alert" title={t('spaces_error')} description={t('spaces_error_desc')}>
+      {#snippet actions()}
+        <Button variant="secondary" onclick={() => void spacesQuery.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')}>
+      {#snippet actions()}
+        {#if canQuire('spaceManage')}
+          <Button icon="plus" onclick={() => (newOpen = true)}>{t('new_space')}</Button>
+        {/if}
+      {/snippet}
+    </EmptyState>
+  {:else}
+    <div class="grid">
+      {#each spaceList as space (space.id)}
+        <button class="space" type="button" onclick={() => open(space.key)}>
+          <Card>
+            <div class="head">
+              <span class="ic"><Icon name={space.icon || 'scroll-text'} size={18} /></span>
+              <span class="name">{space.name}</span>
+            </div>
+            {#if space.description}
+              <p class="desc">{space.description}</p>
+            {/if}
+            <p class="meta">
+              {space.visibility === 'open'
+                ? t('visibility_open')
+                : space.visibility === 'restricted'
+                  ? t('visibility_restricted')
+                  : t('visibility_private')}
+            </p>
+          </Card>
+        </button>
+      {/each}
+    </div>
+  {/if}
+</Page>
+
+<NewSpaceDialog bind:open={newOpen} {workspaceId} onCreated={(space) => open(space.key)} />
+
+<style>
+.grid {
+  display: grid;
+  /*
+   * `auto-fit`, not `auto-fill`. `auto-fill` keeps the empty tracks, so two spaces in a wide window
+   * sit at their minimum width with the rest of the row blank; `auto-fit` collapses them and the
+   * cards share the space. Every other card grid in the app already does this.
+   */
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 12px;
+}
+.space {
+  border: 0;
+  background: none;
+  padding: 0;
+  text-align: start;
+  cursor: pointer;
+  font: inherit;
+}
+.head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+.ic {
+  display: inline-flex;
+  color: var(--kern-ink-400);
+}
+.name {
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--kern-ink-900);
+  letter-spacing: -0.01em;
+}
+.desc {
+  margin: 8px 0 0;
+  font-size: 13.5px;
+  line-height: 1.5;
+  color: var(--kern-ink-650);
+}
+.meta {
+  margin: 10px 0 0;
+  font-size: 12.5px;
+  color: var(--kern-ink-400);
+}
+</style>

package/src/client/permissions.ts

@@ -0,0 +1,39 @@
+import { session } from '@kernhq/ui'
+import { quirePermissions } from '../contract/permissions.js'
+
+/**
+ * What quire lets somebody do.
+ *
+ * Derived from the contract rather than re-typed, and `key()` throws at import when a name does not
+ * exist. There were two hand-written copies of this before — one in the package and one in the app —
+ * and they had drifted: the package's was missing `page.comment` and `page.publish` entirely, so any
+ * screen gating on them through that copy silently had no key at all. Nothing reported it, because
+ * a wrong permission string is a perfectly valid string.
+ *
+ * Every key is declared at **space** scope on the server, so a person may be able to edit one space
+ * and only read another. `session.can` answers for the workspace, which is the right answer for
+ * "should this appear in the rail at all" and the wrong one for "may I edit this page" — the page
+ * asks the server for that, and the server is what refuses.
+ */
+const key = (suffix: string) => {
+  const found = quirePermissions.find((p) => p.key === `quire.${suffix}`)
+  if (!found) throw new Error(`quire: no permission declared for quire.${suffix}`)
+  return found.key
+}
+
+export const QUIRE_PERMISSIONS = {
+  spaceView: key('space.view'),
+  spaceManage: key('space.manage'),
+  pageView: key('page.view'),
+  pageCreate: key('page.create'),
+  pageComment: key('page.comment'),
+  pageEdit: key('page.edit'),
+  pagePublish: key('page.publish'),
+  pageDelete: key('page.delete'),
+} as const
+
+export type QuirePermission = keyof typeof QUIRE_PERMISSIONS
+
+export function canQuire(permission: QuirePermission): boolean {
+  return session.can(QUIRE_PERMISSIONS[permission])
+}

package/src/client/query.ts

@@ -0,0 +1,15 @@
+/**
+ * Query keys, shaped `[module, entity, …scope]` so a realtime `change` message invalidates exactly
+ * the queries it touches — `lib/realtime.svelte.ts` compares the `[module, entity]` prefix.
+ *
+ * The entity names have to match what the server sends in `kernel.realtime.change`: `space` and
+ * `page`. A key that spells one differently is a screen that never refreshes and nobody notices
+ * until somebody else edits something.
+ */
+export const quireKeys = {
+  spaces: (workspaceId: string) => ['quire', 'space', workspaceId] as const,
+  space: (workspaceId: string, spaceId: string) => ['quire', 'space', workspaceId, spaceId] as const,
+  tree: (workspaceId: string, spaceId: string) => ['quire', 'page', workspaceId, 'tree', spaceId] as const,
+  page: (workspaceId: string, pageId: string) => ['quire', 'page', workspaceId, pageId] as const,
+  trash: (workspaceId: string, spaceId: string) => ['quire', 'page', workspaceId, 'trash', spaceId] as const,
+}