@sewadah/selaras-docs 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## v1.2.0
+
+[compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.1.0...selaras-docs-v1.2.0)
+
+### 🚀 Enhancements
+
+- **feat(docs):** provide reusable viewport preview component ([ccead99](https://github.com/sewadahapp/selaras/commit/ccead99a5c07c1eb11e573285ad362d23ee3263a))
+- **feat(docs):** add device previews for adaptive interfaces ([dcd620f](https://github.com/sewadahapp/selaras/commit/dcd620fb331fbe7df1d443ce5d5219be665cf714))
+- **feat(docs):** replace logo and favicon ([0ba8a12](https://github.com/sewadahapp/selaras/commit/0ba8a1234c5395682261d7170c18aeca60ee7dc5))
+- **feat(agent):** add Selaras skill and local MCP server ([b15bc01](https://github.com/sewadahapp/selaras/commit/b15bc0181e86981d902640d7608554072bf095f0))
+
+### 🩹 Fixes
+
+- **fix(autocomplete):** use a modal for adaptive mobile editing ([330540f](https://github.com/sewadahapp/selaras/commit/330540f8073cd9b28782f01492f93e990b2d9ed1))
+
+### 📖 Documentation
+
+- **docs:** organize overview guides and add agent documentation exports ([3f5537b](https://github.com/sewadahapp/selaras/commit/3f5537b3138c5bc345da0d88dabb620f73dcd176))
+
+### 🤖 Other changes
+
+- **build(docs):** install local icon collections ([5f4fcaa](https://github.com/sewadahapp/selaras/commit/5f4fcaa9ccb403b4fccdf6debbe11ca78c1a739d))
+
+Published against `@sewadah/selaras` ^0.4.0.
+
 ## v1.1.0
 
 [compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.0.1...selaras-docs-v1.1.0)

package/README.md

@@ -122,3 +122,56 @@ the logo to the footer while leaving the header as configured.
 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.
+
+## Viewport previews
+
+`DocsViewportPreview` embeds an example page in a real iframe viewport. Device
+buttons change its width, so media queries and Selaras' `adaptive` controls
+respond without resizing the documentation browser. It is available in Vue
+components and Markdown:
+
+```md
+::docs-viewport-preview{src="/examples/team-picker" title="Team picker" :height="540"}
+::
+```
+
+Create the example route in your application's `pages/` directory (or
+`app/pages/` with Nuxt's default directory structure). Use `layout: false` to
+render only the example:
+
+```vue
+<script setup lang="ts">
+definePageMeta({ layout: false })
+const team = ref<string>()
+</script>
+
+<template>
+  <main class="p-6">
+    <SSelect v-model="team" :items="['Design', 'Engineering']" adaptive />
+  </main>
+</template>
+```
+
+Root-relative `src` paths automatically include the application's `baseURL`.
+When generating a static site, add example routes to `nitro.prerender.routes`;
+iframe URLs are not ordinary navigation links for the prerender crawler.
+
+| Prop / model | Default | Purpose |
+| --- | --- | --- |
+| `src` | Required | URL of the example page. |
+| `title` | `Responsive example` | Accessible preview label and iframe title. |
+| `devices` | Desktop 1024px, tablet 768px, mobile 390px | Entries with `value`, `label`, `width`, and optional `icon`. Widths are CSS pixels. |
+| `defaultDevice` | `mobile` | Initial selection; an unknown value falls back to the first device. |
+| `v-model:device` | Uncontrolled | Read or control the selected device value. |
+| `height` | `540` | Iframe height in CSS pixels. |
+| `reloadKey` | Unset | Change this to reload the embedded page, for example after a theme change. |
+
+The frame scrolls horizontally when the chosen viewport is wider than its
+container. Changing devices preserves the embedded page's state; changing
+`reloadKey` remounts it. The example page controls its own theme and providers.
+An empty `devices` array uses the default devices.
+
+`toolbar-start` and `toolbar-end` accept additional toolbar content and receive
+`{ device }`. The `toolbar` slot replaces the entire toolbar and receives
+`{ device, devices, selectDevice }`. Custom device entries can use the exported
+`SelarasDocsViewportDevice` type from `@sewadah/selaras-docs`.

package/app/components/content/DocsViewportPreview.vue

@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import type { SelarasDocsViewportDevice } from '../../../types'
+
+const props = withDefaults(defineProps<{
+  src: string
+  title?: string
+  devices?: readonly SelarasDocsViewportDevice[]
+  defaultDevice?: string
+  height?: number
+  reloadKey?: string | number
+}>(), {
+  title: 'Responsive example',
+  defaultDevice: 'mobile',
+  height: 540,
+})
+const selected = defineModel<string>('device')
+const defaultDevices: readonly SelarasDocsViewportDevice[] = [
+  { value: 'desktop', label: 'Desktop', icon: 'hugeicons:computer', width: 1024 },
+  { value: 'tablet', label: 'Tablet', icon: 'hugeicons:tablet-01', width: 768 },
+  { value: 'mobile', label: 'Mobile', icon: 'hugeicons:smart-phone-01', width: 390 },
+]
+const devices = computed(() => props.devices?.length ? props.devices : defaultDevices)
+const device = computed(() => devices.value.find(device => device.value === (selected.value ?? props.defaultDevice)) ?? devices.value[0]!)
+function selectDevice(value: string) {
+  selected.value = value
+}
+const assetUrl = useDocsAssetUrl()
+const previewUrl = computed(() => assetUrl(props.src))
+</script>
+
+<template>
+  <section class="not-prose min-w-0" :aria-label="title">
+    <slot name="toolbar" :device="device" :devices="devices" :select-device="selectDevice">
+      <div class="mb-3 flex flex-wrap items-center justify-between gap-3">
+        <slot name="toolbar-start" :device="device">
+          <p class="text-sm text-[var(--selaras-resolved-text-muted)]" aria-live="polite">
+            {{ device.label }} · {{ device.width }}px
+          </p>
+        </slot>
+        <div class="flex items-center gap-2">
+          <div class="inline-flex gap-1 rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)] p-1" role="group" aria-label="Preview viewport">
+            <SButton
+              v-for="option in devices" :key="option.value"
+              :icon="option.icon" :aria-label="option.label" :aria-pressed="device.value === option.value"
+              :variant="device.value === option.value ? 'solid' : 'ghost'"
+              :color="device.value === option.value ? 'primary' : 'neutral'"
+              size="sm" :square="!!option.icon" @click="selectDevice(option.value)"
+            >
+              <template v-if="!option.icon">
+                {{ option.label }}
+              </template>
+            </SButton>
+          </div>
+          <slot name="toolbar-end" :device="device" />
+        </div>
+      </div>
+    </slot>
+    <div class="overflow-x-auto rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)] bg-[var(--selaras-resolved-surface-elevated)] p-3 sm:p-4">
+      <iframe
+        :key="reloadKey" :src="previewUrl"
+        :title="`${title} — ${device.label}`"
+        :style="{ width: `${device.width}px`, height: `${height}px`, boxSizing: 'content-box' }"
+        class="mx-auto block max-w-none rounded-[var(--selaras-resolved-radius-md)] border border-[var(--selaras-resolved-border-default)] bg-[var(--selaras-resolved-surface-default)]"
+      />
+    </div>
+  </section>
+</template>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sewadah/selaras-docs",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "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.3.2",
+    "@sewadah/selaras": "^0.4.0",
     "tailwindcss": "^4.3.0"
   }
 }

package/types.d.ts

@@ -128,3 +128,11 @@ declare module 'nuxt/schema' {
     selarasDocs: SelarasDocsModuleOptions
   }
 }
+
+/** A viewport offered by DocsViewportPreview. Width is measured in CSS pixels. */
+export interface SelarasDocsViewportDevice {
+  value: string
+  label: string
+  width: number
+  icon?: string
+}