@sewadah/selaras-docs 1.3.1 → 1.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,62 @@
1
1
  # Changelog
2
2
 
3
+ ## v1.3.3
4
+
5
+ [compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.3.2...selaras-docs-v1.3.3)
6
+
7
+ ### 🚀 Enhancements
8
+
9
+ - **feat(empty-state):** add reusable empty states and examples ([b915695](https://github.com/sewadahapp/selaras/commit/b915695478d98509ff776a042e9ad676654167bd))
10
+
11
+ ### 🩹 Fixes
12
+
13
+ - **fix(docs):** restore future and nightly Nuxt compatibility ([272260e](https://github.com/sewadahapp/selaras/commit/272260e00416c5780ea32ed8ae54a8ce478d436b))
14
+ - **fix(docs):** preserve content at trailing-slash URLs ([24f55a6](https://github.com/sewadahapp/selaras/commit/24f55a6b8e531e785080f0f54923539672d1da52))
15
+ - **fix(a11y):** correct selection semantics and add browser checks ([3416404](https://github.com/sewadahapp/selaras/commit/34164047bb106bafb676d7cef27d48c02d50ea73))
16
+ - **fix(docs):** restore dot grid pointer interaction ([3f8df1e](https://github.com/sewadahapp/selaras/commit/3f8df1edf911b279308f67f57eadca29dae38556))
17
+ - **fix(release):** add explicit all-package release selection ([8ac0d9b](https://github.com/sewadahapp/selaras/commit/8ac0d9bae9f5692148b0b00657c043625ce77823))
18
+
19
+ ### 📖 Documentation
20
+
21
+ - **docs:** refresh v1 setup guide and package homepage ([f4ad42c](https://github.com/sewadahapp/selaras/commit/f4ad42c91bd3ad294618d35cf89e8c2ec77dc2ab))
22
+
23
+ ### 🤖 Other changes
24
+
25
+ - **test(compat):** add Nuxt 5 checks and docs compatibility fixes ([9f6ca01](https://github.com/sewadahapp/selaras/commit/9f6ca0125786cfa20ba8b3235636a9b588b4e997))
26
+
27
+ Published against `@sewadah/selaras` ^1.1.0.
28
+
29
+ ## v1.3.2
30
+
31
+ [compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.3.1...selaras-docs-v1.3.2)
32
+
33
+ ### 🚀 Enhancements
34
+
35
+ - **feat(docs):** add templates catalogue and navigation ([3973c61](https://github.com/sewadahapp/selaras/commit/3973c610c3f6bbdc998ba189d15001c37382ddf4))
36
+ - **feat(docs):** redesign the homepage around four theming edits ([a9e508d](https://github.com/sewadahapp/selaras/commit/a9e508d9b0ab99271a2caaa3ec6cf805515ec35c))
37
+ - **feat(agent)!:** move the MCP server into @sewadah/selaras-mcp ([d4f8848](https://github.com/sewadahapp/selaras/commit/d4f88485a0841210b5d3f16a514b18193de4bfe5))
38
+
39
+ ### 🩹 Fixes
40
+
41
+ - **fix(docs):** recover stale tabs after deployment ([c7f7bdc](https://github.com/sewadahapp/selaras/commit/c7f7bdc62df3c161cf300c815289bbce6e42dee4))
42
+ - **fix(select):** preserve search height with overflowing options ([4a71179](https://github.com/sewadahapp/selaras/commit/4a7117995fc1fd46f30ac883720274cee33f4fa0))
43
+ - **fix(release):** stage changelogs only for selected packages ([ec0f11c](https://github.com/sewadahapp/selaras/commit/ec0f11cae742122a5645414a5be58d2ac902f3dd))
44
+
45
+ ### 📖 Documentation
46
+
47
+ - **docs:** describe Selaras as a Nuxt component library ([4869b74](https://github.com/sewadahapp/selaras/commit/4869b74572284fa5e40625bb0e195a8f5b474818))
48
+
49
+ ### 🤖 Other changes
50
+
51
+ - **test(agent):** resolve the packed server's dependencies from its own workspace ([4678a1d](https://github.com/sewadahapp/selaras/commit/4678a1d7106ab808c96051c8e29d7f87a13141b7))
52
+ - **chore:** stop tracking local design-tool context ([560713f](https://github.com/sewadahapp/selaras/commit/560713f4562903f2ebc952c228f3ba2d4659f0f0))
53
+ - **build(deps):** bump vitest to v5 and happy-dom to v21 ([ebae6e2](https://github.com/sewadahapp/selaras/commit/ebae6e2d7db6785f53e092d63d17273d3b52f49c))
54
+ - **build(deps):** bump dev tooling within current majors ([17bdd8b](https://github.com/sewadahapp/selaras/commit/17bdd8bb6322a19edbc11f9188b73c3b00eef4ef))
55
+ - **build(deps):** bump runtime dependencies and raise their minimums ([1a3b889](https://github.com/sewadahapp/selaras/commit/1a3b8891d2be0140dd16c81a0e9ef19361f6c35d))
56
+ - **build(deps):** bump @nuxt/icon to v2 ([5076bed](https://github.com/sewadahapp/selaras/commit/5076bed7048f69e8cdd372173d0aaee3ebd14b86))
57
+
58
+ Published against `@sewadah/selaras` ^1.0.0.
59
+
3
60
  ## v1.3.1
4
61
 
5
62
  [compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.3.0...selaras-docs-v1.3.1)
package/README.md CHANGED
@@ -37,6 +37,31 @@ need an app root, Content config, or stylesheet for the default setup.
37
37
  `nuxt` remains a peer because the documentation site is a Nuxt application;
38
38
  the layer is normally a development dependency, just like Nuxt itself.
39
39
 
40
+ ## Framework compatibility
41
+
42
+ The supported Nuxt range is declared in the package's peer dependencies.
43
+ CI also tests Nuxt 4 with `future.compatibilityVersion: 5` and Nuxt 5 nightly.
44
+ The nightly checks are informational until Nuxt 5 is released.
45
+
46
+ The layer enables server auto-imports required by Nuxt Content 3. On the
47
+ client, it supplies Content's global `$fetch` from Nuxt's configured fetch
48
+ client when that global is missing, preserving an existing implementation.
49
+ Consumers do not need to configure either compatibility setting themselves.
50
+
51
+ ## Updates after deployment
52
+
53
+ In production, the layer checks Nuxt's latest build manifest before navigation
54
+ and when a tab becomes visible again. A confirmed build change reloads the page
55
+ at the requested URL. Missing content also triggers a fresh build check before
56
+ becoming a 404. Offline or failed checks keep the existing page available;
57
+ checks for an unchanged build do not reload it. This uses Nuxt's app manifest
58
+ and is disabled when `experimental.appManifest` is false.
59
+
60
+ Serve HTML with `Cache-Control: no-cache` so reloads revalidate it, and avoid
61
+ caching `/_nuxt/builds/latest.json` as immutable. On static hosts, configure
62
+ these headers through the hosting provider or CDN. Hashed JavaScript and CSS
63
+ can keep their normal asset caching.
64
+
40
65
  ## Customization
41
66
 
42
67
  Use `app.config.ts` for site identity and the default shell:
package/app/app.config.ts CHANGED
@@ -1,4 +1,7 @@
1
- export default defineAppConfig({
1
+ import type { SelarasDocsAppConfig } from '../types'
2
+
3
+ // Server-side content tooling also evaluates this config without app auto-imports.
4
+ export default {
2
5
  selarasDocs: {
3
6
  site: {
4
7
  name: 'Documentation',
@@ -39,4 +42,4 @@ export default defineAppConfig({
39
42
  ],
40
43
  },
41
44
  },
42
- })
45
+ } satisfies { selarasDocs: SelarasDocsAppConfig }
@@ -278,10 +278,6 @@
278
278
  display: none;
279
279
  }
280
280
 
281
- .selaras-docs-nav-toggle {
282
- display: none;
283
- }
284
-
285
281
  /* Reserve the sidebar's width for the brand, so the header menu's first
286
282
  label lines up with the page content: sidebar (16rem) + the content's
287
283
  inset from it (4rem), less the header's own padding (1.5rem), the
@@ -295,6 +291,12 @@
295
291
  }
296
292
  }
297
293
 
294
+ @media (min-width: 80rem) {
295
+ .selaras-docs-nav-toggle {
296
+ display: none;
297
+ }
298
+ }
299
+
298
300
  @media (max-width: 63.999rem) {
299
301
  .selaras-docs-main {
300
302
  padding: 1.5rem;
@@ -2,6 +2,7 @@
2
2
  import type { SelarasDocsErrorKind } from '../../types'
3
3
  import { useTemplateRef, watch } from 'vue'
4
4
  import { useRouter } from '#app'
5
+ import { isDocsNotFound } from '../utils/error-status'
5
6
 
6
7
  const props = withDefaults(defineProps<{
7
8
  kind?: Extract<SelarasDocsErrorKind, 'page' | 'example'>
@@ -11,17 +12,13 @@ const props = withDefaults(defineProps<{
11
12
  const boundary = useTemplateRef('boundary')
12
13
  const router = useRouter()
13
14
  watch([() => router.currentRoute.value.fullPath, () => props.resetKey], () => boundary.value?.clearError())
14
-
15
- function isMissing(error: Error) {
16
- return 'statusCode' in error && error.statusCode === 404
17
- }
18
15
  </script>
19
16
 
20
17
  <template>
21
18
  <NuxtErrorBoundary ref="boundary">
22
19
  <slot />
23
20
  <template #error="{ error, clearError }">
24
- <DocsErrorState :kind="kind === 'page' && isMissing(error) ? 'notFound' : kind" @retry="clearError" />
21
+ <DocsErrorState :kind="kind === 'page' && isDocsNotFound(error) ? 'notFound' : kind" @retry="clearError" />
25
22
  </template>
26
23
  </NuxtErrorBoundary>
27
24
  </template>
@@ -1,11 +1,12 @@
1
1
  <script setup lang="ts">
2
2
  import type { NuxtError } from '#app'
3
+ import { isDocsNotFound } from '../utils/error-status'
3
4
 
4
5
  const props = defineProps<{ error: NuxtError }>()
5
6
  const config = useRuntimeConfig()
6
7
  const appConfig = useAppConfig()
7
8
  const siteName = computed(() => appConfig.selarasDocs?.site?.name ?? 'Documentation')
8
- const missing = computed(() => props.error.statusCode === 404)
9
+ const missing = computed(() => isDocsNotFound(props.error))
9
10
  const pending = ref(false)
10
11
 
11
12
  useSeoMeta({
@@ -9,6 +9,7 @@ const siteName = computed(() => docsConfig.value.header?.title ?? docsConfig.val
9
9
  const headerLinks = computed(() => docsConfig.value.header?.links ?? [])
10
10
  const repositoryUrl = computed(() => docsConfig.value.repository?.url)
11
11
  const sidebarEnabled = computed(() => docsConfig.value.sidebar?.enabled !== false)
12
+ const mobileNavigationEnabled = computed(() => sidebarEnabled.value || headerLinks.value.length > 0)
12
13
 
13
14
  watch(() => route.path, () => {
14
15
  navigationOpen.value = false
@@ -32,7 +33,7 @@ watch(() => route.path, () => {
32
33
  v-if="headerLinks.length"
33
34
  :items="headerLinks"
34
35
  variant="link"
35
- :ui="{ root: 'hidden w-auto lg:flex' }"
36
+ :ui="{ root: 'hidden w-auto xl:flex' }"
36
37
  />
37
38
  <div class="selaras-docs-header-actions">
38
39
  <DocsSearchButton v-if="docsConfig.header?.search !== false" />
@@ -51,7 +52,7 @@ watch(() => route.path, () => {
51
52
  color="neutral"
52
53
  />
53
54
  <SButton
54
- v-if="sidebarEnabled"
55
+ v-if="mobileNavigationEnabled"
55
56
  variant="ghost"
56
57
  color="neutral"
57
58
  class="selaras-docs-nav-toggle"
@@ -62,9 +63,16 @@ watch(() => route.path, () => {
62
63
  </SButton>
63
64
  </div>
64
65
  </SHeader>
65
- <SDrawer v-if="sidebarEnabled" v-model:open="navigationOpen" side="left" title="Documentation navigation" :handle="false">
66
+ <SDrawer v-if="mobileNavigationEnabled" v-model:open="navigationOpen" side="left" title="Documentation navigation" :handle="false">
66
67
  <template #body>
67
- <SContentNavigation :navigation="navigation ?? []" :collapsed="docsConfig.sidebar?.collapsed" />
68
+ <SNavigationMenu
69
+ v-if="headerLinks.length"
70
+ :items="headerLinks"
71
+ orientation="vertical"
72
+ aria-label="Main navigation"
73
+ :ui="{ root: 'mb-6 w-full' }"
74
+ />
75
+ <SContentNavigation v-if="sidebarEnabled" :navigation="navigation ?? []" :collapsed="docsConfig.sidebar?.collapsed" />
68
76
  </template>
69
77
  </SDrawer>
70
78
  </template>
@@ -1,4 +1,5 @@
1
1
  import type { ContentNavigationLink } from '@sewadah/selaras/components/ContentNavigation.vue'
2
+ import { docsContentPath } from '../utils/content-path'
2
3
 
3
4
  function flattenNavigation(links: ContentNavigationLink[]): ContentNavigationLink[] {
4
5
  return links.flatMap(link => link.children?.length ? flattenNavigation(link.children) : [link])
@@ -11,7 +12,7 @@ export function useDocsSurround() {
11
12
 
12
13
  return computed(() => {
13
14
  const links = flattenNavigation(navigation.value ?? [])
14
- const index = links.findIndex(link => link.path === route.path)
15
+ const index = links.findIndex(link => docsContentPath(link.path) === docsContentPath(route.path))
15
16
 
16
17
  return index === -1
17
18
  ? { prev: undefined, next: undefined }
@@ -7,12 +7,17 @@ import ProseH4 from '@sewadah/selaras/components/ProseH4.vue'
7
7
  import ProseH5 from '@sewadah/selaras/components/ProseH5.vue'
8
8
  import ProseH6 from '@sewadah/selaras/components/ProseH6.vue'
9
9
  import ProsePre from '@sewadah/selaras/components/ProsePre.vue'
10
+ import { docsContentPath } from '../utils/content-path'
10
11
 
11
12
  const route = useRoute()
12
13
  const appConfig = useAppConfig()
13
- const { data: page, error, status, refresh } = await useAsyncData(`selaras-docs:${route.path}`, () => queryCollection('docs').path(route.path).first())
14
+ const nuxtApp = useNuxtApp()
15
+ const contentPath = docsContentPath(route.path)
16
+ const { data: page, error, status, refresh } = await useAsyncData(`selaras-docs:${contentPath}`, () => queryCollection('docs').path(contentPath).first())
14
17
 
15
- if (!page.value && !error.value) {
18
+ const recoveringBuild = import.meta.client && (!page.value || error.value)
19
+ && await nuxtApp.$docsCheckBuild(route.fullPath, true)
20
+ if (!page.value && !error.value && !recoveringBuild) {
16
21
  throw createError({ statusCode: 404, statusMessage: 'Documentation page not found', fatal: true })
17
22
  }
18
23
  if (import.meta.server && error.value)
@@ -70,7 +75,7 @@ const surround = useDocsSurround()
70
75
  </template>
71
76
  </ContentRenderer>
72
77
  <DocsPageActions
73
- :path="route.path"
78
+ :path="contentPath"
74
79
  :title="page!.title"
75
80
  :edit-link="page!.editLink !== false"
76
81
  :issue-link="page!.issueLink !== false"
@@ -84,7 +89,7 @@ const surround = useDocsSurround()
84
89
  />
85
90
  </article>
86
91
  <DocsTableOfContents v-if="hasToc" :links="tocLinks">
87
- <DocsPageActions :path="route.path" :title="page!.title" :edit-link="page!.editLink !== false" :issue-link="page!.issueLink !== false" />
92
+ <DocsPageActions :path="contentPath" :title="page!.title" :edit-link="page!.editLink !== false" :issue-link="page!.issueLink !== false" />
88
93
  </DocsTableOfContents>
89
94
  </div>
90
95
  </SContainer>
@@ -0,0 +1,60 @@
1
+ import { appManifest } from '#build/nuxt.config.mjs'
2
+ import { createDocsBuildUpdate } from '../utils/build-update'
3
+
4
+ export default defineNuxtPlugin((nuxtApp) => {
5
+ const config = useRuntimeConfig()
6
+ const router = useRouter()
7
+ const check = import.meta.dev || !appManifest || !config.app.buildId
8
+ ? async () => false
9
+ : createDocsBuildUpdate({
10
+ buildId: config.app.buildId,
11
+ fetchLatest: () => $fetch(`${(config.app.cdnURL || config.app.baseURL).replace(/\/$/, '')}/${config.app.buildAssetsDir.replace(/^\/|\/$/g, '')}/builds/latest.json`, {
12
+ cache: 'no-store',
13
+ query: { t: Date.now() },
14
+ timeout: 3000,
15
+ retry: 0,
16
+ }),
17
+ reload: (path) => {
18
+ const target = new URL(`${config.app.baseURL.replace(/\/$/, '')}${path}`, window.location.href)
19
+ const sameDocument = target.pathname === window.location.pathname && target.search === window.location.search
20
+ if (sameDocument && target.hash !== window.location.hash)
21
+ window.history.replaceState(window.history.state, '', target.href)
22
+ nuxtApp.runWithContext(() => reloadNuxtApp({
23
+ // Omitting path reloads the document and retains its query/hash.
24
+ // Assigning an existing URL with a fragment only navigates within it.
25
+ path: sameDocument ? undefined : `${target.pathname}${target.search}${target.hash}`,
26
+ persistState: true,
27
+ ttl: 60_000,
28
+ }))
29
+ },
30
+ })
31
+
32
+ if (import.meta.client && !import.meta.dev && appManifest) {
33
+ router.beforeEach(async (to) => {
34
+ if (!nuxtApp.isHydrating && await check(to.fullPath))
35
+ return false
36
+ })
37
+ nuxtApp.hook('app:error', () => {
38
+ void check(router.currentRoute.value.fullPath, true)
39
+ })
40
+ onNuxtReady(() => {
41
+ const onVisible = () => {
42
+ if (document.visibilityState === 'visible')
43
+ void check(router.currentRoute.value.fullPath, true)
44
+ }
45
+ const onPageShow = (event: PageTransitionEvent) => {
46
+ if (event.persisted)
47
+ onVisible()
48
+ }
49
+ document.addEventListener('visibilitychange', onVisible)
50
+ window.addEventListener('pageshow', onPageShow)
51
+ nuxtApp.vueApp.onUnmount(() => {
52
+ document.removeEventListener('visibilitychange', onVisible)
53
+ window.removeEventListener('pageshow', onPageShow)
54
+ })
55
+ void check(router.currentRoute.value.fullPath)
56
+ })
57
+ }
58
+
59
+ return { provide: { docsCheckBuild: check } }
60
+ })
@@ -0,0 +1,11 @@
1
+ import { $fetch } from '#imports'
2
+
3
+ export default defineNuxtPlugin({
4
+ name: 'selaras-docs-content-fetch',
5
+ enforce: 'pre',
6
+ setup() {
7
+ // Content 3 uses a global fetch client; newer Nuxt releases scope it to imports.
8
+ const globals = globalThis as typeof globalThis & { $fetch?: typeof $fetch }
9
+ globals.$fetch ??= $fetch
10
+ },
11
+ })
@@ -0,0 +1,36 @@
1
+ interface BuildUpdateOptions {
2
+ buildId: string
3
+ fetchLatest: () => Promise<unknown>
4
+ reload: (path: string) => void
5
+ now?: () => number
6
+ interval?: number
7
+ }
8
+
9
+ /** Reload only after the server confirms this tab belongs to an older build. */
10
+ export function createDocsBuildUpdate({ buildId, fetchLatest, reload, now = Date.now, interval = 60_000 }: BuildUpdateOptions) {
11
+ let lastCheck = -Infinity
12
+ let pending: Promise<boolean> | undefined
13
+ let outdated = false
14
+ let reloading = false
15
+
16
+ return async (path: string, force = false): Promise<boolean> => {
17
+ if (!outdated && !pending && (force || now() - lastCheck >= interval)) {
18
+ lastCheck = now()
19
+ pending = fetchLatest().then(latest => !!latest && typeof latest === 'object'
20
+ && 'id' in latest && typeof latest.id === 'string' && latest.id.length > 0 && latest.id !== buildId).catch(() => false)
21
+ }
22
+ if (pending) {
23
+ const request = pending
24
+ outdated = await request
25
+ if (pending === request)
26
+ pending = undefined
27
+ }
28
+ if (!outdated)
29
+ return false
30
+ if (!reloading) {
31
+ reloading = true
32
+ reload(path)
33
+ }
34
+ return true
35
+ }
36
+ }
@@ -0,0 +1,4 @@
1
+ /** Nuxt Content stores page paths without a trailing slash. */
2
+ export function docsContentPath(path: string) {
3
+ return path.replace(/\/+$/, '') || '/'
4
+ }
@@ -0,0 +1,7 @@
1
+ export function isDocsNotFound(error: unknown) {
2
+ if (!error || typeof error !== 'object')
3
+ return false
4
+ const status = 'status' in error ? error.status : undefined
5
+ const statusCode = 'statusCode' in error ? error.statusCode : undefined
6
+ return (status ?? statusCode) === 404
7
+ }
package/nuxt.config.mjs CHANGED
@@ -5,6 +5,11 @@ const { resolve } = createResolver(import.meta.url)
5
5
 
6
6
  export default defineNuxtConfig({
7
7
  modules: ['@sewadah/selaras', '@nuxt/content', resolve('./modules/docs.mjs')],
8
+ experimental: {
9
+ emitRouteChunkError: 'automatic-immediate',
10
+ // Content 3 still imports server utilities from Nitro's generated imports.
11
+ nitroAutoImports: true,
12
+ },
8
13
  // Selaras supports Node versions with node:sqlite. Keeping Content on its
9
14
  // native connector lets an installed docs layer avoid a native addon.
10
15
  content: {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sewadah/selaras-docs",
3
3
  "type": "module",
4
- "version": "1.3.1",
4
+ "version": "1.3.3",
5
5
  "description": "Nuxt Content documentation layer for Selaras",
6
6
  "repository": {
7
7
  "type": "git",
@@ -33,7 +33,7 @@
33
33
  "dependencies": {
34
34
  "@nuxt/content": "^3.16.0",
35
35
  "@nuxt/kit": "^4.5.2",
36
- "@sewadah/selaras": "^0.10.0",
36
+ "@sewadah/selaras": "^1.1.0",
37
37
  "tailwindcss": "^4.3.0"
38
38
  }
39
39
  }