@stacksjs/defaults 0.70.206 → 0.70.208

package/views/dashboard/components/index.stx

@@ -0,0 +1,330 @@
+@extends('layouts/default')
+
+@section('content')
+@title('Dashboard - Components')
+<div class="py-4 lg:py-8 min-h-screen dark:bg-neutral-800">
+  <div class="mb-8 px-4 sm:px-6 lg:px-8">
+    <div>
+      <h3 class="font-semibold leading-6 text-base text-gray-900 dark:text-neutral-100">Last 30 days</h3>
+
+      <dl class="grid gap-5 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 mt-5">
+        <div class="overflow-hidden relative pt-5 px-4 sm:pt-6 sm:px-6 bg-white dark:bg-neutral-700 rounded-lg shadow">
+          <dt>
+            <div class="absolute p-3 bg-blue-500 rounded-md">
+              <div class="h-6 w-6 text-white i-hugeicons-cloud-download"></div>
+            </div>
+            <p class="ml-16 font-medium text-gray-500 text-sm truncate dark:text-neutral-400">Total Downloads</p>
+          </dt>
+          <dd class="flex items-baseline ml-16 pb-6 sm:pb-7">
+            <p class="font-semibold text-2xl text-gray-900 dark:text-neutral-100">71,897</p>
+            <p class="flex items-baseline ml-2 font-semibold text-green-600 text-sm dark:text-green-400">
+              <svg class="flex-shrink-0 self-center h-5 w-5 text-green-500 dark:text-green-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+                <path fill-rule="evenodd" d="M10 17a.75.75 0 01-.75-.75V5.612L5.29 9.77a.75.75 0 01-1.08-1.04l5.25-5.5a.75.75 0 011.08 0l5.25 5.5a.75.75 0 11-1.08 1.04l-3.96-4.158V16.25A.75.75 0 0110 17z" clip-rule="evenodd" />
+              </svg>
+              <span class="sr-only"> Increased by </span>
+              122
+            </p>
+          </dd>
+        </div>
+
+        <div class="overflow-hidden relative pt-5 px-4 sm:pt-6 sm:px-6 bg-white dark:bg-neutral-700 rounded-lg shadow">
+          <dt>
+            <div class="absolute p-3 bg-blue-500 rounded-md">
+              <div class="h-6 w-6 text-white i-hugeicons-clock-01"></div>
+            </div>
+            <p class="ml-16 font-medium text-gray-500 text-sm truncate dark:text-neutral-400">Avg. Release Time</p>
+          </dt>
+          <dd class="flex items-baseline ml-16 pb-6 sm:pb-7">
+            <p class="font-semibold text-2xl text-gray-900 dark:text-neutral-100">3.65 mins</p>
+            <p class="flex items-baseline ml-2 font-semibold text-green-600 text-sm dark:text-green-400">
+              <svg class="flex-shrink-0 self-center h-5 w-5 text-green-500 dark:text-green-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+                <path fill-rule="evenodd" d="M10 17a.75.75 0 01-.75-.75V5.612L5.29 9.77a.75.75 0 01-1.08-1.04l5.25-5.5a.75.75 0 011.08 0l5.25 5.5a.75.75 0 11-1.08 1.04l-3.96-4.158V16.25A.75.75 0 0110 17z" clip-rule="evenodd" />
+              </svg>
+              <span class="sr-only"> Increased by </span>
+              12 s
+            </p>
+          </dd>
+        </div>
+
+        <div class="overflow-hidden relative pt-5 px-4 sm:pt-6 sm:px-6 bg-white dark:bg-neutral-700 rounded-lg shadow">
+          <dt>
+            <div class="absolute p-3 bg-blue-500 rounded-md">
+              <div class="h-6 w-6 text-white i-hugeicons-rocket-01"></div>
+            </div>
+            <p class="ml-16 font-medium text-gray-500 text-sm truncate dark:text-neutral-400">Releases</p>
+          </dt>
+          <dd class="flex items-baseline ml-16 pb-6 sm:pb-7">
+            <p class="font-semibold text-2xl text-gray-900 dark:text-neutral-100">420</p>
+            <p class="flex items-baseline ml-2 font-semibold text-red-600 text-sm dark:text-red-400">
+              <svg class="flex-shrink-0 self-center h-5 w-5 text-red-500 dark:text-red-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+                <path fill-rule="evenodd" d="M10 3a.75.75 0 01.75.75v10.638l3.96-4.158a.75.75 0 111.08 1.04l-5.25 5.5a.75.75 0 01-1.08 0l-5.25-5.5a.75.75 0 111.08-1.04l3.96 4.158V3.75A.75.75 0 0110 3z" clip-rule="evenodd" />
+              </svg>
+              <span class="sr-only"> Decreased by </span>
+              3.2%
+            </p>
+          </dd>
+        </div>
+      </dl>
+    </div>
+  </div>
+
+  <div class="mb-8 px-4 sm:px-6 lg:px-8">
+    <div class="bg-white dark:bg-neutral-700 rounded-lg shadow">
+      <div class="p-6">
+        <div class="flex items-center justify-between mb-6">
+          <div>
+            <h3 class="font-medium text-base text-gray-900 dark:text-neutral-100">Download Activity</h3>
+            <p class="mt-1 text-gray-500 text-sm dark:text-neutral-400">Compare package downloads over time</p>
+          </div>
+          <div class="flex items-center space-x-4">
+            <div class="flex items-center space-x-2">
+              <input x-model="comparePackage" type="text" placeholder="Compare with package..." @keyup.enter="handleCompare()" class="block py-1.5 w-64 text-gray-900 sm:leading-6 sm:text-sm dark:text-neutral-100 placeholder:text-gray-400 dark:bg-neutral-600 border-0 ring-1 ring-gray-300 ring-inset rounded-md dark:ring-neutral-600 focus:ring-2 focus:ring-blue-600 focus:ring-inset shadow-sm" />
+              <button @click="handleCompare()" class="px-3 py-2 font-semibold text-sm text-white bg-blue-600 hover:bg-blue-500 rounded-md focus-visible:outline focus-visible:outline-2 focus-visible:outline-blue-600 focus-visible:outline-offset-2 shadow-sm">Compare</button>
+            </div>
+            <select x-model="timeRange" @change="onTimeRangeChange()" class="pl-3 pr-8 py-1.5 text-gray-900 text-sm dark:text-neutral-100 bg-gray-50 dark:bg-neutral-600 border-0 ring-1 ring-gray-300 ring-inset rounded-md dark:ring-neutral-600 focus:ring-2 focus:ring-blue-600">
+              <option value="7">Last 7 days</option>
+              <option value="30">Last 30 days</option>
+              <option value="90">Last 90 days</option>
+              <option value="365">Last year</option>
+            </select>
+          </div>
+        </div>
+        <div class="h-[400px]">
+          <canvas id="components_downloads_chart"></canvas>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <div class="pt-12 px-4 sm:px-6 lg:px-8">
+    <div class="sm:flex sm:items-center">
+      <div class="sm:flex-auto">
+        <h1 class="font-semibold leading-6 text-base text-gray-900 dark:text-neutral-100">Components</h1>
+        <p class="mt-2 text-gray-700 text-sm dark:text-neutral-300">A list of all the components in your library.</p>
+      </div>
+
+      <div class="sm:flex-none mt-4 sm:ml-16 sm:mt-0">
+        <button type="button" class="px-3 py-2 font-semibold text-sm text-white bg-blue-600 hover:bg-blue-500 rounded-md focus-visible:outline focus-visible:outline-2 focus-visible:outline-blue-600 focus-visible:outline-offset-2 shadow-sm">Create Component</button>
+      </div>
+    </div>
+
+    <div class="flow-root mt-8">
+      <div class="overflow-x-auto -mx-4 -my-2 sm:-mx-6 lg:-mx-8">
+        <div class="inline-block py-2 sm:px-6 lg:px-8 min-w-full align-middle">
+          <div class="overflow-hidden ring-1 ring-black ring-opacity-5 sm:rounded-lg dark:ring-neutral-600 shadow">
+            <table class="min-w-full divide-gray-300 divide-y dark:divide-neutral-600">
+              <thead class="bg-gray-50 dark:bg-neutral-700">
+                <tr>
+                  <th scope="col" class="pl-4 pr-3 py-3.5 sm:pl-6 font-semibold text-gray-900 text-left text-sm dark:text-neutral-100">Name</th>
+                  <th scope="col" class="px-3 py-3.5 font-semibold text-gray-900 text-left text-sm dark:text-neutral-100">Size</th>
+                  <th scope="col" class="px-3 py-3.5 font-semibold text-gray-900 text-left text-sm dark:text-neutral-100">Path</th>
+                  <th scope="col" class="px-3 py-3.5 font-semibold text-gray-900 text-right text-sm dark:text-neutral-100">Updated At</th>
+                  <th scope="col" class="px-3 py-3.5 font-semibold text-gray-900 text-right text-sm dark:text-neutral-100">Created At</th>
+                  <th scope="col" class="relative pl-3 pr-4 py-3.5 sm:pr-6"><span class="sr-only">Edit</span></th>
+                </tr>
+              </thead>
+
+              <tbody class="bg-white dark:bg-neutral-700 divide-gray-200 divide-y dark:divide-neutral-600">
+                <template :for="component in componentList">
+                  <tr>
+                    <td class="pl-4 pr-3 py-4 sm:pl-6 font-medium text-gray-900 text-sm whitespace-nowrap dark:text-neutral-100">{{ component.name }}</td>
+                    <td class="px-3 py-4 font-mono text-gray-500 text-sm whitespace-nowrap dark:text-neutral-300">{{ component.size }}</td>
+                    <td class="px-3 py-4 font-mono text-gray-500 text-sm whitespace-nowrap dark:text-neutral-300">{{ component.path }}</td>
+                    <td class="px-3 py-4 text-gray-500 text-right text-sm whitespace-nowrap dark:text-neutral-300">{{ component.updated_at }}</td>
+                    <td class="px-3 py-4 text-gray-500 text-right text-sm whitespace-nowrap dark:text-neutral-300">{{ component.created_at }}</td>
+                    <td class="relative pl-3 pr-4 py-4 sm:pr-6 font-medium text-right text-sm whitespace-nowrap">
+                      <a href="#" class="text-blue-600 dark:text-blue-400 hover:text-blue-900 dark:hover:text-blue-300">Edit<span class="sr-only">, {{ component.name }}, in IDE</span></a>
+                    </td>
+                  </tr>
+                </template>
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<script client>
+// Demo component rows — moved out of the former `<script server>` block
+// (stacksjs/stacks#1838). Replace with a real component scan when the
+// API lands.
+const componentList = [
+  { name: 'Component A', size: '30kb', path: './resources/components/component-a.stx', updated_at: '01-03-2023 08:23:15', created_at: '04-19-2022 09:04:20' },
+  { name: 'Component B', size: '30kb', path: './resources/components/component-b.stx', updated_at: '01-03-2023 08:23:15', created_at: '04-19-2022 09:04:20' },
+  { name: 'Component C', size: '30kb', path: './resources/components/component-c.stx', updated_at: '01-03-2023 08:23:15', created_at: '04-19-2022 09:04:20' },
+]
+
+interface DownloadStats {
+  labels: string[]
+  data: number[]
+  compareData: number[]
+}
+
+interface ChartLike { destroy: () => void, update: () => void, data: { labels: string[], datasets: Array<{ label?: string, data: number[], borderColor?: string, backgroundColor?: string, fill?: boolean }> } }
+type ChartCtor = new (canvas: HTMLElement, config: { type: string, data: unknown, options?: unknown }) => ChartLike
+
+function formatDate(daysAgo: number): string {
+  const date = new Date()
+  date.setDate(date.getDate() - daysAgo)
+  return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' })
+}
+
+function generateDateLabels(days: number): string[] {
+  return Array.from({ length: days }, (_, i) => formatDate(i))
+}
+
+const downloadStats = state<Record<string, DownloadStats>>({
+  '7': {
+    labels: generateDateLabels(7),
+    data: [12500, 15800, 14200, 16800, 19200, 18100, 17200],
+    compareData: [9500, 11800, 10200, 12800, 15200, 14100, 13200],
+  },
+  '30': {
+    labels: generateDateLabels(30),
+    data: Array.from({ length: 30 }, () => Math.floor(Math.random() * 20000) + 10000),
+    compareData: Array.from({ length: 30 }, () => Math.floor(Math.random() * 15000) + 8000),
+  },
+  '90': {
+    labels: generateDateLabels(90),
+    data: Array.from({ length: 90 }, () => Math.floor(Math.random() * 20000) + 10000),
+    compareData: Array.from({ length: 90 }, () => Math.floor(Math.random() * 15000) + 8000),
+  },
+  '365': {
+    labels: generateDateLabels(365),
+    data: Array.from({ length: 365 }, () => Math.floor(Math.random() * 20000) + 10000),
+    compareData: Array.from({ length: 365 }, () => Math.floor(Math.random() * 15000) + 8000),
+  },
+})
+
+const comparePackage = state('')
+const timeRange = state('7')
+const isLoading = state(false)
+const fetchError = state('')
+
+let chartHandle: ChartLike | null = null
+
+function downloadsData() {
+  const range = downloadStats()[timeRange()]
+  if (!range)
+    return { labels: [], datasets: [] }
+  const datasets: Array<{ label?: string, data: number[], borderColor?: string, backgroundColor?: string, fill?: boolean }> = [
+    { label: '@your/package', data: range.data, borderColor: 'rgb(59, 130, 246)', backgroundColor: 'rgba(59, 130, 246, 0.1)', fill: true },
+  ]
+  if (comparePackage()) {
+    datasets.push({ label: comparePackage(), data: range.compareData, borderColor: 'rgb(234, 179, 8)', backgroundColor: 'rgba(234, 179, 8, 0.1)', fill: true })
+  }
+  return { labels: range.labels, datasets }
+}
+
+const chartOptions = {
+  responsive: true,
+  maintainAspectRatio: false,
+  scales: {
+    y: {
+      beginAtZero: true,
+      grid: { color: 'rgba(200, 200, 200, 0.1)' },
+      ticks: {
+        color: 'rgb(156, 163, 175)',
+        font: { family: "'JetBrains Mono', monospace" },
+        callback: (value: number | string) => {
+          const v = Number(value)
+          if (v >= 1000000)
+            return `${(v / 1000000).toFixed(1)}M`
+          if (v >= 1000)
+            return `${(v / 1000).toFixed(1)}k`
+          return v
+        },
+      },
+    },
+    x: { grid: { display: false }, ticks: { color: 'rgb(156, 163, 175)', font: { family: "'JetBrains Mono', monospace" } } },
+  },
+  plugins: {
+    legend: { display: true, position: 'top', align: 'end', labels: { color: 'rgb(156, 163, 175)', font: { family: "'JetBrains Mono', monospace" }, boxWidth: 12, padding: 15 } },
+    tooltip: {
+      callbacks: {
+        label: (context: { dataset: { label?: string }, parsed: { y: number | null } }) => {
+          let label = context.dataset.label || ''
+          if (label)
+            label += ': '
+          if (context.parsed.y !== null) {
+            const v = context.parsed.y
+            if (v >= 1000000)
+              label += `${(v / 1000000).toFixed(1)}M`
+            else if (v >= 1000)
+              label += `${(v / 1000).toFixed(1)}k`
+            else label += v
+          }
+          return `${label} downloads`
+        },
+      },
+    },
+  },
+  elements: { line: { tension: 0.4 } },
+}
+
+async function fetchDownloadData(days: string): Promise<void> {
+  isLoading.set(true)
+  fetchError.set('')
+  try {
+    const baseUrl = `http://localhost:${(globalThis as { process?: { env?: { PORT_API?: string } } }).process?.env?.PORT_API || '3008'}`
+    const response = await fetch(`${baseUrl}/components/stats?days=${days}`, {
+      headers: { Accept: 'application/json' },
+    })
+    if (response.ok) {
+      const data = await response.json()
+      if (data.stats) {
+        const next = { ...downloadStats() }
+        next[timeRange()] = data.stats
+        downloadStats.set(next)
+      }
+    }
+  }
+  catch (error) {
+    fetchError.set('Failed to load component data. Using cached data.')
+    // eslint-disable-next-line no-console
+    console.error('Failed to fetch component data:', error)
+  }
+  finally {
+    isLoading.set(false)
+  }
+}
+
+function refreshChart(): void {
+  if (!chartHandle)
+    return
+  const next = downloadsData()
+  chartHandle.data.labels = next.labels
+  chartHandle.data.datasets = next.datasets
+  chartHandle.update()
+}
+
+async function onTimeRangeChange(): Promise<void> {
+  await fetchDownloadData(timeRange())
+  refreshChart()
+}
+
+async function handleCompare(): Promise<void> {
+  if (comparePackage()) {
+    await fetchDownloadData(timeRange())
+    refreshChart()
+  }
+}
+
+onMount(async () => {
+  await fetchDownloadData(timeRange())
+  const { Chart, registerables } = await import('@stacksjs/charts')
+  Chart.register(...registerables)
+  const Ctor = Chart as unknown as ChartCtor
+  const handle = useChart({ Chart: Ctor, id: 'components_downloads_chart', type: 'line', data: downloadsData(), options: chartOptions })
+  chartHandle = handle.instance as ChartLike | null
+})
+
+onDestroy(() => {
+  chartHandle?.destroy()
+  chartHandle = null
+})
+</script>
+
+@endsection

package/views/dashboard/composables/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Dashboard-local composables.
+ *
+ * Most reactive primitives are auto-imported by stx in `<script client>`
+ * blocks (`state`, `derived`, `effect`, `onMount`, `onDestroy`, `navigate`,
+ * `goBack`, `useColorMode`, `useDark`, `useFetch`, `useEventListener`, …) —
+ * reach for those first. This barrel only ships things stx doesn't.
+ *
+ * See stacksjs/stacks#1838 for the wider sweep this is part of.
+ */
+
+export type { ChartCtor, ChartHandle, ChartLike, UseChartOptions } from './useChart'
+export { useChart, useCharts } from './useChart'
+export type { NavigationSnapshot } from './useNavigation'
+export { useNavigation } from './useNavigation'
+export type { RoleSnapshot } from './useRole'
+export { useRole } from './useRole'
+export type { ThemeMode, ThemeSnapshot } from './useTheme'
+export { isDarkTheme, useTheme } from './useTheme'

package/views/dashboard/composables/useChart.ts

@@ -0,0 +1,77 @@
+/**
+ * useChart — wires `@stacksjs/charts` to a canvas without leaking
+ * `document.getElementById` into pages.
+ *
+ * The dashboard repeats the same shape across feature pages:
+ *
+ *   const ctx = document.getElementById('chart_1')
+ *   if (ctx) new Chart(ctx, { type, data, options })
+ *
+ * `useChart` packages that into one call, returns a destroyer so SPA
+ * navigation can tear charts down, and tolerates SSR (no-ops on the
+ * server). It does *not* import the chart lib eagerly — pages can
+ * still `await import('@stacksjs/charts')` to keep the browser bundle
+ * lazy, then pass the `Chart` constructor in.
+ */
+
+export interface ChartLike {
+  destroy: () => void
+}
+
+// Constructor signature mirrors Chart.js — `new Chart(canvas, config)`.
+// We don't import `@stacksjs/charts` here to keep this composable
+// dep-free at the type level; pages pass the constructor in.
+export type ChartCtor = new (
+  canvas: HTMLCanvasElement | HTMLElement,
+  config: { type: string, data: unknown, options?: unknown },
+) => ChartLike
+
+export interface UseChartOptions {
+  /** Chart constructor (`new Chart(...)`). Pages import lazily and pass it in. */
+  Chart: ChartCtor
+  /** Element id, e.g. `'chart_1'`. */
+  id: string
+  type: string
+  data: unknown
+  options?: unknown
+}
+
+export interface ChartHandle {
+  /** The constructed chart, or `null` if the element was missing or we're SSR. */
+  readonly instance: ChartLike | null
+  destroy: () => void
+}
+
+export function useChart(opts: UseChartOptions): ChartHandle {
+  // SSR-safe — no document means no canvas.
+  if (typeof document === 'undefined')
+    return { instance: null, destroy: () => {} }
+
+  const el = document.getElementById(opts.id)
+  if (!el) {
+    // Canvas not in the DOM yet (or wrong id). Returning a no-op handle
+    // is friendlier than throwing — pages stay rendered, devs see the
+    // missing chart and can grep the id.
+    // eslint-disable-next-line no-console
+    console.warn(`[useChart] no element with id "${opts.id}" — chart not initialised`)
+    return { instance: null, destroy: () => {} }
+  }
+
+  const instance = new opts.Chart(el, { type: opts.type, data: opts.data, options: opts.options })
+  return {
+    instance,
+    destroy: () => instance.destroy(),
+  }
+}
+
+/**
+ * Convenience for the common "init N charts at once" pattern. Returns
+ * a single destroyer that tears them all down.
+ */
+export function useCharts(specs: UseChartOptions[]): { handles: ChartHandle[], destroyAll: () => void } {
+  const handles = specs.map(useChart)
+  return {
+    handles,
+    destroyAll: () => handles.forEach(h => h.destroy()),
+  }
+}

package/views/dashboard/composables/useNavigation.ts

@@ -0,0 +1,99 @@
+/**
+ * useNavigation — wraps `window.location` / `history.pushState` so
+ * dashboard pages can read URL state and navigate without leaking
+ * vanilla DOM access into `.stx` files (stacksjs/stacks#1838).
+ *
+ * stx already exposes a top-level `navigate(url)` for SPA navigation, so
+ * this composable focuses on the *read* side (current path, segment
+ * extraction, query params) and on a couple of write helpers that stx's
+ * primitive doesn't cover (hash setters, opening external URLs).
+ *
+ * All accessors are SSR-safe — they return sensible defaults when
+ * `window` is undefined so importing this in a page that hydrates
+ * server-side doesn't crash.
+ */
+
+export interface NavigationSnapshot {
+  /**
+   * Current pathname, e.g. `/kanban/12`. Empty string on the server.
+   */
+  path: () => string
+
+  /**
+   * Path segment by index, supporting negative indexes (Pythonic). The
+   * pathname is split on `/` with empty segments dropped — so
+   * `urlSegment(-1)` on `/kanban/12/cards` returns `cards`, and
+   * `urlSegment(0)` returns `kanban`. Returns an empty string when the
+   * index is out of bounds or on the server.
+   *
+   * Replaces the recurring `window.location.pathname.split('/').pop()`
+   * pattern from feature pages.
+   */
+  urlSegment: (index: number) => string
+
+  /**
+   * Numeric route parameter — convenience wrapper for the very common
+   * `/feature/[id]` shape. Parses `urlSegment(-1)` as a positive integer
+   * and returns `null` when it isn't one.
+   */
+  urlIdParam: () => number | null
+
+  /**
+   * Query string value, e.g. `urlQuery('q')` on `/search?q=foo` → `foo`.
+   * Returns `null` when the param is absent or on the server.
+   */
+  urlQuery: (name: string) => string | null
+
+  /**
+   * Replace the current URL without a history entry (uses
+   * `history.replaceState`). Useful for tab/state changes that
+   * shouldn't pollute the back button.
+   */
+  replacePath: (next: string) => void
+
+  /**
+   * Open a URL in a new tab. Forwards `noopener,noreferrer` automatically
+   * — pages shouldn't have to remember the security flags every time.
+   */
+  openExternal: (url: string) => void
+}
+
+export function useNavigation(): NavigationSnapshot {
+  return {
+    path: () => {
+      if (typeof window === 'undefined') return ''
+      return window.location.pathname
+    },
+
+    urlSegment: (index: number) => {
+      if (typeof window === 'undefined') return ''
+      const parts = window.location.pathname.split('/').filter(Boolean)
+      if (parts.length === 0) return ''
+      const i = index < 0 ? parts.length + index : index
+      return parts[i] ?? ''
+    },
+
+    urlIdParam: () => {
+      if (typeof window === 'undefined') return null
+      const last = window.location.pathname.split('/').filter(Boolean).pop()
+      if (!last) return null
+      const n = Number(last)
+      return Number.isFinite(n) && n > 0 ? n : null
+    },
+
+    urlQuery: (name: string) => {
+      if (typeof window === 'undefined') return null
+      return new URL(window.location.href).searchParams.get(name)
+    },
+
+    replacePath: (next: string) => {
+      if (typeof window === 'undefined') return
+      window.history.replaceState({}, '', next)
+    },
+
+    openExternal: (url: string) => {
+      if (typeof window === 'undefined') return
+      window.open(url, '_blank', 'noopener,noreferrer')
+    },
+  }
+}

package/views/dashboard/composables/useRole.ts

@@ -0,0 +1,58 @@
+/**
+ * Role-aware visibility hook for dashboard features.
+ *
+ * Backs gating decisions across the dashboard
+ * (stacksjs/stacks#1843, first consumer: CI tracking in #1844).
+ *
+ * Resolution chain (in order):
+ *
+ *   1. **Authenticated user with roles** — Reads the role names returned
+ *      by `/api/dashboard/auth/me` (Action: `Dashboard/Auth/MeAction` →
+ *      `@stacksjs/auth` → `BqbRbacStore` → `user_roles` pivot). Role
+ *      membership is the authoritative answer.
+ *   2. **Authenticated user with no role records** — The user exists but
+ *      has nothing in `user_roles`. Treated as `client` (most restrictive)
+ *      so a brand-new account doesn't accidentally see dev tools before
+ *      an admin assigns a role.
+ *   3. **Unauthenticated** — No bearer token, no session. The dev
+ *      dashboard on localhost lands here. Defaults to `isDev: true` so
+ *      the surface stays usable without forcing anyone to log in against
+ *      a local DB. Production deployments that gate `/api/dashboard/*`
+ *      behind the `auth` middleware never hit this branch — the endpoint
+ *      returns a real user/roles and case (1) applies.
+ *
+ * Consumers should `derived(() => isDev())` so the signal flips
+ * reactively if the user's roles change (admin assigns/revokes via the
+ * RBAC UI without a page reload).
+ */
+import { useStore } from '@stacksjs/stx'
+
+export interface RoleSnapshot {
+  /** Admin: every dashboard surface is visible. */
+  isAdmin: () => boolean
+  /** Dev: infra/dev-mode surfaces (CI tracking, runner alerts, queries). */
+  isDev: () => boolean
+  /** Client: minimal surface — content / orders / billing only. */
+  isClient: () => boolean
+  /** Trigger the identity round-trip. Safe to call repeatedly; the store
+   * dedupes in-flight + cached responses. */
+  load: () => Promise<void>
+  /** Force a re-fetch (e.g. after an admin assigns the viewer a new role). */
+  refresh: () => Promise<void>
+}
+
+export function useRole(): RoleSnapshot {
+  const auth = useStore('auth')
+
+  // Fire the load lazily on first consumer. The store guards against
+  // double-fetch so multiple `useRole()` calls in one page are safe.
+  auth.load()
+
+  return {
+    isAdmin: () => auth.isAdmin(),
+    isDev: () => auth.isDev(),
+    isClient: () => auth.isClient(),
+    load: () => auth.load(),
+    refresh: () => auth.refresh(),
+  }
+}

package/views/dashboard/composables/useTheme.ts

@@ -0,0 +1,74 @@
+/**
+ * useTheme — single owner of the OS dark-mode preference signal
+ * (stacksjs/stacks#1838).
+ *
+ * The original incident: `dashboardStore.isDark` derived its OS
+ * preference by calling `window.matchMedia(...)` *inside the store
+ * factory* — a store that imported window for its own state was one of
+ * the audit's main offenders. This composable lifts that wiring out so
+ * the store consumes a clean signal and pages can ask `useTheme()`
+ * directly without re-reading `matchMedia` per call site.
+ *
+ * Behaviour:
+ *
+ *   - On the server, `prefersDark()` resolves to `false`. The dashboard
+ *     defaults to its light palette during SSR; once the page hydrates
+ *     the listener attaches and `prefersDark()` flips if the OS theme
+ *     is dark, so the first repaint reflects reality.
+ *   - In the browser, the listener is installed once per module load.
+ *     Subsequent `useTheme()` calls reuse the same signal — no
+ *     listener storm.
+ *
+ * Note: stx exposes its own `useDark()` / `useColorMode()` composables
+ * via auto-import. Those are the right primitives for "what theme is
+ * the user currently *viewing*" (which considers user preference +
+ * stored override). `useTheme().prefersDark` is specifically the *OS
+ * preference* — that's what `dashboardStore` resolves against when its
+ * own `theme` setting is `'system'`.
+ */
+import { state } from '@stacksjs/stx'
+
+export type ThemeMode = 'light' | 'dark' | 'system'
+
+export interface ThemeSnapshot {
+  /**
+   * OS-level dark-mode preference. Tracks `prefers-color-scheme: dark`
+   * via a single `matchMedia` listener installed lazily on first import.
+   */
+  prefersDark: () => boolean
+}
+
+const prefersDarkSignal = state(false)
+let installed = false
+
+function install(): void {
+  if (installed) return
+  installed = true
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+    return
+  const mql = window.matchMedia('(prefers-color-scheme: dark)')
+  prefersDarkSignal.set(mql.matches)
+  mql.addEventListener('change', e => prefersDarkSignal.set(e.matches))
+}
+
+// Install at module load. The window guard inside `install()` keeps this
+// safe for SSR — the signal stays at its `false` default until the
+// page hydrates and re-imports the composable in the browser.
+install()
+
+export function useTheme(): ThemeSnapshot {
+  return {
+    prefersDark: () => prefersDarkSignal(),
+  }
+}
+
+/**
+ * Resolve the *effective* dark state given a user theme mode +
+ * the OS preference. Pulled out as a small pure helper so consumers
+ * (e.g. `dashboardStore.isDark`) can compose it without re-deriving
+ * the same `'system' ? prefersDark : mode === 'dark'` ternary.
+ */
+export function isDarkTheme(mode: ThemeMode, prefersDark: boolean): boolean {
+  if (mode === 'system') return prefersDark
+  return mode === 'dark'
+}