@kernhq/module-quire 0.10.9 → 0.11.0

package/src/client/components/PageLabels.svelte

@@ -0,0 +1,158 @@
+<script lang="ts">
+import { DropdownMenu, IconButton, type MenuItem } from '@kernhq/ui'
+import { createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { untrack } from 'svelte'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { quireKeys } from '../query.js'
+import LabelChip from './LabelChip.svelte'
+import LabelManager from './LabelManager.svelte'
+
+/**
+ * The labels a page wears, and the menu that changes them.
+ *
+ * `pages.setLabels` replaces the whole set rather than adding one, so this holds the ticked set
+ * locally and sends all of it on every toggle. That is what makes unticking expressible at all —
+ * an additive procedure would need a second one to pair with it, and the pair would then have to
+ * agree about a page two people are editing.
+ *
+ * The local set is also what makes the menu feel like a menu. A checkbox that only ticks once the
+ * server has answered reads as broken at any latency worth having, so the tick lands immediately
+ * and the request follows; a failure resyncs from the server rather than leaving a lie on screen.
+ *
+ * The seeding effect reads `selected` and `inflight` through `untrack` because it writes the first
+ * and is gated on the second — tracked, the write would make the effect its own trigger and every
+ * tick would be undone by the stale answer still in the cache.
+ */
+interface Props {
+  workspaceId: string
+  spaceId: string
+  pageId: string
+  canEdit: boolean
+  canManage: boolean
+}
+const { workspaceId, spaceId, pageId, canEdit, canManage }: Props = $props()
+
+const api = getQuireApi()
+const client = useQueryClient()
+
+const onPage = createQuery(() => ({
+  queryKey: quireKeys.pageLabels(workspaceId, pageId),
+  enabled: Boolean(workspaceId && pageId),
+  queryFn: () => api.labels.forPage({ workspaceId, pageId }),
+}))
+
+/** The whole vocabulary, so the menu can offer what is *not* on the page as well as what is. */
+const inSpace = createQuery(() => ({
+  queryKey: quireKeys.labels(workspaceId, spaceId),
+  enabled: Boolean(workspaceId && spaceId),
+  queryFn: () => api.labels.list({ workspaceId, spaceId }),
+}))
+
+let selected = $state(new Set<string>())
+let inflight = $state(0)
+let managerOpen = $state(false)
+
+$effect(() => {
+  const data = onPage.data
+  if (!data) return
+  if (untrack(() => inflight) > 0) return
+  const next = new Set(data.map((l) => l.id))
+  const current = untrack(() => selected)
+  if (next.size !== current.size || [...next].some((id) => !current.has(id))) selected = next
+})
+
+/**
+ * Drawn from the space's list rather than from the page's own answer, so a rename shows up on the
+ * chip without this page being refetched — and so a tick that has not reached the server yet is
+ * already a chip. The page's answer stands in until the list has loaded.
+ */
+const chips = $derived(
+  inSpace.data
+    ? inSpace.data.filter((l) => selected.has(l.id))
+    : (onPage.data ?? []).filter((l) => selected.has(l.id)),
+)
+
+async function toggle(labelId: string, on: boolean) {
+  const next = new Set(selected)
+  if (on) next.add(labelId)
+  else next.delete(labelId)
+  selected = next
+  inflight++
+  try {
+    await api.pages.setLabels({ workspaceId, pageId, labelIds: [...next] })
+  } catch {
+    // The optimistic tick was a guess; the server's answer is the fact.
+    await onPage.refetch()
+  } finally {
+    inflight--
+    /*
+     * The whole `label` prefix, not just this page's key. The sidebar's label filter holds a
+     * page-to-labels map for the space, and labelling a page here is precisely what makes it
+     * stale — the server announces `page updated` for this, which lands on the `page` prefix and
+     * never reaches it.
+     */
+    if (inflight === 0) await client.invalidateQueries({ queryKey: ['quire', 'label', workspaceId] })
+  }
+}
+
+const items = $derived.by((): MenuItem[] => {
+  const all = inSpace.data ?? []
+  const rows: MenuItem[] = [{ type: 'label', label: t('labels_edit') }]
+  if (all.length === 0) rows.push({ id: 'none', label: t('labels_empty'), disabled: true })
+  for (const label of all)
+    rows.push({
+      type: 'checkbox',
+      id: label.id,
+      label: label.name,
+      checked: selected.has(label.id),
+      onCheckedChange: (on: boolean) => void toggle(label.id, on),
+    })
+  if (canManage) {
+    rows.push({ type: 'separator' })
+    rows.push({
+      id: 'manage',
+      label: t('labels_manage'),
+      icon: 'settings',
+      onSelect: () => (managerOpen = true),
+    })
+  }
+  return rows
+})
+</script>
+
+{#if chips.length > 0 || canEdit}
+  <div class="labels">
+    {#each chips as label (label.id)}
+      <LabelChip {label} />
+    {/each}
+
+    {#if canEdit}
+      <DropdownMenu {items} align="start">
+        {#snippet trigger(props: Record<string, unknown>)}
+          <IconButton
+            {...props}
+            icon="tag"
+            size={26}
+            variant="ghost"
+            label={chips.length === 0 ? t('label_none_on_page') : t('labels_edit')}
+          />
+        {/snippet}
+      </DropdownMenu>
+    {/if}
+  </div>
+{/if}
+
+{#if canManage}
+  <LabelManager bind:open={managerOpen} {workspaceId} {spaceId} />
+{/if}
+
+<style>
+.labels {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+  margin-block-start: 12px;
+}
+</style>

package/src/client/components/SidebarFavorites.svelte

@@ -0,0 +1,262 @@
+<script lang="ts">
+import {
+  DropdownMenu,
+  formatCount,
+  IconButton,
+  type MenuItem,
+  navigation,
+  SectionLabel,
+  SidebarItem,
+} from '@kernhq/ui'
+import { createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { untrack } from 'svelte'
+import { dndzone, SHADOW_ITEM_MARKER_PROPERTY_NAME } from 'svelte-dnd-action'
+import type { FavoriteEntry, Space } from '../../contract/index.js'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { quireKeys } from '../query.js'
+
+/**
+ * One person's own shortcuts, at the top of the sidebar where a table of contents is not.
+ *
+ * The list is the *workspace's*, not the space's — a favourite is "I want this to hand", and
+ * losing it because you switched space would defeat the point. Each entry carries the little of
+ * its page a row needs to draw itself, so the group is one request rather than one per row.
+ *
+ * Reordering is a drag and a menu, and the menu is not a fallback: `svelte-dnd-action` cannot be
+ * reached from a keyboard, so without **Move up** and **Move down** half the people using this
+ * could not reorder anything. Both go through `favorites.reorder`, which mints a fractional index
+ * server-side and answers with the whole list — so the reply *is* the new order and nothing has to
+ * refetch to find out what happened.
+ *
+ * Three traps in `svelte-dnd-action`, all of which have shipped in this project before: it tracks
+ * items by an `id` property and nothing else (a favourite is keyed by `pageId`, so the rows carry
+ * an `id` alias); the list must be `$state.raw`, because a deep-reactive proxy hands the library a
+ * different object on every read and it reads that as an endless stream of changes; and the
+ * seeding effect reads its `dragging` guard through `untrack`, or clearing the flag at the end of
+ * a drop re-runs it against the old query data and undoes the move on screen.
+ */
+interface Props {
+  workspaceId: string
+  workspaceSlug: string
+  /** the spaces this person can see, for turning a favourite's `spaceId` into a URL */
+  spaces: readonly Space[]
+  activePageId: string | null
+}
+const { workspaceId, workspaceSlug, spaces, activePageId }: Props = $props()
+
+const api = getQuireApi()
+const client = useQueryClient()
+
+const query = createQuery(() => ({
+  queryKey: quireKeys.favorites(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.favorites.list({ workspaceId }),
+}))
+
+type Entry = FavoriteEntry & { id: string; [SHADOW_ITEM_MARKER_PROPERTY_NAME]?: boolean }
+
+const keyOf = $derived(new Map(spaces.map((s) => [s.id, s.key])))
+
+/**
+ * A favourite whose space this person cannot see is not drawn.
+ *
+ * The row would have nowhere to go: a page's URL is `/quire/<space key>/<page id>`, and the key
+ * comes from the space list. The server already drops the entries whose *pages* are unreadable, so
+ * what is left here is the narrower case of a space that has since been archived.
+ */
+const rows = $derived(
+  (query.data ?? []).filter((f) => keyOf.has(f.spaceId)).map((f): Entry => ({ ...f, id: f.pageId })),
+)
+
+let ordered = $state.raw<Entry[]>([])
+let dragging = $state(false)
+let busy = $state(false)
+
+$effect(() => {
+  const next = rows
+  if (untrack(() => dragging)) return
+  ordered = next
+})
+
+const hrefFor = (entry: Entry) =>
+  `/${workspaceSlug}/quire/${encodeURIComponent(keyOf.get(entry.spaceId) ?? '')}/${encodeURIComponent(entry.pageId)}`
+
+const iconFor = (entry: Entry) =>
+  entry.kind === 'live' ? 'square-pen' : entry.kind === 'database' ? 'database' : 'file-text'
+
+const titleOf = (entry: Entry) => entry.title.trim() || t('untitled')
+
+const isShadow = (entry: Entry) => Boolean(entry[SHADOW_ITEM_MARKER_PROPERTY_NAME])
+
+/** `afterId` is the favourite to land behind; null means first. */
+async function move(pageId: string, afterId: string | null) {
+  if (busy) return
+  busy = true
+  try {
+    const list = await api.favorites.reorder({ workspaceId, pageId, afterId })
+    client.setQueryData(quireKeys.favorites(workspaceId), list)
+  } finally {
+    busy = false
+  }
+}
+
+async function remove(pageId: string) {
+  if (busy) return
+  busy = true
+  try {
+    const list = await api.favorites.remove({ workspaceId, pageId })
+    client.setQueryData(quireKeys.favorites(workspaceId), list)
+  } finally {
+    busy = false
+  }
+}
+
+function consider(event: CustomEvent<{ items: Entry[] }>) {
+  dragging = true
+  ordered = event.detail.items
+}
+
+function finalize(event: CustomEvent<{ items: Entry[] }>) {
+  const items = event.detail.items
+  ordered = items
+  const before = new Map(untrack(() => rows).map((r, i) => [r.id, i]))
+  const moved = items.find((item, index) => before.get(item.id) !== index)
+  dragging = false
+  if (!moved) return
+  const at = items.indexOf(moved)
+  void move(moved.pageId, at > 0 ? (items[at - 1]?.pageId ?? null) : null)
+}
+
+function menuFor(entry: Entry, index: number): MenuItem[] {
+  const title = titleOf(entry)
+  return [
+    {
+      id: 'up',
+      label: t('favorite_move_up', { title }),
+      icon: 'chevron-up',
+      disabled: index === 0,
+      onSelect: () => void move(entry.pageId, index > 1 ? (ordered[index - 2]?.pageId ?? null) : null),
+    },
+    {
+      id: 'down',
+      label: t('favorite_move_down', { title }),
+      icon: 'chevron-down',
+      disabled: index >= ordered.length - 1,
+      onSelect: () => void move(entry.pageId, ordered[index + 1]?.pageId ?? null),
+    },
+    { type: 'separator' },
+    {
+      id: 'remove',
+      label: t('favorite_remove'),
+      icon: 'star',
+      danger: true,
+      onSelect: () => void remove(entry.pageId),
+    },
+  ]
+}
+
+function open(entry: Entry) {
+  void navigation.go(hrefFor(entry))
+}
+</script>
+
+{#if ordered.length > 0}
+  <div class="group">
+    <SectionLabel label={t('favorites')} count={formatCount(ordered.length)} />
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div
+      class="stack"
+      use:dndzone={{
+        items: ordered,
+        flipDurationMs: 140,
+        type: 'quire-favorites',
+        dragDisabled: ordered.length < 2,
+        dropTargetStyle: {},
+      }}
+      onconsider={consider}
+      onfinalize={finalize}
+    >
+      {#each ordered as entry, index (entry.id)}
+        <div class="row" class:shadow={isShadow(entry)}>
+          <SidebarItem
+            label={titleOf(entry)}
+            icon={iconFor(entry)}
+            active={activePageId === entry.pageId}
+            onclick={() => open(entry)}
+          >
+            {#snippet trailing()}
+              <!--
+                Room for the menu, which is a sibling laid over the row rather than a child of it:
+                `SidebarItem` is a `<button>`, and a button inside a button is invalid markup whose
+                accessible name becomes the two labels run together.
+              -->
+              <span class="well"></span>
+            {/snippet}
+          </SidebarItem>
+
+          <span class="actions">
+            <DropdownMenu items={menuFor(entry, index)}>
+              {#snippet trigger(props: Record<string, unknown>)}
+                <IconButton
+                  {...props}
+                  icon="ellipsis"
+                  size={22}
+                  variant="ghost"
+                  label={t('favorite_actions', { title: titleOf(entry) })}
+                />
+              {/snippet}
+            </DropdownMenu>
+          </span>
+        </div>
+      {/each}
+    </div>
+  </div>
+{/if}
+
+<style>
+.group {
+  padding-block-end: 6px;
+}
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+.row {
+  position: relative;
+}
+/*
+ * The placeholder the library leaves where the row came from. Drawn as an outline rather than
+ * faded, because fading it would mute its text against the pane — `opacity` on a row is how
+ * "muted" becomes "unreadable".
+ */
+.row.shadow :global(.ksi) {
+  visibility: hidden;
+}
+.row.shadow {
+  border: 1px dashed var(--kern-border-strong);
+  border-radius: var(--kern-r-xl);
+}
+.well {
+  width: 22px;
+  flex: none;
+}
+/*
+ * `opacity: 0` rather than `display: none` keeps the control focusable, and `:focus-within` on the
+ * row is what makes it visible once the keyboard arrives — the same shape as the page tree's add
+ * button, and the reason **Move up** is reachable at all.
+ */
+.actions {
+  position: absolute;
+  inset-block-start: 50%;
+  inset-inline-end: 8px;
+  transform: translateY(-50%);
+  display: inline-flex;
+  opacity: 0;
+}
+.row:hover .actions,
+.row:focus-within .actions {
+  opacity: 1;
+}
+</style>

package/src/client/components/SidebarRecents.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+import { navigation, relativeTime, SectionLabel, SidebarItem } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import type { RecentEntry, Space } from '../../contract/index.js'
+import { getQuireApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import { quireKeys } from '../query.js'
+
+/**
+ * Where this person has just been, newest first.
+ *
+ * Below the tree rather than above it: the tree is the space's table of contents and the thing
+ * somebody came to the sidebar for, and a list that reorders itself every time you open a page is
+ * a poor thing to put in front of it. Eight rows, because this answers "take me back" and not
+ * "what have I read" — the row is a shortcut, and a long list of them stops being one.
+ *
+ * `recents.record` is called by the page screen on open; nothing here writes. The list is one
+ * person's own — the server filters it by the caller, which is the only thing keeping it personal,
+ * since row-level security fences the workspace rather than the reader.
+ */
+interface Props {
+  workspaceId: string
+  workspaceSlug: string
+  spaces: readonly Space[]
+  activePageId: string | null
+}
+const { workspaceId, workspaceSlug, spaces, activePageId }: Props = $props()
+
+const api = getQuireApi()
+
+const query = createQuery(() => ({
+  queryKey: quireKeys.recents(workspaceId),
+  enabled: Boolean(workspaceId),
+  queryFn: () => api.recents.list({ workspaceId, limit: 8 }),
+}))
+
+const keyOf = $derived(new Map(spaces.map((s) => [s.id, s.key])))
+
+/** Same as the favourites group: a row whose space has no key has nowhere to navigate to. */
+const rows = $derived((query.data ?? []).filter((r) => keyOf.has(r.spaceId)))
+
+const titleOf = (entry: RecentEntry) => entry.title.trim() || t('untitled')
+
+const iconFor = (entry: RecentEntry) =>
+  entry.kind === 'live' ? 'square-pen' : entry.kind === 'database' ? 'database' : 'file-text'
+
+function open(entry: RecentEntry) {
+  void navigation.go(
+    `/${workspaceSlug}/quire/${encodeURIComponent(keyOf.get(entry.spaceId) ?? '')}/${encodeURIComponent(entry.pageId)}`,
+  )
+}
+</script>
+
+{#if rows.length > 0}
+  <div class="group">
+    <SectionLabel label={t('recent')} />
+    <div class="stack">
+      {#each rows as entry (entry.pageId)}
+        <SidebarItem
+          label={titleOf(entry)}
+          icon={iconFor(entry)}
+          active={activePageId === entry.pageId}
+          onclick={() => open(entry)}
+        >
+          {#snippet trailing()}
+            <!--
+              A relative time, not a date: this list is only ever read as "how long ago", and
+              `relativeTime` renders it in the interface language rather than as a raw number.
+            -->
+            <span class="when">{relativeTime(entry.viewedAt)}</span>
+          {/snippet}
+        </SidebarItem>
+      {/each}
+    </div>
+  </div>
+{/if}
+
+<style>
+.group {
+  padding-block-start: 10px;
+}
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+/*
+ * Muted with a colour, never with `opacity` — and never smaller than 11.5px, which is where this
+ * pane's ink stops being legible against its own background.
+ */
+.when {
+  flex: none;
+  font-family: var(--kern-font-mono);
+  font-size: 11.5px;
+  color: var(--kern-ink-350);
+  letter-spacing: -0.01em;
+}
+</style>