@sewadah/selaras-docs 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # 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)
+
+### 🚀 Enhancements
+
+- **feat(color-mode-switch):** add switch for light and dark modes ([0fea5d4](https://github.com/sewadahapp/selaras/commit/0fea5d4cfcdd1be2fcdad10241d0e5dabbaf720a))
+- **feat(button):** add subtle variant and underline links on hover ([62e77b3](https://github.com/sewadahapp/selaras/commit/62e77b312a6a32c53cab0127006fd27305658f37))
+- **feat:** add confirm service and refine component behavior ([f3cf73b](https://github.com/sewadahapp/selaras/commit/f3cf73b9f492f7cb8ed44a4ded4c26ec6b165e19))
+- **feat(select):** support object options as values ([be2ae38](https://github.com/sewadahapp/selaras/commit/be2ae38485110f2fa1e6cfdfc2e12eecf69885e4))
+- **feat(code-group):** add Bun package manager icon ([4d8c927](https://github.com/sewadahapp/selaras/commit/4d8c927d4a2f8058d0a1a6a61e2996609bf4550a))
+- **feat(docs):** redesign theme picker ([22cc5f2](https://github.com/sewadahapp/selaras/commit/22cc5f229eba4aae0dc65a7104d0d6d26a74a42d))
+
+### 🩹 Fixes
+
+- **fix(ci):** allow headroom in packed consumer CSS budgets ([d1bd54a](https://github.com/sewadahapp/selaras/commit/d1bd54adb2247945e9ec05477fa6b944ac4a1a41))
+- **fix(button):** strengthen text variant hover colors ([586d38c](https://github.com/sewadahapp/selaras/commit/586d38c570b7e19ff5cd5f167319a2cd098d26ff))
+- **fix(docs):** remove default footer attribution ([5cd46ba](https://github.com/sewadahapp/selaras/commit/5cd46ba3a538ccbe37ef12177fcf49babce459b3))
+- **fix(theme):** allow chip variant conditions ([2ecefb0](https://github.com/sewadahapp/selaras/commit/2ecefb0425083d08cea9447d212278291407f7c3))
+- **fix(degung):** join grouped buttons back into one segmented pill ([ca3a14e](https://github.com/sewadahapp/selaras/commit/ca3a14e0a8a7c1083b2f1da2bc904aae133cbdf2))
+- **fix(degung):** taper each display rim before its own corner ([4e025fe](https://github.com/sewadahapp/selaras/commit/4e025feb87f70c0f8e66c555ebe08aa7b53b05c6))
+- **fix(degung):** use a fixed-pixel display rim inset instead of a percentage ([ac6567d](https://github.com/sewadahapp/selaras/commit/ac6567dd1d042686ec3cf432a09e9a87397c61b9))
+- **fix(degung):** apply the display look to every accordion, flatten nested groups ([38b8d20](https://github.com/sewadahapp/selaras/commit/38b8d2058478ac80e58d724d8b6a886860416e14))
+- **fix(degung):** collapse the rail's leftover gutter on nested nav rows ([e138ce8](https://github.com/sewadahapp/selaras/commit/e138ce80f178cefe5470340f63a16df249a8c3e3))
+- **fix(degung):** tone down the display text glow for readability ([a65a32a](https://github.com/sewadahapp/selaras/commit/a65a32a038e93bc0ace34d4d19daf2ef23eda9d9))
+- **fix(degung):** drop the tree-connector rail and readable nav hover ([f712787](https://github.com/sewadahapp/selaras/commit/f71278758a3a686229f589dac0de9242d0fc259a))
+- **fix(toast):** carry a card's full background into its stacked cover ([d7c7562](https://github.com/sewadahapp/selaras/commit/d7c7562e6a3f32bbec646eaafbdc51c40c0df9e7))
+
+### 📖 Documentation
+
+- **docs(degung):** restyle the preset as rounded glossy hardware ([9be8a84](https://github.com/sewadahapp/selaras/commit/9be8a84cdd37706a982a05c80c093cf3636ecbc1))
+
+### 🤖 Other changes
+
+- **chore(test):** restore default worker parallelism ([e4b7f59](https://github.com/sewadahapp/selaras/commit/e4b7f59a6628a0de1567a5ef61e5e29870394d17))
+- **chore(scripts):** run docs template from docs dev ([f743ad4](https://github.com/sewadahapp/selaras/commit/f743ad4e99bcdeff581c18f287cb3dc3729b03b5))
+- **chore(dev):** add Nix shell and limit test workers ([055c03d](https://github.com/sewadahapp/selaras/commit/055c03dcbbe7b6b5fab37210c59b36f03c1a6580))
+- **style(docs):** refine footer and display finish ([31a9dae](https://github.com/sewadahapp/selaras/commit/31a9dae7d7fa23a22d6dbad1e19d5d0616552453))
+- **style(docs):** refine footer content and alignment ([d29b947](https://github.com/sewadahapp/selaras/commit/d29b9479a86caca36c39d1d66d1580257f74b184))
+- **style(degung):** brighten, lengthen and thin the display rim highlight ([413cad5](https://github.com/sewadahapp/selaras/commit/413cad5fae769b5338f45b0c9537f65bc17aa9ab))
+- **style(degung):** enlarge the slider thumb, inset the display rim from the edge ([7530118](https://github.com/sewadahapp/selaras/commit/75301182347d14d16d5b2d7aa1ad7e4381e94465))
+- **style(degung):** tighten the display rim to a hairline ([ed8d531](https://github.com/sewadahapp/selaras/commit/ed8d53190907fa630aff7c2db26eb1333b47702f))
+- **style(degung):** widen the slider thumb, tuck the display rim to all four edges ([8d51891](https://github.com/sewadahapp/selaras/commit/8d51891c41a5323b0713d50568b88fef281e886b))
+- **style(degung):** twin-edge display highlight, chrome pill slider thumb ([c385bb9](https://github.com/sewadahapp/selaras/commit/c385bb948194bfd04f0c3aca3d34e1b9eb7ae911))
+- **style(degung):** add display glow, screen highlight and selection color ([5a2897e](https://github.com/sewadahapp/selaras/commit/5a2897e627f90acf134f4bfc07f35d8bb4365a58))
+
+Published against `@sewadah/selaras` ^0.3.2.
+
 ## v1.0.1
 
 [compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.0.0...selaras-docs-v1.0.1)

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/assets/style.css

@@ -156,6 +156,7 @@
   position: relative;
   width: min(100%, 90rem);
   margin-inline: auto;
+  isolation: isolate;
 }
 
 .selaras-docs-footer--fluid {
@@ -164,11 +165,13 @@
 
 .selaras-docs-footer::before {
   position: absolute;
+  z-index: -1;
+  inset-block: 0;
   inset-inline-start: 50%;
-  top: 0;
   width: 100vw;
   transform: translateX(-50%);
-  border-top: 1px solid var(--selaras-resolved-border-default);
+  border-top: 1px solid color-mix(in oklab, var(--selaras-resolved-border-default) 72%, transparent);
+  background: color-mix(in oklab, var(--selaras-resolved-surface-canvas) 34%, var(--selaras-resolved-surface-default));
   content: '';
   pointer-events: none;
 }
@@ -181,7 +184,8 @@
   align-items: center;
   justify-content: space-between;
   gap: 1rem;
-  min-height: 5rem;
+  min-height: 4.5rem;
+  padding-block: 0.875rem;
 }
 
 .selaras-docs-footer-text {
@@ -193,21 +197,37 @@
 .selaras-docs-footer-links {
   display: flex;
   flex-wrap: wrap;
-  gap: 1rem;
+  align-items: center;
+  gap: 0.375rem;
 }
 
 .selaras-docs-footer-links a {
   display: inline-flex;
+  min-height: 2.25rem;
+  padding: 0.5rem 0.75rem;
   align-items: center;
   gap: 0.375rem;
   color: var(--selaras-resolved-text-muted);
   font-size: 0.875rem;
   text-decoration: none;
+  border-radius: var(--selaras-resolved-radius-md);
+  transition: color 150ms ease, background-color 150ms ease;
 }
 
 .selaras-docs-footer-links a:hover {
   color: var(--selaras-resolved-text-default);
-  text-decoration: underline;
+  background: var(--selaras-resolved-surface-elevated);
+}
+
+.selaras-docs-footer-links a:focus-visible {
+  outline: 2px solid var(--selaras-resolved-color-primary-fill);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .selaras-docs-footer-links a {
+    transition: none;
+  }
 }
 
 @media (min-width: 64rem) {
@@ -245,8 +265,9 @@
     align-items: flex-start;
     flex-direction: column;
     justify-content: center;
-    padding-top: 1rem;
-    padding-bottom: 1rem;
+    gap: 0.5rem;
+    padding-top: 1.25rem;
+    padding-bottom: 1.25rem;
   }
 }
 

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.0.1",
+  "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.1",
+    "@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
+}