@sewadah/selaras-docs 1.2.2 → 1.2.4

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## v1.2.4
+
+[compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.2.3...selaras-docs-v1.2.4)
+
+### 🚀 Enhancements
+
+- **feat(docs):** add interactive application blocks ([102ee68](https://github.com/sewadahapp/selaras/commit/102ee68bef82d12b07dc4788dc8ea2378435e0ea))
+- **feat(docs):** add error pages and local recovery boundaries ([371ed7a](https://github.com/sewadahapp/selaras/commit/371ed7a4fd873fa7e4647ab0b89b85dc0bb7a4b7))
+- **feat(docs):** add SEO metadata and static sharing images ([f6ec141](https://github.com/sewadahapp/selaras/commit/f6ec14152def06f91a62292b53ae2df50813b1d5))
+- **feat(docs):** add Seirama branding and design kit ([9fd9f19](https://github.com/sewadahapp/selaras/commit/9fd9f1948feaa19897ae24e982d33099d50a732c))
+- **feat(forms):** add leading and trailing content slots ([ebd0948](https://github.com/sewadahapp/selaras/commit/ebd094813a274d444319cb0354387c770ab8a6ef))
+
+### 🩹 Fixes
+
+- **fix(docs):** configure custom domain deployment ([b65908a](https://github.com/sewadahapp/selaras/commit/b65908a7aa4ad0d0b67029b41c338633e9faa50d))
+
+Published against `@sewadah/selaras` ^0.9.0.
+
+## v1.2.3
+
+[compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.2.2...selaras-docs-v1.2.3)
+
+### 🚀 Enhancements
+
+- **feat(forms):** add listbox and transfer list ([e4ca547](https://github.com/sewadahapp/selaras/commit/e4ca54737d3ba492c20a61fb9e712afeaff99674))
+
+### 🩹 Fixes
+
+- **fix(select):** align selected option styles with listbox ([342eaf3](https://github.com/sewadahapp/selaras/commit/342eaf3c47851b3720fb686cac4adf50fc224c8a))
+- **fix(avatar-group):** flatten dynamic slot children ([9c68a66](https://github.com/sewadahapp/selaras/commit/9c68a66cccc4e88f0ae2a83e2fcc5a59cfa3c3a2))
+- **fix(color-mode):** keep controls stable during hydration ([4ef0d71](https://github.com/sewadahapp/selaras/commit/4ef0d7105308f5a1fe4fdf95f213933e3e2f4a34))
+
+Published against `@sewadah/selaras` ^0.8.0.
+
 ## v1.2.2
 
 [compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.2.1...selaras-docs-v1.2.2)

package/README.md

@@ -119,6 +119,65 @@ pieces can be replaced on their own:
 For example, a `components/DocsFooterBrand.vue` containing `<DocsLogo />` adds
 the logo to the footer while leaving the header as configured.
 
+## Error recovery
+
+The layer provides a default `error.vue` for missing pages and fatal errors.
+It preserves the HTTP status code, keeps error pages out of search indexes and
+offers a home link or reload action. The standalone screen avoids loading
+navigation and Content data so it can render when those services fail.
+
+Client-side page failures show a local recovery state inside the layout, keeping
+the header and sidebar available. `DocsExample` isolates each live example;
+retrying remounts its content. Navigating to another route clears the page
+boundary. Server rendering errors still use the standalone error screen.
+
+Content query failures show a retry state with HTTP 500 during server rendering.
+Only a successful query with no matching document is treated as a 404.
+If a request cannot recover in place, retry reloads the current page to start a
+fresh session. Reloads happen only after the user chooses to retry.
+
+Customize the messages and home destination in `app.config.ts`:
+
+```ts
+export default defineAppConfig({
+  selarasDocs: {
+    errors: {
+      homeTo: '/guide/introduction',
+      homeLabel: 'Back to the guide',
+      retryLabel: 'Try again',
+      reloadLabel: 'Reload page',
+      retryingLabel: 'Trying again…',
+      notFound: { title: 'Page not found', description: 'Start again from the guide.' },
+      fatal: { title: 'Something went wrong' },
+      page: { title: 'This page couldn’t load' },
+      example: { title: 'This example couldn’t load' },
+    },
+  },
+})
+```
+
+Home destinations are internal routes resolved under the app's `baseURL`.
+The default destination is `/`. Provide an existing page if your site has no
+homepage. Public recovery copy never includes raw exceptions or stack traces.
+
+Override `components/DocsErrorIllustration.vue` to replace the default geometric
+document illustration. The optional `missing` boolean distinguishes a 404 from
+other errors. Use inherited theme tokens in inline SVGs for light/dark support.
+`DocsErrorState` also exposes an `illustration` slot. Override `DocsErrorPage`
+for the standalone screen's composition, or supply your own `error.vue` for
+application-specific providers. Applications with their own `app.vue` should
+retain the page boundary inside their layout:
+
+```vue
+<template>
+  <NuxtLayout>
+    <DocsErrorBoundary>
+      <NuxtPage />
+    </DocsErrorBoundary>
+  </NuxtLayout>
+</template>
+```
+
 For a host that owns Tailwind compilation or uses a class prefix, set
 `selarasDocs: { css: false }` in `nuxt.config.ts` and import Selaras and the
 docs stylesheet from the host CSS entry.

package/app/app.config.ts

@@ -31,7 +31,7 @@ export default defineAppConfig({
       links: [
         {
           label: 'Powered by Selaras',
-          to: 'https://sewadahapp.github.io/selaras',
+          to: 'https://selarasui.my.id',
           target: '_blank',
           rel: 'noreferrer',
         },

package/app/app.vue

@@ -13,7 +13,9 @@ useHead(() => {
 <template>
   <SApp>
     <NuxtLayout>
-      <NuxtPage />
+      <DocsErrorBoundary>
+        <NuxtPage />
+      </DocsErrorBoundary>
     </NuxtLayout>
     <ClientOnly>
       <DocsSearch />

package/app/components/DocsErrorBoundary.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import type { SelarasDocsErrorKind } from '../../types'
+import { useTemplateRef, watch } from 'vue'
+import { useRouter } from '#app'
+
+const props = withDefaults(defineProps<{
+  kind?: Extract<SelarasDocsErrorKind, 'page' | 'example'>
+  resetKey?: string
+}>(), { kind: 'page' })
+
+const boundary = useTemplateRef('boundary')
+const router = useRouter()
+watch([() => router.currentRoute.value.fullPath, () => props.resetKey], () => boundary.value?.clearError())
+
+function isMissing(error: Error) {
+  return 'statusCode' in error && error.statusCode === 404
+}
+</script>
+
+<template>
+  <NuxtErrorBoundary ref="boundary">
+    <slot />
+    <template #error="{ error, clearError }">
+      <DocsErrorState :kind="kind === 'page' && isMissing(error) ? 'notFound' : kind" @retry="clearError" />
+    </template>
+  </NuxtErrorBoundary>
+</template>

package/app/components/DocsErrorIllustration.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+defineProps<{ missing?: boolean }>()
+</script>
+
+<template>
+  <svg viewBox="0 0 400 240" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
+    <path d="M40 187H360" stroke="var(--selaras-resolved-border-default)" stroke-width="2" stroke-linecap="round" />
+    <rect x="113" y="41" width="148" height="159" rx="12" fill="var(--selaras-resolved-surface-elevated)" stroke="var(--selaras-resolved-border-default)" stroke-width="2" />
+    <path d="M144 24H231L277 70V170C277 177 272 182 265 182H144C137 182 132 177 132 170V36C132 29 137 24 144 24Z" fill="var(--selaras-resolved-surface-default)" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2.5" stroke-linejoin="round" />
+    <path d="M231 25V58C231 65 236 70 243 70H276" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2.5" stroke-linejoin="round" />
+    <path d="M154 61H193M154 84H213" stroke="var(--selaras-resolved-border-default)" stroke-width="5" stroke-linecap="round" />
+    <rect x="154" y="108" width="57" height="48" rx="6" fill="var(--selaras-resolved-color-primary-subtle)" />
+    <path v-if="missing" d="M225 113H254V154H225V113Z" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2" stroke-dasharray="4 5" stroke-linejoin="round" />
+    <path v-else d="M233 116V135M233 146V147" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="4" stroke-linecap="round" />
+    <path d="M56 153C56 122 84 119 105 132M290 109C318 103 342 122 333 146" stroke="var(--selaras-resolved-border-default)" stroke-width="2" stroke-dasharray="4 7" stroke-linecap="round" />
+    <circle cx="55" cy="159" r="6" fill="var(--selaras-resolved-color-primary-fill)" />
+    <rect x="311" y="144" width="44" height="37" rx="6" fill="var(--selaras-resolved-color-primary-subtle)" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2" />
+    <path d="M323 163H343M333 153V173" stroke="var(--selaras-resolved-color-primary-fill)" stroke-width="2" stroke-linecap="round" />
+  </svg>
+</template>

package/app/components/DocsErrorPage.vue

@@ -0,0 +1,81 @@
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+
+const props = defineProps<{ error: NuxtError }>()
+const config = useRuntimeConfig()
+const appConfig = useAppConfig()
+const siteName = computed(() => appConfig.selarasDocs?.site?.name ?? 'Documentation')
+const missing = computed(() => props.error.statusCode === 404)
+const pending = ref(false)
+
+useSeoMeta({
+  title: () => `${missing.value ? 'Page not found' : 'Something went wrong'} — ${siteName.value}`,
+  robots: 'noindex',
+})
+
+function reload() {
+  pending.value = true
+  window.location.reload()
+}
+
+async function goHome(event: MouseEvent) {
+  event.preventDefault()
+  const path = appConfig.selarasDocs?.errors?.homeTo ?? '/'
+  try {
+    await clearError({ redirect: path })
+  }
+  catch {
+    window.location.assign(`${config.app.baseURL.replace(/\/$/, '')}/${path.replace(/^\//, '')}`)
+  }
+}
+</script>
+
+<template>
+  <div class="selaras-docs-root selaras-docs-error-page">
+    <header class="selaras-docs-error-header">
+      <a :href="config.app.baseURL" class="selaras-docs-error-brand" :aria-label="`${siteName} home`">
+        <DocsLogo />
+        <span>{{ siteName }}</span>
+      </a>
+    </header>
+    <main class="selaras-docs-error-main">
+      <DocsErrorState :kind="missing ? 'notFound' : 'fatal'" :pending="pending" @retry="reload" @home="goHome" />
+    </main>
+  </div>
+</template>
+
+<style scoped>
+.selaras-docs-error-page {
+  min-height: 100svh;
+  color: var(--selaras-resolved-text-default);
+}
+
+.selaras-docs-error-header {
+  width: min(100%, 90rem);
+  margin: 0 auto;
+  padding: 1.5rem;
+}
+
+.selaras-docs-error-brand {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.75rem;
+  color: inherit;
+  font-size: 1.125rem;
+  font-weight: 650;
+  text-decoration: none;
+}
+
+.selaras-docs-error-brand:focus-visible {
+  border-radius: var(--selaras-resolved-radius-sm);
+  outline: 2px solid var(--selaras-resolved-color-primary-focus);
+  outline-offset: 4px;
+}
+
+.selaras-docs-error-main {
+  display: grid;
+  align-items: center;
+  min-height: calc(100svh - 6rem);
+  padding: 1.5rem 1.5rem 5rem;
+}
+</style>

package/app/components/DocsErrorState.vue

@@ -0,0 +1,161 @@
+<script setup lang="ts">
+import type { SelarasDocsErrorKind } from '../../types'
+
+const props = withDefaults(defineProps<{
+  kind?: SelarasDocsErrorKind
+  pending?: boolean
+  showHome?: boolean
+}>(), { kind: 'page', pending: false, showHome: undefined })
+
+const emit = defineEmits<{ retry: [], home: [event: MouseEvent] }>()
+const appConfig = useAppConfig()
+const config = useRuntimeConfig()
+const homeHref = computed(() => {
+  const path = appConfig.selarasDocs?.errors?.homeTo ?? '/'
+  const base = config.app.baseURL.replace(/\/$/, '')
+  return `${base}/${path.replace(/^\//, '')}`
+})
+const headingId = useId()
+const heading = useTemplateRef<HTMLElement>('heading')
+onMounted(() => {
+  if (props.kind !== 'example')
+    heading.value?.focus({ preventScroll: true })
+})
+const copy = computed(() => {
+  const defaults = {
+    notFound: { title: 'Page not found', description: 'The link may have changed, or this page may no longer exist. You can start again from the homepage.' },
+    fatal: { title: 'Something went wrong', description: 'We couldn’t load this page. Reload it to try again, or return to the homepage.' },
+    page: { title: 'This page couldn’t load', description: 'Please try again. You can still use the navigation to explore other pages.' },
+    example: { title: 'This example couldn’t load', description: 'Try loading the example again. The rest of the documentation is still available.' },
+  }
+  return { ...defaults[props.kind], ...appConfig.selarasDocs?.errors?.[props.kind] }
+})
+const labels = computed(() => appConfig.selarasDocs?.errors ?? {})
+const showHome = computed(() => props.showHome ?? props.kind !== 'example')
+</script>
+
+<template>
+  <section
+    class="selaras-docs-error-state not-prose"
+    :data-error-kind="kind"
+    :aria-labelledby="headingId"
+    :role="kind === 'example' ? 'alert' : undefined"
+  >
+    <div class="selaras-docs-error-artwork">
+      <slot name="illustration">
+        <DocsErrorIllustration :missing="kind === 'notFound'" />
+      </slot>
+    </div>
+    <div class="selaras-docs-error-copy">
+      <component :is="kind === 'example' ? 'h3' : 'h1'" :id="headingId" ref="heading" class="selaras-docs-error-title" :tabindex="kind === 'example' ? undefined : -1">
+        {{ copy.title }}
+      </component>
+      <p class="selaras-docs-error-description">
+        {{ copy.description }}
+      </p>
+      <div class="selaras-docs-error-actions">
+        <SButton v-if="kind !== 'notFound'" :loading="pending" :disabled="pending" @click="emit('retry')">
+          {{ pending ? labels.retryingLabel ?? 'Trying again…' : kind === 'fatal' ? labels.reloadLabel ?? 'Reload page' : labels.retryLabel ?? 'Try again' }}
+        </SButton>
+        <SButton v-if="showHome" as="a" :href="homeHref" :variant="kind === 'notFound' ? 'solid' : 'outline'" :color="kind === 'notFound' ? 'primary' : 'neutral'" @click="emit('home', $event)">
+          {{ labels.homeLabel ?? 'Go to homepage' }}
+        </SButton>
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.selaras-docs-error-state {
+  width: min(100%, 42rem);
+  margin: 3rem auto;
+  color: var(--selaras-resolved-text-default);
+  text-align: center;
+}
+
+.selaras-docs-error-artwork {
+  width: min(100%, 22rem);
+  margin: 0 auto 1.5rem;
+}
+
+.selaras-docs-error-artwork :deep(svg) {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.selaras-docs-error-title {
+  margin: 0;
+  font-size: clamp(1.75rem, 1.4rem + 1vw, 2.5rem);
+  font-weight: 650;
+  line-height: 1.15;
+  letter-spacing: -0.025em;
+  text-wrap: balance;
+}
+
+.selaras-docs-error-title:focus {
+  outline: none;
+}
+
+.selaras-docs-error-description {
+  max-width: 44ch;
+  margin: 1rem auto 0;
+  color: var(--selaras-resolved-text-muted);
+  font-size: 1rem;
+  line-height: 1.7;
+}
+
+.selaras-docs-error-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.75rem;
+  margin-top: 1.75rem;
+}
+
+.selaras-docs-error-state[data-error-kind="example"] {
+  display: flex;
+  align-items: center;
+  gap: 1.25rem;
+  width: 100%;
+  margin: 0;
+  padding: 1.5rem;
+  border: 1px solid var(--selaras-resolved-border-default);
+  border-radius: var(--selaras-resolved-radius-lg);
+  background: var(--selaras-resolved-surface-elevated);
+  text-align: start;
+}
+
+[data-error-kind="example"] .selaras-docs-error-artwork {
+  flex: none;
+  width: 6rem;
+  margin: 0;
+}
+
+[data-error-kind="example"] .selaras-docs-error-title {
+  font-size: 1rem;
+  line-height: 1.4;
+  letter-spacing: normal;
+}
+
+[data-error-kind="example"] .selaras-docs-error-description {
+  margin: 0.375rem 0 0;
+  font-size: 0.875rem;
+}
+
+[data-error-kind="example"] .selaras-docs-error-actions {
+  justify-content: flex-start;
+  margin-top: 1rem;
+}
+
+@media (max-width: 30rem) {
+  .selaras-docs-error-state[data-error-kind="example"] {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+
+  [data-error-kind="example"] .selaras-docs-error-artwork {
+    display: none;
+  }
+}
+</style>

package/app/components/content/DocsExample.vue

@@ -18,7 +18,9 @@ const resolvedComponent = computed(() => {
 
 <template>
   <section v-if="resolvedComponent" :data-example="name">
-    <component :is="resolvedComponent" />
+    <DocsErrorBoundary kind="example" :reset-key="name">
+      <component :is="resolvedComponent" />
+    </DocsErrorBoundary>
   </section>
   <p v-else role="alert">
     Example "{{ name }}" not found

package/app/error.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+
+defineProps<{ error: NuxtError }>()
+</script>
+
+<template>
+  <SApp>
+    <DocsErrorPage :error="error" />
+  </SApp>
+</template>

package/app/pages/[...slug].vue

@@ -10,14 +10,30 @@ import ProsePre from '@sewadah/selaras/components/ProsePre.vue'
 
 const route = useRoute()
 const appConfig = useAppConfig()
-const { data: page } = await useAsyncData(`selaras-docs:${route.path}`, () => queryCollection('docs').path(route.path).first())
+const { data: page, error, status, refresh } = await useAsyncData(`selaras-docs:${route.path}`, () => queryCollection('docs').path(route.path).first())
 
-if (!page.value) {
+if (!page.value && !error.value) {
   throw createError({ statusCode: 404, statusMessage: 'Documentation page not found', fatal: true })
 }
+if (import.meta.server && error.value)
+  setResponseStatus(500)
+
+async function retryPage() {
+  await refresh()
+  if (import.meta.client && error.value) {
+    window.location.reload()
+    return
+  }
+  if (!page.value && !error.value)
+    showError({ statusCode: 404, statusMessage: 'Documentation page not found' })
+}
 
 definePageMeta({ layout: 'selaras-docs' })
-useSeoMeta({ title: page.value.title, description: page.value.description ?? appConfig.selarasDocs?.site?.description })
+useSeoMeta({
+  title: () => page.value?.title ?? appConfig.selarasDocs?.errors?.page?.title ?? 'Documentation unavailable',
+  description: () => page.value?.description ?? appConfig.selarasDocs?.site?.description,
+  robots: () => error.value ? 'noindex' : undefined,
+})
 useHead(() => ({
   ...(appConfig.selarasDocs?.site?.titleTemplate && { titleTemplate: appConfig.selarasDocs.site.titleTemplate }),
   ...(appConfig.selarasDocs?.site?.url && {
@@ -40,7 +56,8 @@ const surround = useDocsSurround()
 </script>
 
 <template>
-  <SContainer size="full" class="selaras-docs-page" :class="{ 'selaras-docs-page--fluid': appConfig.selarasDocs?.main?.fluid }">
+  <DocsErrorState v-if="error || !page" kind="page" :pending="status === 'pending'" @retry="retryPage" />
+  <SContainer v-else size="full" class="selaras-docs-page" :class="{ 'selaras-docs-page--fluid': appConfig.selarasDocs?.main?.fluid }">
     <div class="selaras-docs-page-grid">
       <article class="selaras-docs-article">
         <p v-if="page!.description" class="selaras-docs-description">

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sewadah/selaras-docs",
   "type": "module",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Nuxt Content documentation layer for Selaras",
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
   "dependencies": {
     "@nuxt/content": "^3.16.0",
     "@nuxt/kit": "^4.5.2",
-    "@sewadah/selaras": "^0.7.1",
+    "@sewadah/selaras": "^0.9.0",
     "tailwindcss": "^4.3.0"
   }
 }

package/types.d.ts

@@ -37,7 +37,23 @@ export interface SelarasDocsLogo {
   tint?: boolean
 }
 
+export type SelarasDocsErrorKind = 'notFound' | 'fatal' | 'page' | 'example'
+
+export interface SelarasDocsErrorCopy {
+  title?: string
+  description?: string
+}
+
 export interface SelarasDocsAppConfig {
+  /** Recovery messages and the destination of error-screen home links. */
+  errors?: Partial<Record<SelarasDocsErrorKind, SelarasDocsErrorCopy>> & {
+    /** An internal route, resolved under the application's base URL. @default '/' */
+    homeTo?: string
+    homeLabel?: string
+    retryLabel?: string
+    reloadLabel?: string
+    retryingLabel?: string
+  }
   site?: {
     name?: string
     description?: string