@sewadah/selaras-docs 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+## v1.0.1
+
+[compare changes](https://github.com/sewadahapp/selaras/compare/selaras-docs-v1.0.0...selaras-docs-v1.0.1)
+
+### 🚀 Enhancements
+
+- **feat(docs):** add Degung theme preset ([9af1f54](https://github.com/sewadahapp/selaras/commit/9af1f54af58d18bd9305ddf944243052bda9a022))
+- **feat(docs):** tint logo with active theme color ([102f525](https://github.com/sewadahapp/selaras/commit/102f5254a553e5c646357307c685816a2147bcf7))
+- **feat(docs):** add Pelog and Slendro theme presets ([90dfe04](https://github.com/sewadahapp/selaras/commit/90dfe04f247ad032cd3f6ef03fca662c46d9f936))
+- **feat:** refine code tree viewer ([ef27831](https://github.com/sewadahapp/selaras/commit/ef2783151a5814abf9ca8711a386e303c1c9ab93))
+- **feat(docs):** add app and navigation config ([9d71ef6](https://github.com/sewadahapp/selaras/commit/9d71ef61209dfb6f3c844a06d62660040cc51a7a))
+- **feat(table):** support hierarchical tree rows ([fee43bb](https://github.com/sewadahapp/selaras/commit/fee43bb3da59299529a89fca97627a233ae54489))
+- **feat(table):** move column filters to popovers ([12d2e88](https://github.com/sewadahapp/selaras/commit/12d2e88bf97776f85257968d3c6bd5c256f887ff))
+- **feat(table):** make column sorting opt-in ([0cd56fb](https://github.com/sewadahapp/selaras/commit/0cd56fb0b6ce5127adf2cb71e2f9180361e5af48))
+- **feat(table):** add row hover and click selection ([2dd2a7c](https://github.com/sewadahapp/selaras/commit/2dd2a7cf62ea1f40b575ecc7534cb9ac11b8dada))
+- **feat(dropdown):** add adaptive mobile mode ([6403583](https://github.com/sewadahapp/selaras/commit/640358314fb706ee0a3eb59ebb6ca8de48a244eb))
+- **feat(timeline):** add timeline component ([92438fe](https://github.com/sewadahapp/selaras/commit/92438fe10284ce9cdb7467b277f01d89fc904d28))
+- **feat:** add keyboard shortcuts to menu items ([748a869](https://github.com/sewadahapp/selaras/commit/748a8696c124d7423c52696af4f85e483c484bcc))
+- **feat(toast):** add positioning and stack controls ([9ff6a45](https://github.com/sewadahapp/selaras/commit/9ff6a45b78a47a857cbdfe4ebba19d50799e5aa7))
+- **feat(code-group):** show icons in tabs ([be3f024](https://github.com/sewadahapp/selaras/commit/be3f024557ec4422ece61b685920230b67c6f14b))
+- **feat(docs):** add temporary logo ([18bf96f](https://github.com/sewadahapp/selaras/commit/18bf96f8b78630413d27694719f54bd71dd7063c))
+- **feat(docs):** place header navigation beside the brand ([cdf95ef](https://github.com/sewadahapp/selaras/commit/cdf95ef5afcff595cc70fa5b268d661d2cde713a))
+- **feat(docs):** add brand override points and a favicon option ([78a1ac7](https://github.com/sewadahapp/selaras/commit/78a1ac72b4a95056aea1835c4a4cea2acf035b98))
+- **feat(directives):** add v-mask input masking ([bf93ddc](https://github.com/sewadahapp/selaras/commit/bf93ddc40c99f94420f212a4b4e6a564a7fed039))
+- **feat(overlay):** expose arrow and positioning controls ([7a89248](https://github.com/sewadahapp/selaras/commit/7a892487dd295754f1c662ca38fae874e39b9d77))
+- **feat(overlay):** support configurable arrows ([2606363](https://github.com/sewadahapp/selaras/commit/2606363651be8ca712da9e821f648c1146de22c8))
+- **feat(form-field):** add floating labels and grouped examples ([d5f8c9c](https://github.com/sewadahapp/selaras/commit/d5f8c9cce09348b675bdb8236ee38a75fe14f835))
+- **feat(calendar):** add composable schedule examples ([fc85fd0](https://github.com/sewadahapp/selaras/commit/fc85fd0393f8e3254f5737a769a99a9fa5aa3b5b))
+- **feat(theme):** use white text for light intent fills ([f382884](https://github.com/sewadahapp/selaras/commit/f382884f7d07817e9794e12cd0a6b98440959e13))
+- **feat(tabs):** add scrolling, vertical layout, and panel retention ([5b86c32](https://github.com/sewadahapp/selaras/commit/5b86c32b82b5464079a15348d159c755ba70c815))
+- **feat(docs):** add default powered by footer ([5a9b881](https://github.com/sewadahapp/selaras/commit/5a9b881d07195a4403f3ea1def943d666bd6dcd2))
+- **feat(release):** ship a changelog with the docs layer ([8fe893c](https://github.com/sewadahapp/selaras/commit/8fe893c5ca44334e34107e05e761e10eaa3938bd))
+
+### 🩹 Fixes
+
+- **fix(docs):** enable default page navigation ([cf07fbb](https://github.com/sewadahapp/selaras/commit/cf07fbb8fc9fa719861d528c366df3e4b1956ff1))
+- **fix(toast):** layer toasts into a scaled stack with enter and exit motion ([9e0f922](https://github.com/sewadahapp/selaras/commit/9e0f922d79a1e24526ae357c53ef39d42d7ce75d))
+- **fix(code-tree):** follow scoped light and dark themes for syntax colors ([a98c8fb](https://github.com/sewadahapp/selaras/commit/a98c8fb4d8be3c703838f8e552f80d6864f60c4d))
+- **fix(dropdown,timeline):** route new layout classes through the theme and class prefix ([08c65d6](https://github.com/sewadahapp/selaras/commit/08c65d6e4aa48034f5380c1c4978f8c6235d9228))
+- **fix(dropdown):** keep adaptive trigger aria in sync after a resize ([15d1a59](https://github.com/sewadahapp/selaras/commit/15d1a5974f5decbf54993eff900236e59b76cdd8))
+- **fix(table):** limit row hover to body rows ([16762ec](https://github.com/sewadahapp/selaras/commit/16762eccebb19fc407bbe485b4e15319352b72c9))
+- **fix(navigation-menu):** bind item hotkeys page-wide like other menus ([5bbc6d5](https://github.com/sewadahapp/selaras/commit/5bbc6d5c7873d63a404c28d46ed2ca0c519be491))
+- **fix(hotkey):** match shifted symbols and option chords ([b7a5acb](https://github.com/sewadahapp/selaras/commit/b7a5acb4524b808621602d875cc07f30857c9a9d))
+- **fix(menus):** keep shortcut hints inside item slots ([bcffe01](https://github.com/sewadahapp/selaras/commit/bcffe01d1468fa0e9d9f05f337cab60a1ac862c7))
+- **fix(dropdown):** keep disabled mobile link items inert ([c0a5c86](https://github.com/sewadahapp/selaras/commit/c0a5c86e19da37f9a3343836c0e33ae8acdaf377))
+- **fix(code-tree):** ignore highlights for a file no longer selected ([40136c2](https://github.com/sewadahapp/selaras/commit/40136c2645431e8abdfaf96096e643c0712ebe88))
+- **fix(toast):** make stacking the documented default ([0ae4f40](https://github.com/sewadahapp/selaras/commit/0ae4f40adf7dce709acda188ac8c516cbe3b1c74))
+- **fix(docs):** theme native scrollbars ([5903f0f](https://github.com/sewadahapp/selaras/commit/5903f0f5eb6968b90b7acd5bb84b18ab8539c8a7))
+- **fix(docs):** show navigation menu flyouts ([9330c39](https://github.com/sewadahapp/selaras/commit/9330c3983c5da84999e70ec4642f862b0e1905af))
+- **fix(docs):** hide the search shortcut hint on small screens ([ec811bd](https://github.com/sewadahapp/selaras/commit/ec811bdda58027271ca573c0b0424ca9964b6f1c))
+- **fix(calendar):** key weekday headers by index ([94943d6](https://github.com/sewadahapp/selaras/commit/94943d62ed23a1183459d885a00e418e7ac3ae0f))
+- **fix(tabs):** scroll a controlled tab into view once ([80aaeae](https://github.com/sewadahapp/selaras/commit/80aaeae41f1dd698d4c18a8eb89ceb446f70a957))
+- **fix(autocomplete):** select after home/end navigation ([12259f4](https://github.com/sewadahapp/selaras/commit/12259f45777d9b81c9173ac12d610c1f7c7a34ad))
+- **fix(toast):** skip toasts added during server render ([8995cb4](https://github.com/sewadahapp/selaras/commit/8995cb47ffbcc7a8db6a084d4846241a605ca6e6))
+- **fix(date-picker):** skip form submission while disabled ([9330b38](https://github.com/sewadahapp/selaras/commit/9330b385516a1eb5d5bfbd2d0050fa0159ae224f))
+- **fix(color-picker):** keep one trigger mounted and respect form state ([2f7bd82](https://github.com/sewadahapp/selaras/commit/2f7bd828fc5a2fb52ef9debac569436c48098fc2))
+- **fix(directives):** rewrite v-mask without a third-party dependency ([9d91636](https://github.com/sewadahapp/selaras/commit/9d916365673192190dafafed529f16662bfeb169))
+- **fix(autocomplete):** improve multiple selection behavior ([66c8a86](https://github.com/sewadahapp/selaras/commit/66c8a86d03f05b87a59fc6fafe583ce4ad6fb68f))
+- **fix(color-picker):** align popover to trigger start ([28c39a3](https://github.com/sewadahapp/selaras/commit/28c39a3381e9c82401422df41717e5ec5e889c81))
+- **fix(calendar):** keep default grid compact ([4962470](https://github.com/sewadahapp/selaras/commit/4962470e46f40314d77b76e01cddc14234ffe74f))
+- **fix(docs):** keep centered header sticky ([0bf8504](https://github.com/sewadahapp/selaras/commit/0bf8504baec22426273b49a78376244cb2d72452))
+- **fix(docs):** preserve full width rules and layer hmr ([94ec893](https://github.com/sewadahapp/selaras/commit/94ec89321f9205ccb4a77bcc63116a3d51db4e8a))
+
+### 📖 Documentation
+
+- **docs(toast):** add a live position example ([8b2cc7d](https://github.com/sewadahapp/selaras/commit/8b2cc7d0a9f2e7b774b99e78de28b7039813aea7))
+- **docs:** add a landing page with a live theming demo ([3d456c7](https://github.com/sewadahapp/selaras/commit/3d456c7eaa932e4d7fd7f5feff4795e720b63559))
+- **docs:** add the selaras logo and favicon ([7bd2e9f](https://github.com/sewadahapp/selaras/commit/7bd2e9fe9b368cfe0ab7f10023d86b05ee8bd66c))
+- **docs(directives):** drop plain Vue usage notes ([b6b514e](https://github.com/sewadahapp/selaras/commit/b6b514e7838e7772a9629e6ade52e11bd9928053))
+- **docs:** highlight theme source snippets ([de7519c](https://github.com/sewadahapp/selaras/commit/de7519c42f31778abe1282f2345c2f2c9a15ce19))
+- **docs:** clarify square button example ([349ea36](https://github.com/sewadahapp/selaras/commit/349ea36d546da40121606f054f884aa8fed9d25a))
+- **docs:** rename blocks group to composites ([e14a727](https://github.com/sewadahapp/selaras/commit/e14a727ace5ff2a73d607f2098679612f699d468))
+
+### 🤖 Other changes
+
+- **test:** align packed checks with component defaults ([75c3eb9](https://github.com/sewadahapp/selaras/commit/75c3eb9beff0d45bacbc2af5402002679ddb938b))
+- **test(docs):** align packed consumer content schema ([818cce7](https://github.com/sewadahapp/selaras/commit/818cce7f38d8ae0b5a22dadefe771dbd74a78edf))
+- **test(compat):** allow unprefixed CSS size variance ([f55d537](https://github.com/sewadahapp/selaras/commit/f55d537a866ee75cab8641635307ca447cbe454f))
+- **ci(docs):** add standalone pages deployment ([f322dcb](https://github.com/sewadahapp/selaras/commit/f322dcb1140023ce8a699ee5c2a91637ed5db439))
+- **test(compat):** align packed CSS budgets ([cdced95](https://github.com/sewadahapp/selaras/commit/cdced95b46a92f5b5fd299839734b8b25c53eeb2))
+- **test(css):** raise the prefixed stylesheet budget ([d501562](https://github.com/sewadahapp/selaras/commit/d50156269478e9bf13b60cb586f9fe7dd15ceab3))
+- **style:** fix lint errors from recent changes ([9e7054c](https://github.com/sewadahapp/selaras/commit/9e7054cb0d9d8d13da63bca5b012ac0ed00e1130))
+- **style(toast):** refine semantic toast styling ([dd879f6](https://github.com/sewadahapp/selaras/commit/dd879f69be398ad314b5012bee70fe3ccd6eb3b4))
+- **style(docs):** refine dark modal scrim and docs header ([5cd1e22](https://github.com/sewadahapp/selaras/commit/5cd1e2269d8b0d3325afde39e74954273a5ae7a7))
+- **ci:** use npm trusted publishing ([e5f3dd7](https://github.com/sewadahapp/selaras/commit/e5f3dd7bb4c726ff708363d2b2c75defb6918caf))
+- **style(callout):** match alert surface ([0269454](https://github.com/sewadahapp/selaras/commit/0269454b6a2c9372b2e3b55ec015b7ecf436dc7e))
+- **style(docs):** enlarge the brand name and search button ([e49a97d](https://github.com/sewadahapp/selaras/commit/e49a97d42ddb7e30d1bfeedc511caa77292a7da7))
+- **test(form-library):** scope the date cell click to the picker ([4644ae6](https://github.com/sewadahapp/selaras/commit/4644ae699fe6c803e725278f63921f61638bf5b2))
+- **test(compat):** fix packed consumer checks ([7e9d501](https://github.com/sewadahapp/selaras/commit/7e9d501ebc8902f6a362fad631ef30bfd33dcdab))
+- **test(css):** update prefixed stylesheet budget ([122133f](https://github.com/sewadahapp/selaras/commit/122133f0759e0147380c38ba6cd636c84c0051f2))
+- **style(docs):** remove sidebar border ([864d33c](https://github.com/sewadahapp/selaras/commit/864d33cfb6564b3b4521bead9b24320d874b9d68))
+- **style(tabs):** refine pill variant ([09b9ee6](https://github.com/sewadahapp/selaras/commit/09b9ee600f3b5f053774e400d0c9aaea5a5fed7b))
+- **style(docs):** constrain header and footer shells ([723afe6](https://github.com/sewadahapp/selaras/commit/723afe6b1dc90da72cff5a403a18d4c4c7a3958a))
+- **style(docs):** center header and footer content ([3ec7f9c](https://github.com/sewadahapp/selaras/commit/3ec7f9cdd03975037e6658bbe96b9e01e5abc1e3))
+
+Published against `@sewadah/selaras` ^0.3.1.
+
+## v1.0.0
+
+First tagged release of the documentation layer, published against `@sewadah/selaras` ^0.3.0.
+
+The itemized history leading up to this release lives in the [core changelog](https://github.com/sewadahapp/selaras/blob/main/CHANGELOG.md) - every `docs:` and `docs-layer:` change shipped through the core release stream until the layer gained its own version.

package/README.md

@@ -47,12 +47,21 @@ export default defineAppConfig({
     site: {
       name: 'My project',
       description: 'Documentation for my project.',
+      titleTemplate: '%s · My project',
+      url: 'https://example.com',
+      // Files in public/. Use one path, or separate light and dark images.
+      // `tint: true` colors a monochrome SVG with the active primary theme color.
+      logo: { light: '/logo.svg', dark: '/logo-dark.svg', tint: true },
+      favicon: '/favicon.svg',
     },
     repository: {
       url: 'https://github.com/example/project',
       editLinks: true,
     },
     header: {
+      search: true,
+      colorMode: true,
+      fluid: false,
       links: [
         { label: 'Guide', to: '/guide/getting-started' },
         {
@@ -64,12 +73,52 @@ export default defineAppConfig({
         },
       ],
     },
+    main: { fluid: false, padded: true },
+    sidebar: {
+      enabled: true,
+      collapsed: false,
+      exclude: ['/internal/draft'],
+    },
+    toc: { enabled: true, title: 'On this page' },
+    footer: { text: '© 2026 My project', fluid: false },
   },
 })
 ```
 
+Folder navigation can be configured with a `.navigation.yml` file alongside
+the Markdown pages in that folder:
+
+```yaml
+title: Getting started
+icon: hugeicons:rocket
+order: 1
+collapse: false
+navBadges:
+  - New
+```
+
+Use `navigation: false` in a page's frontmatter to omit it from navigation, or
+set `navigation` to an object to override its navigation `title`, `icon`,
+`order`, and `navBadges`. Page frontmatter can also set `toc: false`,
+`aside: false`, `editLink: false`, or `prevNext: false` to hide those parts of
+the page shell. The sidebar also accepts an app-wide `collapsed` default; a
+folder's `collapse` value takes precedence. `main.fluid` expands the
+content width, `main.padded: false` removes its outer inset, and `header.fluid`
+and `footer.fluid` allow those regions to span the viewport.
+
 Create an application component with the same name as a layer component, such
-as `components/DocsHeader.vue`, to replace that part of the shell. For a host
-that owns Tailwind compilation or uses a class prefix, set
+as `components/DocsHeader.vue`, to replace that part of the shell. Smaller
+pieces can be replaced on their own:
+
+| Component | Controls | Default |
+| --- | --- | --- |
+| `DocsHeaderBrand` | The header's home link content | `site.logo` and the site name |
+| `DocsFooterBrand` | The start of the footer | `footer.text` |
+| `DocsLogo` | The logo image, used by `DocsHeaderBrand` | `site.logo`, switching light/dark; size it with `--selaras-docs-logo-height` |
+
+For example, a `components/DocsFooterBrand.vue` containing `<DocsLogo />` adds
+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.

package/app/app.config.ts

@@ -12,11 +12,30 @@ export default defineAppConfig({
       showTitle: true,
       search: true,
       colorMode: true,
+      fluid: false,
+    },
+    main: {
+      fluid: false,
+      padded: true,
+    },
+    sidebar: {
+      enabled: true,
+      collapsed: false,
     },
     toc: {
       enabled: true,
       title: 'On this page',
     },
-    footer: {},
+    footer: {
+      fluid: false,
+      links: [
+        {
+          label: 'Powered by Selaras',
+          to: 'https://sewadahapp.github.io/selaras',
+          target: '_blank',
+          rel: 'noreferrer',
+        },
+      ],
+    },
   },
 })

package/app/app.vue

@@ -1,3 +1,15 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const assetUrl = useDocsAssetUrl()
+
+useHead(() => {
+  const favicon = assetUrl(appConfig.selarasDocs?.site?.favicon)
+  return {
+    link: favicon ? [{ rel: 'icon', href: favicon, type: favicon.endsWith('.svg') ? 'image/svg+xml' : undefined }] : [],
+  }
+})
+</script>
+
 <template>
   <SApp>
     <NuxtLayout>
@@ -5,6 +17,7 @@
     </NuxtLayout>
     <ClientOnly>
       <DocsSearch />
+      <SToast />
     </ClientOnly>
   </SApp>
 </template>

package/app/assets/style.css

@@ -4,8 +4,19 @@
   color: inherit;
 }
 
+:root {
+  color-scheme: light;
+  background: var(--selaras-resolved-surface-canvas, var(--selaras-resolved-surface-default));
+  scrollbar-color: var(--selaras-resolved-border-default) var(--selaras-resolved-surface-canvas, var(--selaras-resolved-surface-default));
+}
+
+:root.dark {
+  color-scheme: dark;
+}
+
 .selaras-docs-root {
   background: var(--selaras-resolved-surface-canvas, var(--selaras-resolved-surface-default));
+  scrollbar-color: var(--selaras-resolved-border-default) var(--selaras-resolved-surface-canvas, var(--selaras-resolved-surface-default));
 }
 
 .selaras-docs-skip-link {
@@ -27,6 +38,49 @@
   outline-offset: 2px;
 }
 
+/* Match the main documentation shell's centered width. */
+.selaras-docs-header {
+  position: sticky;
+  z-index: 20;
+  top: 0;
+  width: 100%;
+  background: var(--selaras-resolved-surface-canvas, var(--selaras-resolved-surface-default));
+  border-bottom: 0;
+}
+
+.selaras-docs-header-inner {
+  box-sizing: border-box;
+  width: min(100%, 90rem);
+  min-width: 0;
+  height: 100%;
+  margin-inline: auto;
+  padding-inline: 1.5rem;
+}
+
+.selaras-docs-header-inner--fluid {
+  width: 100%;
+}
+
+.selaras-docs-header-actions {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 0.5rem;
+  margin-inline-start: auto;
+}
+
+.selaras-docs-header::after {
+  position: absolute;
+  z-index: 1;
+  inset-inline-start: 50%;
+  bottom: 0;
+  width: 100vw;
+  transform: translateX(-50%);
+  border-bottom: 1px solid var(--selaras-resolved-border-default);
+  content: '';
+  pointer-events: none;
+}
+
 .selaras-docs-shell {
   display: flex;
   width: min(100%, 90rem);
@@ -34,8 +88,8 @@
   margin: 0 auto;
 }
 
-.selaras-docs-sidebar {
-  border-inline-end: 1px solid var(--selaras-resolved-border-default);
+.selaras-docs-root--fluid .selaras-docs-shell {
+  width: 100%;
 }
 
 .selaras-docs-main {
@@ -44,11 +98,19 @@
   padding: 2rem;
 }
 
+.selaras-docs-main--unpadded {
+  padding: 0;
+}
+
 .selaras-docs-page {
   max-width: 78rem;
   margin: 0 auto;
 }
 
+.selaras-docs-page--fluid {
+  max-width: none;
+}
+
 .selaras-docs-page-grid {
   display: grid;
   grid-template-columns: minmax(0, 1fr);
@@ -91,11 +153,31 @@
 }
 
 .selaras-docs-footer {
+  position: relative;
+  width: min(100%, 90rem);
+  margin-inline: auto;
+}
+
+.selaras-docs-footer--fluid {
+  width: 100%;
+}
+
+.selaras-docs-footer::before {
+  position: absolute;
+  inset-inline-start: 50%;
+  top: 0;
+  width: 100vw;
+  transform: translateX(-50%);
   border-top: 1px solid var(--selaras-resolved-border-default);
+  content: '';
+  pointer-events: none;
 }
 
 .selaras-docs-footer-inner {
+  box-sizing: border-box;
   display: flex;
+  width: 100%;
+  padding-inline: 1.5rem;
   align-items: center;
   justify-content: space-between;
   gap: 1rem;
@@ -133,6 +215,14 @@
     display: none;
   }
 
+  /* Reserve the sidebar's width for the brand, so the header menu's first
+     label lines up with the page content: sidebar (16rem) + the content's
+     inset from it (4rem), less the header's own padding (1.5rem), the
+     brand-to-menu gap (0.5rem), and the menu link's own padding (0.625rem). */
+  .selaras-docs-brand-area {
+    min-width: 17.375rem;
+  }
+
   .selaras-docs-page-grid {
     grid-template-columns: minmax(0, 1fr) 14rem;
   }
@@ -143,6 +233,10 @@
     padding: 1.5rem;
   }
 
+  .selaras-docs-main--unpadded {
+    padding: 0;
+  }
+
   .selaras-docs-header-link.selaras-docs-header-link--desktop {
     display: none;
   }
@@ -165,13 +259,25 @@
 
 .selaras-docs-brand {
   gap: 0.625rem;
+  font-size: 1.125rem;
   font-weight: 600;
+  letter-spacing: -0.01em;
 }
 
 .selaras-docs-logo {
   display: block;
   width: auto;
-  height: 1.75rem;
+  height: var(--selaras-docs-logo-height, 1.75rem);
+}
+
+.selaras-docs-logo--tinted {
+  width: var(--selaras-docs-logo-height, 1.75rem);
+  flex: none;
+  background-color: var(--selaras-resolved-color-primary-fill);
+  mask-image: var(--selaras-docs-logo-mask);
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
 }
 
 .selaras-docs-logo--dark {

package/app/components/DocsFooter.vue

@@ -5,17 +5,16 @@ const footer = computed(() => docsConfig.value.footer)
 </script>
 
 <template>
-  <footer v-if="footer?.text || footer?.links?.length" class="selaras-docs-footer">
+  <footer v-if="footer?.text || footer?.links?.length" class="selaras-docs-footer" :class="{ 'selaras-docs-footer--fluid': footer?.fluid }">
     <SContainer size="full" class="selaras-docs-footer-inner">
-      <p v-if="footer?.text" class="selaras-docs-footer-text">
-        {{ footer.text }}
-      </p>
+      <DocsFooterBrand />
       <nav v-if="footer?.links?.length" class="selaras-docs-footer-links" aria-label="Footer navigation">
         <NuxtLink
           v-for="link in footer.links"
           :key="`${link.to}:${link.label ?? link.icon ?? ''}`"
           :to="link.to"
           :target="link.target"
+          :rel="link.rel"
           :aria-label="link.ariaLabel ?? link.label"
         >
           <SIcon v-if="link.icon" :name="link.icon" />

package/app/components/DocsFooterBrand.vue

@@ -0,0 +1,10 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const text = computed(() => appConfig.selarasDocs?.footer?.text)
+</script>
+
+<template>
+  <p v-if="text" class="selaras-docs-footer-text">
+    {{ text }}
+  </p>
+</template>

package/app/components/DocsHeader.vue

@@ -6,14 +6,9 @@ const navigationOpen = ref(false)
 
 const docsConfig = computed(() => appConfig.selarasDocs ?? {})
 const siteName = computed(() => docsConfig.value.header?.title ?? docsConfig.value.site?.name ?? 'Documentation')
-const showTitle = computed(() => docsConfig.value.header?.showTitle !== false)
-const logo = computed(() => docsConfig.value.site?.logo)
-const logoAlt = computed(() => typeof logo.value === 'object' ? (logo.value.alt ?? siteName.value) : siteName.value)
-const lightLogo = computed(() => typeof logo.value === 'string' ? logo.value : (logo.value?.light ?? logo.value?.dark))
-const darkLogo = computed(() => typeof logo.value === 'object' ? (logo.value.dark ?? logo.value.light) : logo.value)
-const hasDistinctLogos = computed(() => Boolean(lightLogo.value && darkLogo.value && lightLogo.value !== darkLogo.value))
 const headerLinks = computed(() => docsConfig.value.header?.links ?? [])
 const repositoryUrl = computed(() => docsConfig.value.repository?.url)
+const sidebarEnabled = computed(() => docsConfig.value.sidebar?.enabled !== false)
 
 watch(() => route.path, () => {
   navigationOpen.value = false
@@ -21,23 +16,28 @@ watch(() => route.path, () => {
 </script>
 
 <template>
-  <SHeader>
-    <NuxtLink to="/" class="selaras-docs-brand" :aria-label="`${siteName} home`">
-      <template v-if="lightLogo">
-        <img :src="lightLogo" :alt="logoAlt" class="selaras-docs-logo" :class="{ 'selaras-docs-logo--light': hasDistinctLogos }">
-        <img v-if="hasDistinctLogos" :src="darkLogo" :alt="logoAlt" class="selaras-docs-logo selaras-docs-logo--dark">
-      </template>
-      <span v-if="showTitle">{{ siteName }}</span>
-    </NuxtLink>
-    <template #right>
-      <SNavigationMenu
-        v-if="headerLinks.length"
-        :items="headerLinks"
-        variant="link"
-        :ui="{ root: 'hidden w-auto lg:flex' }"
-      />
+  <SHeader
+    :ui="{
+      root: 'selaras-docs-header',
+      left: docsConfig.header?.fluid ? 'selaras-docs-header-inner selaras-docs-header-inner--fluid' : 'selaras-docs-header-inner',
+      right: 'hidden',
+    }"
+  >
+    <div class="selaras-docs-brand-area">
+      <NuxtLink to="/" class="selaras-docs-brand" :aria-label="`${siteName} home`">
+        <DocsHeaderBrand />
+      </NuxtLink>
+    </div>
+    <SNavigationMenu
+      v-if="headerLinks.length"
+      :items="headerLinks"
+      variant="link"
+      :ui="{ root: 'hidden w-auto lg:flex' }"
+    />
+    <div class="selaras-docs-header-actions">
       <DocsSearchButton v-if="docsConfig.header?.search !== false" />
       <SColorModeToggle v-if="docsConfig.header?.colorMode !== false" />
+      <DocsThemePicker v-if="docsConfig.header?.themePicker" />
       <SButton
         v-if="repositoryUrl"
         as="a"
@@ -51,6 +51,7 @@ watch(() => route.path, () => {
         color="neutral"
       />
       <SButton
+        v-if="sidebarEnabled"
         variant="ghost"
         color="neutral"
         class="selaras-docs-nav-toggle"
@@ -59,11 +60,11 @@ watch(() => route.path, () => {
       >
         Menu
       </SButton>
-    </template>
+    </div>
   </SHeader>
-  <SDrawer v-model:open="navigationOpen" side="left" title="Documentation navigation" :handle="false">
+  <SDrawer v-if="sidebarEnabled" v-model:open="navigationOpen" side="left" title="Documentation navigation" :handle="false">
     <template #body>
-      <SContentNavigation :navigation="navigation ?? []" />
+      <SContentNavigation :navigation="navigation ?? []" :collapsed="docsConfig.sidebar?.collapsed" />
     </template>
   </SDrawer>
 </template>

package/app/components/DocsHeaderBrand.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+const docsConfig = computed(() => appConfig.selarasDocs ?? {})
+const siteName = computed(() => docsConfig.value.header?.title ?? docsConfig.value.site?.name ?? 'Documentation')
+const showTitle = computed(() => docsConfig.value.header?.showTitle !== false)
+</script>
+
+<template>
+  <DocsLogo />
+  <span v-if="showTitle">{{ siteName }}</span>
+</template>

package/app/components/DocsLogo.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+const logo = useDocsLogo()
+</script>
+
+<template>
+  <template v-if="logo.light">
+    <span
+      v-if="logo.tint"
+      role="img"
+      :aria-label="logo.alt"
+      class="selaras-docs-logo selaras-docs-logo--tinted"
+      :style="{ '--selaras-docs-logo-mask': `url('${logo.light}')` }"
+    />
+    <template v-else>
+      <img :src="logo.light" :alt="logo.alt" class="selaras-docs-logo" :class="{ 'selaras-docs-logo--light': logo.distinct }">
+      <img v-if="logo.distinct" :src="logo.dark" :alt="logo.alt" class="selaras-docs-logo selaras-docs-logo--dark">
+    </template>
+  </template>
+</template>

package/app/components/DocsSearchButton.vue

@@ -5,9 +5,11 @@ const messages = useMessages()
 </script>
 
 <template>
-  <SButton variant="soft" color="neutral" size="sm" :icon="icons.search" aria-label="Search documentation" @click="open">
+  <SButton variant="soft" color="neutral" size="sm" :icon="icons.search" aria-label="Search documentation" class="sm:min-w-48 xl:min-w-60" @click="open">
     <span class="hidden sm:inline">{{ messages.search }}</span>
-    <SKbd value="meta" size="sm" />
-    <SKbd value="K" size="sm" />
+    <span class="ms-auto hidden gap-1 sm:flex">
+      <SKbd value="meta" size="sm" />
+      <SKbd value="K" size="sm" />
+    </span>
   </SButton>
 </template>

package/app/components/DocsSidebar.vue

@@ -1,13 +1,16 @@
 <script setup lang="ts">
+const appConfig = useAppConfig()
 const { data: navigation } = useDocsNavigation()
+const sidebar = computed(() => appConfig.selarasDocs?.sidebar)
 </script>
 
 <template>
   <SPageAside
+    v-if="sidebar?.enabled !== false"
     class="selaras-docs-sidebar"
     aria-label="Documentation navigation"
     :ui="{ root: 'top-16 h-[calc(100vh-4rem)]' }"
   >
-    <SContentNavigation :navigation="navigation ?? []" />
+    <SContentNavigation :navigation="navigation ?? []" :collapsed="sidebar?.collapsed" />
   </SPageAside>
 </template>

package/app/composables/useDocsLogo.ts

@@ -0,0 +1,30 @@
+/**
+ * Prefixes a root-relative path (`/logo.svg`) with the app's base URL, so a
+ * file in `public/` still resolves when the site is served from a subpath.
+ * Absolute URLs and relative paths pass through unchanged.
+ */
+export function useDocsAssetUrl() {
+  const baseURL = useRuntimeConfig().app.baseURL.replace(/\/$/, '')
+  return (path: string | undefined) => path?.startsWith('/') && !path.startsWith('//') ? `${baseURL}${path}` : path
+}
+
+/** The configured `site.logo`, resolved into light/dark image sources. */
+export function useDocsLogo() {
+  const appConfig = useAppConfig()
+  const assetUrl = useDocsAssetUrl()
+
+  return computed(() => {
+    const config = appConfig.selarasDocs ?? {}
+    const logo = config.site?.logo
+    const name = config.header?.title ?? config.site?.name ?? 'Documentation'
+    const light = assetUrl(typeof logo === 'string' ? logo : (logo?.light ?? logo?.dark))
+    const dark = assetUrl(typeof logo === 'string' ? logo : (logo?.dark ?? logo?.light))
+    return {
+      light,
+      dark,
+      alt: typeof logo === 'object' ? (logo.alt ?? name) : name,
+      distinct: Boolean(light && dark && light !== dark),
+      tint: typeof logo === 'object' && logo.tint === true,
+    }
+  })
+}

package/app/composables/useDocsNavigation.ts

@@ -1,4 +1,53 @@
+interface DocsNavigationNode {
+  title: string
+  path: string
+  icon?: string | false
+  order?: number
+  collapse?: boolean
+  navBadges?: Array<string | { text: string }>
+  navigation?: boolean | {
+    title?: string
+    icon?: string | false
+    order?: number
+    navBadges?: Array<string | { text: string }>
+  }
+  children?: DocsNavigationNode[]
+}
+
 export function useDocsNavigation() {
-  return useAsyncData('selaras-docs-navigation', () =>
-    queryCollectionNavigation('docs').order('order', 'ASC'))
+  const appConfig = useAppConfig()
+
+  return useAsyncData('selaras-docs-navigation', async () => {
+    const tree = await queryCollectionNavigation('docs', ['order', 'icon', 'collapse', 'navBadges'])
+      .order('order', 'ASC')
+
+    const excluded = new Set(appConfig.selarasDocs?.sidebar?.exclude ?? [])
+    const visit = (items: DocsNavigationNode[], applyExclusions = false): DocsNavigationNode[] => items
+      .filter(item => !applyExclusions || !excluded.has(item.path))
+      .map((item) => {
+        const metadata = typeof item.navigation === 'object' && item.navigation ? item.navigation : {}
+        const children = item.children ? visit(item.children, applyExclusions) : undefined
+        return {
+          ...item,
+          ...metadata,
+          title: metadata.title ?? item.title,
+          icon: metadata.icon ?? item.icon,
+          order: metadata.order ?? item.order,
+          navBadges: metadata.navBadges ?? item.navBadges,
+          ...(children && { children }),
+        }
+      })
+      .filter(item => !applyExclusions || !item.children || item.children.length > 0)
+      .sort((a, b) => {
+        if (a.order == null && b.order == null)
+          return 0
+        if (a.order == null)
+          return 1
+        if (b.order == null)
+          return -1
+        return a.order - b.order
+      })
+
+    return visit(tree as DocsNavigationNode[], excluded.size > 0)
+  })
 }

package/app/layouts/selaras-docs.vue

@@ -1,10 +1,24 @@
+<script setup lang="ts">
+const appConfig = useAppConfig()
+</script>
+
 <template>
-  <div class="selaras-docs-root min-h-screen text-[var(--selaras-resolved-text-default)]">
+  <div
+    class="selaras-docs-root min-h-screen text-[var(--selaras-resolved-text-default)]"
+    :class="{
+      'selaras-docs-root--fluid': appConfig.selarasDocs?.main?.fluid,
+    }"
+  >
     <a class="selaras-docs-skip-link" href="#selaras-docs-main">Skip to content</a>
     <DocsHeader />
     <div class="selaras-docs-shell">
       <DocsSidebar />
-      <main id="selaras-docs-main" class="selaras-docs-main" tabindex="-1">
+      <main
+        id="selaras-docs-main"
+        class="selaras-docs-main"
+        :class="{ 'selaras-docs-main--unpadded': appConfig.selarasDocs?.main?.padded === false }"
+        tabindex="-1"
+      >
         <slot />
       </main>
     </div>

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

@@ -18,6 +18,12 @@ if (!page.value) {
 
 definePageMeta({ layout: 'selaras-docs' })
 useSeoMeta({ title: page.value.title, description: page.value.description ?? appConfig.selarasDocs?.site?.description })
+useHead(() => ({
+  ...(appConfig.selarasDocs?.site?.titleTemplate && { titleTemplate: appConfig.selarasDocs.site.titleTemplate }),
+  ...(appConfig.selarasDocs?.site?.url && {
+    link: [{ rel: 'canonical', href: new URL(route.path, appConfig.selarasDocs.site.url).href }],
+  }),
+}))
 
 const proseComponents = {
   h1: ProseH1,
@@ -34,17 +40,22 @@ const surround = useDocsSurround()
 </script>
 
 <template>
-  <SContainer size="full" class="selaras-docs-page">
+  <SContainer 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">
           {{ page!.description }}
         </p>
         <ContentRenderer :value="page!" :components="proseComponents" class="selaras-docs-content selaras-prose" />
-        <DocsEditLink :path="route.path" />
-        <SContentSurround :prev="surround.prev" :next="surround.next" class="selaras-docs-surround" />
+        <DocsEditLink v-if="page!.editLink !== false" :path="route.path" />
+        <SContentSurround
+          v-if="page!.prevNext !== false"
+          :prev="surround.prev"
+          :next="surround.next"
+          class="selaras-docs-surround"
+        />
       </article>
-      <DocsTableOfContents :links="tocLinks" />
+      <DocsTableOfContents v-if="page!.toc !== false && page!.aside !== false" :links="tocLinks" />
     </div>
   </SContainer>
 </template>

package/content.config.ts

@@ -8,12 +8,41 @@ export default defineContentConfig({
   collections: {
     docs: defineCollection({
       type: 'page',
-      source: {
-        cwd: resolve(options.rootDir, 'content'),
-        include: '**/*.md',
-      },
+      source: [
+        {
+          cwd: resolve(options.rootDir, 'content'),
+          include: '**/*.md',
+        },
+        {
+          cwd: resolve(options.rootDir, 'content'),
+          // Nuxt Content reads this metadata into the navigation tree.
+          include: '**/.navigation.yml',
+        },
+      ],
       schema: z.object({
         order: z.number().optional(),
+        icon: z.union([z.string(), z.literal(false)]).optional(),
+        collapse: z.boolean().optional(),
+        navBadges: z.array(z.union([
+          z.string(),
+          z.object({ text: z.string() }),
+        ])).optional(),
+        navigation: z.union([
+          z.boolean(),
+          z.object({
+            title: z.string().optional(),
+            icon: z.union([z.string(), z.literal(false)]).optional(),
+            order: z.number().optional(),
+            navBadges: z.array(z.union([
+              z.string(),
+              z.object({ text: z.string() }),
+            ])).optional(),
+          }),
+        ]).optional(),
+        toc: z.boolean().default(true),
+        aside: z.boolean().default(true),
+        editLink: z.boolean().default(true),
+        prevNext: z.boolean().default(true),
       }),
     }),
   },

package/nuxt.config.mjs

@@ -8,6 +8,16 @@ export default defineNuxtConfig({
   // Selaras supports Node versions with node:sqlite. Keeping Content on its
   // native connector lets an installed docs layer avoid a native addon.
   content: {
+    // Include h3 headings in the docs sidebar TOC; Nuxt Content defaults to
+    // including headings through h2 only.
+    build: {
+      markdown: {
+        toc: {
+          depth: 3,
+          searchDepth: 3,
+        },
+      },
+    },
     experimental: {
       sqliteConnector: 'native',
     },

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@sewadah/selaras-docs",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Nuxt Content documentation layer for Selaras",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sewadahapp/selaras.git",
+    "directory": "packages/docs"
+  },
   "exports": {
     ".": {
       "types": "./types.d.ts",
@@ -12,6 +17,7 @@
   },
   "main": "./nuxt.config.mjs",
   "files": [
+    "CHANGELOG.md",
     "app",
     "content.config.ts",
     "modules",
@@ -27,7 +33,7 @@
   "dependencies": {
     "@nuxt/content": "^3.16.0",
     "@nuxt/kit": "^4.5.2",
-    "@sewadah/selaras": "^0.3.0",
+    "@sewadah/selaras": "^0.3.1",
     "tailwindcss": "^4.3.0"
   }
 }

package/types.d.ts

@@ -12,6 +12,7 @@ export interface SelarasDocsLink {
   to: string
   icon?: string
   target?: string
+  rel?: string
   ariaLabel?: string
 }
 
@@ -32,13 +33,21 @@ export interface SelarasDocsLogo {
   light?: string
   dark?: string
   alt?: string
+  /** Tint a monochrome SVG with the active primary theme color. */
+  tint?: boolean
 }
 
 export interface SelarasDocsAppConfig {
   site?: {
     name?: string
     description?: string
+    /** Applied to browser titles; `%s` is replaced with the current page title. */
+    titleTemplate?: string
+    url?: string
+    /** Shown in the header and footer. A `/`-rooted path is served from `public/` under the app's base URL. */
     logo?: string | SelarasDocsLogo
+    /** The browser tab icon, e.g. `/favicon.svg`, resolved like `logo`. */
+    favicon?: string
   }
   repository?: {
     url?: string
@@ -51,8 +60,26 @@ export interface SelarasDocsAppConfig {
     showTitle?: boolean
     search?: boolean
     colorMode?: boolean
+    /** Show the consuming site's visual preset picker. @default false */
+    themePicker?: boolean
+    /** Let the header span the viewport instead of the docs shell width. */
+    fluid?: boolean
     links?: SelarasDocsNavigationItem[]
   }
+  main?: {
+    /** Let the content area use the available width. @default false */
+    fluid?: boolean
+    /** Remove the default content inset. @default false */
+    padded?: boolean
+  }
+  sidebar?: {
+    /** Hide the desktop sidebar and its mobile navigation control. @default true */
+    enabled?: boolean
+    /** Start folder groups collapsed. Folder `.navigation.yml` can override this. @default false */
+    collapsed?: boolean
+    /** Exact page paths to omit from the sidebar. */
+    exclude?: string[]
+  }
   toc?: {
     enabled?: boolean
     title?: string
@@ -60,9 +87,20 @@ export interface SelarasDocsAppConfig {
   footer?: {
     text?: string
     links?: SelarasDocsLink[]
+    /** Let the footer span the viewport instead of the docs shell width. */
+    fluid?: boolean
   }
 }
 
+/** Metadata accepted in a content page's `.navigation.yml` folder config. */
+export interface SelarasDocsContentNavigationItem {
+  title?: string
+  icon?: string | false
+  order?: number
+  collapse?: boolean
+  navBadges?: Array<string | { text: string }>
+}
+
 declare module '@nuxt/schema' {
   interface AppConfig {
     selarasDocs?: SelarasDocsAppConfig