qarpeo 0.0.0-alpha.10

package/dist/runtime/app/components/CMSVersionBanner.vue

@@ -0,0 +1,49 @@
+<script lang="ts" setup>
+import { computed } from "vue"
+import { useDocsVersion } from "../composables/docs-version"
+
+/**
+ * `<CMSVersionBanner>` / `<DocsVersionBanner>` — Warning banner displayed when a reader
+ * is viewing an archived or legacy documentation version. Provides a one-click link to
+ * the equivalent page in the latest version.
+ */
+withDefaults(defineProps<{
+  class?: string
+}>(), {
+  class: "",
+})
+
+const { isLatest, activeVersionItem, getVersionPath } = useDocsVersion()
+const latestUrl = computed(() => getVersionPath("latest"))
+</script>
+
+<template>
+  <div
+    v-if="!isLatest"
+    :class="[
+      'rounded-lg border border-amber-300/80 dark:border-amber-700/60 bg-amber-50/90 dark:bg-amber-950/30 p-3.5 text-xs text-amber-900 dark:text-amber-200 mb-6 flex flex-col sm:flex-row items-start sm:items-center justify-between gap-2 shadow-xs',
+      $props.class,
+    ]"
+    role="alert"
+    aria-live="polite"
+  >
+    <div class="flex items-center gap-2">
+      <span class="text-base leading-none">⚠️</span>
+      <span>
+        You are viewing archived documentation for
+        <strong class="font-semibold">{{ activeVersionItem.label }}</strong>.
+        This version may be outdated.
+      </span>
+    </div>
+    <UButton
+      :to="latestUrl"
+      size="xs"
+      color="warning"
+      variant="subtle"
+      class="shrink-0"
+      trailing-icon="i-lucide-arrow-right"
+    >
+      Switch to latest version
+    </UButton>
+  </div>
+</template>

package/dist/runtime/app/components/CMSVersionSwitcher.vue

@@ -0,0 +1,126 @@
+<script lang="ts" setup>
+import { computed } from "vue"
+import { useDocsVersion } from "../composables/docs-version"
+
+/**
+ * `<CMSVersionSwitcher>` / `<DocsVersionSwitcher>` — Polished Nuxt UI component for switching
+ * between documentation versions. Preserves the active subpath when switching.
+ */
+const props = withDefaults(
+  defineProps<{
+    variant?: "dropdown" | "select" | "buttons" | "badge"
+    size?: "xs" | "sm" | "md"
+    color?: "primary" | "neutral" | "secondary"
+    class?: string
+  }>(),
+  {
+    variant: "dropdown",
+    size: "xs",
+    color: "primary",
+    class: "",
+  },
+)
+
+const { currentVersion, versions, switchVersion } = useDocsVersion()
+
+const currentLabel = computed(() => {
+  const item = versions.value?.find((v) => v.id === currentVersion.value)
+  if (item?.label) return item.label
+  return currentVersion.value === "latest" ? "latest" : currentVersion.value
+})
+
+const dropdownItems = computed(() => [
+  (versions.value || []).map((v) => ({
+    label: v.label,
+    icon: v.id === currentVersion.value ? "i-lucide-check" : undefined,
+    badge: v.isLatest ? "latest" : v.isArchived ? "legacy" : undefined,
+    onSelect: () => switchVersion(v.id),
+  })),
+])
+
+const selectItems = computed(() =>
+  (versions.value || []).map((v) => ({
+    label: v.label + (v.isArchived ? " (legacy)" : ""),
+    value: v.id,
+  })),
+)
+</script>
+
+<template>
+  <template v-if="versions && versions.length > 1">
+    <!-- Buttons variant -->
+    <div
+      v-if="variant === 'buttons'"
+      :class="['inline-flex items-center gap-1 rounded-lg border border-gray-200 dark:border-gray-800 p-1 bg-gray-50/50 dark:bg-gray-900/50 text-xs font-medium', props.class]"
+      role="group"
+      aria-label="Documentation version switcher"
+    >
+      <UButton
+        v-for="v in versions"
+        :key="v.id"
+        :size="size"
+        variant="ghost"
+        :color="color"
+        :label="v.label"
+        :class="[
+          'flex items-center gap-1.5 transition-colors',
+          v.id === currentVersion
+            ? 'bg-white dark:bg-gray-800 text-gray-900 dark:text-white shadow-xs font-semibold'
+            : 'text-gray-600 dark:text-gray-400',
+        ]"
+        @click="switchVersion(v.id)"
+      >
+        <template v-if="v.isLatest" #trailing>
+          <UBadge
+            size="xs"
+            :color="color"
+            variant="subtle"
+            class="text-[10px] font-semibold"
+            label="latest"
+          />
+        </template>
+      </UButton>
+    </div>
+
+    <!-- Select variant: Nuxt UI USelect -->
+    <USelect
+      v-else-if="variant === 'select'"
+      :model-value="currentVersion"
+      :items="selectItems"
+      :size="size"
+      :color="color"
+      variant="subtle"
+      class="font-mono"
+      :class="props.class"
+      @update:model-value="switchVersion($event)"
+    />
+
+    <!-- Dropdown variant (DEFAULT): Nuxt UI UDropdownMenu with subtle button trigger -->
+    <UDropdownMenu
+      v-else
+      :items="dropdownItems"
+      :content="{ align: 'start' }"
+    >
+      <UButton
+        :size="size"
+        :color="color"
+        variant="subtle"
+        class="font-mono cursor-pointer"
+        trailing-icon="i-lucide-chevron-down"
+        :class="props.class"
+        :label="currentLabel"
+      />
+    </UDropdownMenu>
+  </template>
+
+  <!-- Single version or loading fallback: static Nuxt UI UBadge -->
+  <UBadge
+    v-else
+    :color="color"
+    variant="subtle"
+    :size="size"
+    class="font-mono"
+    :class="props.class"
+    :label="currentLabel"
+  />
+</template>

package/dist/runtime/app/components/ContentRenderer.vue

@@ -0,0 +1,80 @@
+<script lang="ts" setup>
+import { computed, shallowRef, watchEffect } from "vue"
+import { MarkdownDocument } from "@comark/vue"
+import { isMarkdownDocument } from "comark/utils"
+import { createSerializedMarkdownParser } from "comark"
+
+/**
+ * `<ContentRenderer>` — Renders a CMS content value (Comark AST, raw markdown string, or page object).
+ * Pre-parsed server ASTs are rendered instantly with zero client-side Shiki overhead.
+ */
+const props = withDefaults(defineProps<{
+  value?: object | string | null
+  excerpt?: boolean
+  tag?: string | boolean
+  as?: string | boolean
+  class?: string | any[] | Record<string, boolean>
+  unwrap?: boolean | string | any[]
+  components?: Record<string, any>
+  plugins?: any[]
+}>(), {
+  value: null,
+  excerpt: false,
+  tag: "div",
+  class: "",
+  unwrap: false,
+  components: () => ({}),
+  plugins: () => [],
+})
+
+const resolvedValue = computed(() => {
+  const val = props.value as any
+  if (!val) return ""
+  if (isMarkdownDocument(val)) return val
+  if (isMarkdownDocument(val.body)) return val.body
+  if (typeof val.contentMd === "string" && val.contentMd) return val.contentMd
+  if (typeof val.body === "string" && val.body) return val.body
+  if (typeof val.body?.value === "string") return val.body.value
+  if (typeof val.body?.content === "string") return val.body.content
+  return ""
+})
+
+// Lazily-created parser (avoids importing Shiki on the client)
+let _parser: ReturnType<typeof createSerializedMarkdownParser> | null = null
+function getParser() {
+  if (!_parser) {
+    _parser = createSerializedMarkdownParser({ plugins: (props.plugins as any[]) || [] })
+  }
+  return _parser
+}
+
+const parsedDoc = shallowRef<any>(null)
+
+watchEffect(() => {
+  const content = resolvedValue.value
+  if (typeof content === "string" && content) {
+    const raw = props.excerpt ? content.split("<!-- more -->")[0] : content
+    getParser()(raw.trim(), { streaming: false }).then((doc) => {
+      parsedDoc.value = doc
+    })
+  } else {
+    parsedDoc.value = null
+  }
+})
+</script>
+
+<template>
+  <slot v-if="!resolvedValue" name="empty" />
+  <MarkdownDocument
+    v-else-if="isMarkdownDocument(resolvedValue)"
+    :value="(resolvedValue as any)"
+    :components="components"
+    :class="class"
+  />
+  <MarkdownDocument
+    v-else
+    :value="parsedDoc ?? { nodes: [], frontmatter: {}, meta: {} }"
+    :components="components"
+    :class="class"
+  />
+</template>

package/dist/runtime/app/components/FileUpload.vue

@@ -0,0 +1,196 @@
+<script lang="ts" setup>
+import { ref, computed } from "vue"
+import { useUpload, type UploadedFile } from "../composables/storage"
+
+/**
+ * `<FileUpload>` — Drag-and-drop file upload dropzone with progress and v-model support.
+ * Supports custom slot for full UI control or uses a built-in dropzone UI.
+ */
+const props = withDefaults(defineProps<{
+  /** File types accepted (e.g. "image/*", ".pdf,.docx"). */
+  accept?: string
+  /** Allow multiple file selection. */
+  multiple?: boolean
+  /** Maximum file size allowed in bytes. */
+  maxSize?: number
+  /** Whether the dropzone is disabled. */
+  disabled?: boolean
+  /** Automatically trigger upload immediately on file selection. */
+  autoUpload?: boolean
+  /** Uploaded file(s) v-model. */
+  modelValue?: UploadedFile | UploadedFile[] | null
+  /** Use presigned direct-to-R2 upload ticket. */
+  presigned?: boolean
+  /** Additional CSS class for the wrapper container. */
+  dropzoneClass?: string
+}>(), {
+  multiple: false,
+  disabled: false,
+  autoUpload: true,
+  modelValue: null,
+  presigned: false,
+  dropzoneClass: "",
+})
+
+const emit = defineEmits<{
+  "update:modelValue": [value: UploadedFile | UploadedFile[] | null]
+  change: [files: File | File[]]
+  upload: [files: File[]]
+  success: [result: UploadedFile | UploadedFile[]]
+  error: [err: Error]
+  progress: [percent: number]
+}>()
+
+const inputRef = ref<HTMLInputElement | null>(null)
+const isDragging = ref(false)
+const clientError = ref<string | null>(null)
+
+const { isUploading, progress, error, upload, uploadMultiple, reset } = useUpload()
+
+function open() {
+  if (props.disabled || isUploading.value) return
+  inputRef.value?.click()
+}
+
+function clear() {
+  reset()
+  clientError.value = null
+  if (inputRef.value) inputRef.value.value = ""
+  emit("update:modelValue", props.multiple ? [] : null)
+}
+
+async function processFiles(files: FileList | File[]) {
+  clientError.value = null
+  const fileList = Array.from(files)
+  if (fileList.length === 0) return
+
+  if (props.maxSize) {
+    const oversized = fileList.find((f) => f.size > props.maxSize!)
+    if (oversized) {
+      const maxMb = (props.maxSize / (1024 * 1024)).toFixed(1)
+      const msg = `File "${oversized.name}" exceeds maximum size of ${maxMb}MB`
+      clientError.value = msg
+      emit("error", new Error(msg))
+      return
+    }
+  }
+
+  emit("change", props.multiple ? fileList : fileList[0]!)
+  if (!props.autoUpload) return
+  emit("upload", fileList)
+
+  try {
+    if (props.multiple) {
+      const results = await uploadMultiple(fileList)
+      emit("update:modelValue", results)
+      emit("success", results)
+    } else {
+      const result = await upload(fileList[0]!, { presigned: props.presigned })
+      emit("update:modelValue", result)
+      emit("success", result)
+    }
+  } catch (err: any) {
+    clientError.value = err?.message || "Upload failed"
+    emit("error", err)
+  }
+}
+
+function onDrop(event: DragEvent) {
+  event.preventDefault()
+  isDragging.value = false
+  if (props.disabled || isUploading.value) return
+  if (event.dataTransfer?.files) processFiles(event.dataTransfer.files)
+}
+
+function onDragOver(event: DragEvent) {
+  event.preventDefault()
+  if (!props.disabled && !isUploading.value) isDragging.value = true
+}
+
+function onDragLeave(event: DragEvent) {
+  event.preventDefault()
+  isDragging.value = false
+}
+
+function onInputChange(event: Event) {
+  const target = event.target as HTMLInputElement
+  if (target.files) processFiles(target.files)
+}
+
+const displayError = computed(() => clientError.value || error.value?.message || null)
+</script>
+
+<template>
+  <!-- Custom slot: users take full UI control -->
+  <div
+    v-if="$slots.default"
+    :class="['qarpeo-file-upload', dropzoneClass]"
+    @drop="onDrop"
+    @dragover="onDragOver"
+    @dragleave="onDragLeave"
+  >
+    <input
+      ref="inputRef"
+      type="file"
+      :accept="accept"
+      :multiple="multiple"
+      class="hidden"
+      @change="onInputChange"
+    />
+    <slot
+      :is-dragging="isDragging"
+      :is-uploading="isUploading"
+      :progress="progress"
+      :error="displayError"
+      :open="open"
+      :clear="clear"
+    />
+  </div>
+
+  <!-- Built-in dropzone UI -->
+  <div
+    v-else
+    class="qarpeo-file-upload-wrapper"
+    @drop="onDrop"
+    @dragover="onDragOver"
+    @dragleave="onDragLeave"
+  >
+    <input
+      ref="inputRef"
+      type="file"
+      :accept="accept"
+      :multiple="multiple"
+      class="hidden"
+      @change="onInputChange"
+    />
+    <div
+      :class="[
+        'rounded-lg border-2 border-dashed p-6 text-center transition-colors duration-200',
+        isDragging
+          ? 'border-primary-500 bg-primary-50/50 dark:bg-primary-950/20'
+          : 'border-gray-300 dark:border-gray-700',
+        disabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer',
+        dropzoneClass,
+      ]"
+      @click="open"
+    >
+      <!-- Uploading state -->
+      <div v-if="isUploading" class="space-y-2">
+        <p class="text-sm text-gray-500">Uploading... {{ progress }}%</p>
+        <UProgress :value="progress" size="xs" />
+      </div>
+
+      <!-- Idle / drag state -->
+      <div v-else class="space-y-1">
+        <UIcon name="i-lucide-upload-cloud" class="size-8 mx-auto text-gray-400" />
+        <p class="text-sm font-medium text-gray-700 dark:text-gray-300">
+          {{ isDragging ? "Drop files to upload" : "Click or drag files here to upload" }}
+        </p>
+        <p v-if="accept" class="text-xs text-gray-400">Accepted: {{ accept }}</p>
+      </div>
+
+      <!-- Error -->
+      <p v-if="displayError" class="mt-2 text-xs text-red-500">{{ displayError }}</p>
+    </div>
+  </div>
+</template>

package/dist/runtime/app/components/ImpersonationBanner.vue

@@ -0,0 +1,57 @@
+<script lang="ts" setup>
+import { computed } from "vue"
+import { useUserSession } from "#imports"
+import type { QarpeoUser, QarpeoSession } from "../../types/auth"
+
+/**
+ * `<ImpersonationBanner>` Renders a dismissible banner when an admin is actively impersonating a
+ * user. Shows who is being impersonated and provides a "Stop Impersonating" button.
+ * Auto-hides when not in an impersonation session.
+ * @emits stopped — when impersonation is stopped successfully
+ */
+const emit = defineEmits<{ stopped: [] }>()
+
+const { session, fetch: refreshSession } = useUserSession()
+
+const isImpersonating = computed(() => Boolean((session.value as QarpeoSession | null)?.impersonator))
+const impersonator = computed<QarpeoUser | null>(
+  () => ((session.value as QarpeoSession | null)?.impersonator as QarpeoUser) || null,
+)
+const impersonated = computed<QarpeoUser | null>(() => {
+  if (!isImpersonating.value) return null
+  return ((session.value as QarpeoSession | null)?.user as QarpeoUser) || null
+})
+
+async function stopImpersonating() {
+  try {
+    await $fetch("/api/auth/impersonate/stop", { method: "POST", credentials: "include" })
+    await refreshSession()
+    emit("stopped")
+  } catch {}
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      v-if="isImpersonating"
+      class="fixed top-0 left-0 right-0 z-[9999] flex items-center justify-between gap-4 bg-amber-700 text-white px-4 py-2 text-sm font-sans"
+    >
+      <span>
+        ⚠ Admin
+        <strong>{{ impersonator?.email || impersonator?.name || "Unknown" }}</strong>
+        is impersonating
+        <strong>{{ impersonated?.email || impersonated?.name || "Unknown" }}</strong>
+      </span>
+      <UButton
+        color="neutral"
+        variant="outline"
+        size="xs"
+        class="border-white/50 text-white hover:bg-white/20"
+        @click="stopImpersonating"
+      >
+        Stop Impersonating
+      </UButton>
+    </div>
+  </Teleport>
+</template>

package/dist/runtime/app/components/SignedIn.vue

@@ -0,0 +1,13 @@
+<script lang="ts" setup>
+import { useAuth } from "../composables/auth"
+const { loggedIn, ready } = useAuth()
+</script>
+
+<template>
+  <template v-if="ready && loggedIn">
+    <slot />
+  </template>
+  <template v-else-if="!ready">
+    <slot name="fallback" />
+  </template>
+</template>

package/dist/runtime/app/components/SignedOut.vue

@@ -0,0 +1,13 @@
+<script lang="ts" setup>
+import { useAuth } from "../composables/auth"
+const { loggedIn, ready } = useAuth()
+</script>
+
+<template>
+  <template v-if="ready && !loggedIn">
+    <slot />
+  </template>
+  <template v-else-if="!ready">
+    <slot name="fallback" />
+  </template>
+</template>

package/dist/runtime/app/components/shiki.css

@@ -0,0 +1,34 @@
+/* Shiki dark mode styles. A colour swatch keeps the background and contrast
+   foreground the transformer wrote, inline with Comark or as a generated
+   class with the content pipeline. */
+html.dark .shiki span[style*="--shiki-dark"]:not(.shiki-color-highlight) {
+  color: var(--shiki-dark) !important;
+  font-style: var(--shiki-dark-font-style) !important;
+  font-weight: var(--shiki-dark-font-weight) !important;
+  text-decoration: var(--shiki-dark-text-decoration) !important;
+}
+
+/* Shiki icon highlight transformer styles */
+.shiki-icon-highlight {
+  display: inline-block;
+  width: 1.25em;
+  height: 1.25em;
+  vertical-align: -0.25em;
+  margin-right: 0.125em;
+  background-color: var(--ui-text-highlighted);
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-size: 100% 100%;
+  mask-size: 100% 100%;
+  -webkit-mask-image: var(--shiki-icon-url);
+  mask-image: var(--shiki-icon-url);
+}
+
+/* Container background styling for dark & light mode */
+html.dark pre.shiki {
+  background-color: #0f172a !important;
+}
+
+html:not(.dark) pre.shiki {
+  background-color: #f8fafc !important;
+}

package/dist/runtime/app/composables/analytics.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @file Composables/analytics.ts Client-side analytics dashboard composable. Fetches data from the
+ *   Qarpeo analytics API routes registered by `analytics: true`.
+ * @example
+ *   ;```vue
+ *   <script setup>
+ *   const { summary, pageviews, loading } = useAnalyticsDashboard()
+ *   await fetchSummary('7d')
+ *   </script>
+ *   ```
+ */
+import type { AnalyticsRange } from "../../../types";
+/**
+ * Reactive analytics dashboard composable. Uses the built-in Qarpeo analytics API routes.
+ *
+ * @param basePath API prefix (default: '/api/analytics')
+ */
+export declare function useAnalyticsDashboard(basePath?: string): {
+    /** Whether a fetch is in flight. */
+    loading: Readonly<import("vue").Ref<boolean, boolean>>;
+    /** Last error, if any. */
+    error: Readonly<import("vue").Ref<Error | null, Error | null>>;
+    /** KPI summary data. */
+    summary: Readonly<import("vue").Ref<{
+        readonly pageviews: number;
+        readonly visitors: number;
+        readonly topPages: readonly {
+            readonly path: string;
+            readonly views: number;
+        }[];
+        readonly topReferrers: readonly {
+            readonly referrer: string;
+            readonly count: number;
+        }[];
+        readonly countries: readonly {
+            readonly country: string;
+            readonly count: number;
+        }[];
+        readonly devices: {
+            readonly mobile: number;
+            readonly desktop: number;
+            readonly bot: number;
+        };
+    } | null, {
+        readonly pageviews: number;
+        readonly visitors: number;
+        readonly topPages: readonly {
+            readonly path: string;
+            readonly views: number;
+        }[];
+        readonly topReferrers: readonly {
+            readonly referrer: string;
+            readonly count: number;
+        }[];
+        readonly countries: readonly {
+            readonly country: string;
+            readonly count: number;
+        }[];
+        readonly devices: {
+            readonly mobile: number;
+            readonly desktop: number;
+            readonly bot: number;
+        };
+    } | null>>;
+    /** Pageview time-series data. */
+    pageviews: Readonly<import("vue").Ref<{
+        readonly total: number;
+        readonly series: readonly {
+            readonly date: string;
+            readonly count: number;
+        }[];
+    } | null, {
+        readonly total: number;
+        readonly series: readonly {
+            readonly date: string;
+            readonly count: number;
+        }[];
+    } | null>>;
+    /** Custom event records. */
+    events: Readonly<import("vue").Ref<readonly {
+        readonly name: string;
+        readonly count: number;
+        readonly lastSeen: string;
+    }[], readonly {
+        readonly name: string;
+        readonly count: number;
+        readonly lastSeen: string;
+    }[]>>;
+    /** Fetch the KPI summary. */
+    fetchSummary: (range?: AnalyticsRange) => Promise<{
+        pageviews: number;
+        visitors: number;
+        topPages: {
+            path: string;
+            views: number;
+        }[];
+        topReferrers: {
+            referrer: string;
+            count: number;
+        }[];
+        countries: {
+            country: string;
+            count: number;
+        }[];
+        devices: {
+            mobile: number;
+            desktop: number;
+            bot: number;
+        };
+    } | null>;
+    /** Fetch pageview time-series. */
+    fetchPageviews: (range?: AnalyticsRange) => Promise<{
+        total: number;
+        series: {
+            date: string;
+            count: number;
+        }[];
+    } | null>;
+    /** Fetch custom events. */
+    fetchEvents: (range?: AnalyticsRange, name?: string, limit?: number) => Promise<{
+        name: string;
+        count: number;
+        lastSeen: string;
+    }[]>;
+};