@uxfront/layer-docs 0.6.0 → 0.7.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. It can also set the header's site name the way the UXFront homepages do, signed "by UXFront".
+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 picks their framework once, and sees its examples on every page. It can also set the header's site name the way the UXFront homepages do, signed "by UXFront".
 
 ## Install
 
@@ -70,12 +70,29 @@ export const Button = () => <button>Save</button>;
 ::
 ````
 
+It shows the code for the reader's framework. Docus only highlights a few languages (Vue, TypeScript, HTML, CSS, …), so the layer adds `tsx`, `svelte`, `angular-html`, `angular-ts` and `astro`. Add any other your examples need in the app's `nuxt.config.ts`:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  content: {
+    build: {
+      markdown: {
+        highlight: { langs: ["jsx"] },
+      },
+    },
+  },
+});
+```
+
 ## What it adds
 
-- **`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 Framework select above the sidebar.** It picks the framework for the whole site, and lines up with the navigation's pages below it. It replaces Docus's `DocsAsideLeftTop` and renders Docus's below it.
+- **The same select in the header's menu.** On smaller screens, where Docus hides the sidebar, the menu that stands in for it starts with the select. It replaces Docus's `AppHeaderBody` and renders Docus's below it.
+- **`FrameworkSwitcher`.** It shows the slot for the reader's framework, with no tabs of its own, since the select already picks one for every page. A page doesn't have to cover every framework: a missing one shows the first one the page has, with a note saying so.
 - **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.
+- **Highlighting for the frameworks' languages.** `tsx`, `svelte`, `angular-html`, `angular-ts` and `astro`, on top of Docus's.
 - **Bundled icons.** Nuxt Icon bundles the icons named in app config too, so the select's icons don't come from the Iconify API.
 
 Everything else is Docus's: configure it as its [docs](https://docus.dev) describe.

package/app/components/app/AppHeaderBody.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+// Replaces Docus's to put the framework select above the navigation in the
+// header's menu, which stands in for the sidebar on smaller screens, as
+// DocsAsideLeftTop does above the sidebar. Docus's renders below it.
+import DocusAppHeaderBody from "docus/app/components/app/AppHeaderBody.vue";
+
+const { frameworks } = useFramework();
+const labelId = useId();
+</script>
+
+<template>
+  <div v-if="frameworks.length">
+    <span :id="labelId" class="w-full pr-2.5 py-1.5 flex items-center text-sm text-muted">
+      Framework
+    </span>
+    <DocsFrameworkSelect :aria-labelledby="labelId" class="mb-2" />
+  </div>
+  <DocusAppHeaderBody />
+</template>

package/app/components/content/FrameworkSwitcher.vue

@@ -1,6 +1,4 @@
 <script setup lang="ts">
-import type { FrameworkOption } from "../../composables/useFramework";
-
 /**
  * Shows the reader's framework out of a page's per-framework examples:
  *
@@ -13,62 +11,24 @@ import type { FrameworkOption } from "../../composables/useFramework";
  * ::
  * ```
  *
- * One tab per framework in `docsTheme.frameworks`. Picking one here picks it
- * everywhere, the sidebar's select included. Nuxt UI's tabs bring the WAI-ARIA
- * tabs pattern: arrow keys move between tabs, and each panel is labelled by its tab.
+ * The reader picks it in the Framework select, above the sidebar or, on
+ * smaller screens, in the header's menu, for the whole site at once, so the
+ * switcher has no tabs of its own. A page can cover only some frameworks. The
+ * others show the first one it covers, with a note saying so.
  */
-const { framework, frameworks, current } = useFramework();
+const { frameworks, current } = useFramework();
 const slots = useSlots();
-const tabs = useTemplateRef("tabs");
-
-// A page can cover only some frameworks. The others show the first one it covers.
-function shown(option: FrameworkOption) {
-  return slots[option.value] ? option : frameworks.value.find((f) => slots[f.value]);
-}
 
-// When the tabs outgrow the width, the list scrolls. A pick made elsewhere (in
-// another switcher, in the sidebar, or restored once mounted) scrolls the list
-// to its tab. scrollIntoView() would scroll the page to the switcher too.
-watch(
-  current,
-  (option) => {
-    const index = option ? frameworks.value.indexOf(option) : -1;
-    const tab: HTMLElement | undefined = tabs.value?.triggersRef[index]?.$el;
-    const list = tab?.parentElement;
-    if (!tab || !list) return;
-    const end = tab.offsetLeft + tab.offsetWidth - list.clientWidth;
-    list.scrollLeft = Math.min(tab.offsetLeft, Math.max(list.scrollLeft, end));
-  },
-  { flush: "post" },
+const shown = computed(() =>
+  current.value && slots[current.value.value]
+    ? current.value
+    : frameworks.value.find((option) => slots[option.value]),
 );
 </script>
 
 <template>
-  <UTabs
-    v-if="current"
-    ref="tabs"
-    :model-value="current.value"
-    :items="frameworks"
-    color="primary"
-    variant="link"
-    size="sm"
-    class="framework-switcher"
-    :ui="{
-      root: 'my-5 gap-4',
-      // Scrolls when the tabs outgrow the width. The baseline and the selected
-      // tab's underline are drawn inside the list, where scrolling doesn't clip them.
-      list: 'overflow-x-auto border-b-0 mb-0 shadow-[inset_0_-1px_0_var(--ui-border)]',
-      indicator: 'bottom-0',
-      trigger: 'shrink-0',
-      content: '*:first:mt-0 *:last:mb-0',
-    }"
-    @update:model-value="framework = String($event)"
-  >
-    <template #content="{ item }">
-      <p v-if="!slots[item.value] && shown(item)" class="mb-2 text-sm text-muted">
-        Not available for {{ item.label }}, showing {{ shown(item)!.label }}.
-      </p>
-      <slot v-if="shown(item)" :name="shown(item)!.value" />
-    </template>
-  </UTabs>
+  <p v-if="current && shown && shown !== current" class="my-5 text-sm text-muted">
+    Not available for {{ current.label }}, showing {{ shown.label }}.
+  </p>
+  <slot v-if="shown" :name="shown.value" />
 </template>

package/app/components/docs/DocsFrameworkSelect.vue

@@ -1,15 +1,29 @@
 <script setup lang="ts">
+// The Framework label above it lines up with the navigation's categories, so the
+// select sits like one of their pages: indented behind the same guide line, at
+// the same width, with the same icon size, so its icon and label line up with
+// theirs. The wrappers mirror the navigation's child list and its items. The
+// classes go to the outer one, so a margin stays outside the guide line, and
+// the other attributes, like DocsAsideLeftTop's aria-labelledby, to the select.
+defineOptions({ inheritAttrs: false });
+
 const { framework, frameworks, current } = useFramework();
 </script>
 
 <template>
-  <USelect
-    :model-value="current?.value"
-    :items="frameworks"
-    variant="ghost"
-    color="neutral"
-    :icon="current?.icon"
-    class="w-full"
-    @update:model-value="framework = $event"
-  />
+  <div :class="$attrs.class" class="ms-2.5 -me-2.5 border-s border-default">
+    <div class="ps-1.5 -ms-px">
+      <USelect
+        v-bind="{ ...$attrs, class: undefined }"
+        :model-value="current?.value"
+        :items="frameworks"
+        variant="ghost"
+        color="neutral"
+        :icon="current?.icon"
+        :ui="{ leadingIcon: 'size-4 mx-0.5' }"
+        class="w-full"
+        @update:model-value="framework = $event"
+      />
+    </div>
+  </div>
 </template>

package/nuxt.config.ts

@@ -3,8 +3,9 @@
  *
  * It extends Docus, which renders `content/docs/` with its header, sidebar,
  * 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
+ * Framework select above the sidebar (in the header's menu on smaller screens),
+ * and a `::framework-switcher` content component with one slot per framework,
+ * which shows the reader's pick. The app lists its frameworks in
  * `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`).
@@ -14,6 +15,18 @@
 export default defineNuxtConfig({
   extends: ["docus"],
 
+  // The languages of the per-framework examples, on top of the ones Docus
+  // highlights (Vue, TypeScript, HTML, CSS, …). Nuxt merges these with the app's.
+  content: {
+    build: {
+      markdown: {
+        highlight: {
+          langs: ["tsx", "svelte", "angular-html", "angular-ts", "astro"],
+        },
+      },
+    },
+  },
+
   icon: {
     clientBundle: {
       scan: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxfront/layer-docs",
-  "version": "0.6.0",
+  "version": "0.7.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",