@uxfront/layer-docs 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @uxfront/layer-docs
 
-The Nuxt layer for UXFront's documentation sites. It extends [Docus](https://docus.dev), which renders the markdown in `content/docs/` with a header, sidebar, search and table of contents, and adds a framework switcher: every reader sees the examples for their framework, on every page.
+The Nuxt layer for UXFront's documentation sites. It extends [Docus](https://docus.dev), which renders the markdown in `content/docs/` with a header, sidebar, search and table of contents, and adds a framework switcher: every reader sees the examples for their framework, on every page. It can also set the header's site name the way the UXFront homepages do, signed "by UXFront".
 
 ## Install
 
@@ -32,6 +32,23 @@ export default defineAppConfig({
 
 `value` is the slot name pages write each framework's examples in, and `icon` any [Iconify](https://icones.js.org) icon. The layer ships no default list, so with none, the switcher and the select render nothing.
 
+## The header wordmark
+
+Docus prints the site name in the header as plain text. Set `docsTheme.wordmark` to write it the way the UXFront homepages do, one part bold, and `docsTheme.byline` to sign it "by UXFront", linked to uxfront.com:
+
+```ts
+// app/app.config.ts
+export default defineAppConfig({
+  docsTheme: {
+    // **Open**Components
+    wordmark: { bold: "Open", regular: "Components" },
+    byline: true,
+  },
+});
+```
+
+The wordmark links home, and its accessible name is Docus's `header.title`, or the site name. The byline sits beside the link, not inside it, and phones leave it out so the header's buttons keep their room. With neither set, the header shows Docus's own title or logo.
+
 ## Writing examples
 
 Put one slot per framework in a `::framework-switcher`:
@@ -57,6 +74,7 @@ export const Button = () => <button>Save</button>;
 
 - **`FrameworkSwitcher`.** One tab per framework, on Nuxt UI's tabs, so it follows the WAI-ARIA tabs pattern (arrow keys between tabs, panels labelled by their tab). A page doesn't have to cover every framework: a missing one shows the first one the page has, with a note saying so. When the tabs outgrow the width, the list scrolls.
 - **A Framework select above the sidebar.** It replaces Docus's `DocsAsideLeftTop` and renders Docus's below it.
+- **A header wordmark and byline.** It replaces Docus's `AppHeaderLeft`, and renders Docus's unless the app sets a wordmark.
 - **`useFramework()`.** The reader's pick, shared by every switcher and the select, and kept in `localStorage` across visits. It's read once the page is mounted, so the prerendered HTML shows the default framework and hydrates cleanly.
 - **Bundled icons.** Nuxt Icon bundles the icons named in app config too, so the select's icons don't come from the Iconify API.
 

package/app/components/app/AppHeaderLeft.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+// Replaces Docus's, which prints the site name as plain text, to set the app's
+// wordmark (`docsTheme.wordmark`) and sign it "by UXFront" (`docsTheme.byline`),
+// the way the UXFront homepage headers do. With neither, it renders Docus's own.
+import UxFrontMark from "@uxfront/ui/components/icons/UxFrontMark.vue";
+import DocusAppHeaderLeft from "docus/app/components/app/AppHeaderLeft.vue";
+
+const appConfig = useAppConfig();
+const site = useSiteConfig();
+const { localePath } = useDocusI18n();
+
+const wordmark = computed(() => appConfig.docsTheme.wordmark);
+const ariaLabel = computed(() => appConfig.header?.title || site.name);
+</script>
+
+<template>
+  <div class="docs-header-left">
+    <NuxtLink v-if="wordmark" :to="localePath('/')" :aria-label="ariaLabel" class="docs-wordmark">
+      <strong>{{ wordmark.bold }}</strong
+      >{{ wordmark.regular }}
+    </NuxtLink>
+    <DocusAppHeaderLeft v-else />
+    <!-- Beside the home link, not inside it, since it holds a link of its own. -->
+    <span v-if="appConfig.docsTheme.byline" class="docs-byline">
+      by
+      <a href="https://uxfront.com">
+        <UxFrontMark />
+        <span><strong>UX</strong>Front</span>
+      </a>
+    </span>
+  </div>
+</template>
+
+<style scoped>
+/* Styled here rather than with Tailwind utilities: Docus's stylesheet doesn't
+   list this layer among Tailwind's sources, so only utilities Docus happens to
+   use itself would be generated. */
+.docs-header-left {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-width: 0;
+}
+
+.docs-wordmark {
+  flex-shrink: 0;
+}
+
+/* Phones leave the byline out: beside the header's buttons, it pushes the menu
+   toggle off-screen. */
+.docs-byline {
+  display: none;
+  align-items: center;
+  gap: 0.375rem;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  white-space: nowrap;
+  color: var(--ui-text-muted);
+}
+
+.docs-byline a {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  font-weight: 500;
+  color: var(--ui-text-toned);
+  transition: color 0.15s;
+}
+
+.docs-byline a:hover {
+  color: var(--ui-text-highlighted);
+}
+
+.docs-byline svg {
+  width: 0.875rem;
+  height: 0.875rem;
+}
+
+@media (min-width: 40rem) {
+  .docs-byline {
+    display: inline-flex;
+  }
+}
+</style>

package/app/composables/useFramework.ts

@@ -12,11 +12,24 @@ export interface FrameworkOption {
   icon: string;
 }
 
+/**
+ * The site name in the docs header, as the UXFront homepages set it: one part
+ * bold, then the rest, as in **Open**Components.
+ */
+export interface DocsWordmark {
+  bold: string;
+  regular: string;
+}
+
 declare module "nuxt/schema" {
   interface AppConfigInput {
     docsTheme?: {
       /** The frameworks the docs' examples come in, in display order. The first is the default. */
       frameworks?: FrameworkOption[];
+      /** The header's site name, in place of Docus's plain-text title. */
+      wordmark?: DocsWordmark;
+      /** Signs the header's site name "by UXFront", linked to uxfront.com. */
+      byline?: boolean;
     };
   }
 }

package/nuxt.config.ts

@@ -5,7 +5,9 @@
  * search and table of contents, and adds a framework switcher on top: a
  * `::framework-switcher` content component with one slot per framework, and a
  * Framework select above the sidebar. The app lists its frameworks in
- * `docsTheme.frameworks` in its `app.config.ts`.
+ * `docsTheme.frameworks` in its `app.config.ts`. It can also set the header's
+ * site name as a wordmark, signed "by UXFront" (`docsTheme.wordmark` and
+ * `docsTheme.byline`).
  *
  * https://nuxt.com/docs/getting-started/layers
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uxfront/layer-docs",
-  "version": "0.5.0",
-  "description": "Nuxt layer for UXFront documentation sites: Docus, plus a framework switcher that shows every reader the examples for their framework.",
+  "version": "0.6.0",
+  "description": "Nuxt layer for UXFront documentation sites: Docus, plus a framework switcher that shows every reader the examples for their framework, and the UXFront header wordmark.",
   "keywords": [
     "docs",
     "documentation",
@@ -36,6 +36,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@uxfront/ui": "^0.4.1",
     "@vueuse/core": "^14.4.0",
     "docus": "^5.13.0"
   },