@frontfactory/vitepress-theme 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/README.md +148 -5
  3. package/config.d.ts +26 -1
  4. package/config.js +165 -21
  5. package/dist/style.css +1 -1
  6. package/node/llms.js +31 -0
  7. package/node/og.js +159 -0
  8. package/node/pages.js +154 -0
  9. package/node/rss.js +81 -0
  10. package/package.json +42 -28
  11. package/src/blog/posts.data.ts +46 -0
  12. package/src/components/FfBackToTop.vue +18 -9
  13. package/src/components/FfBanner.vue +24 -6
  14. package/src/components/FfCopyStatus.vue +64 -0
  15. package/src/components/FfDocMeta.vue +41 -2
  16. package/src/components/FfFeature.vue +18 -7
  17. package/src/components/FfFeedback.vue +96 -0
  18. package/src/components/FfHero.vue +16 -6
  19. package/src/components/FfHeroCommand.vue +20 -34
  20. package/src/components/FfHomeSponsors.vue +2 -2
  21. package/src/components/FfNavBarTitle.vue +63 -0
  22. package/src/components/FfPost.vue +49 -0
  23. package/src/components/FfProgress.vue +69 -0
  24. package/src/components/FfVersionSwitcher.vue +20 -0
  25. package/src/composables/blog.ts +38 -0
  26. package/src/composables/options.ts +12 -1
  27. package/src/composables/tabs.ts +155 -0
  28. package/src/content/Api.vue +6 -2
  29. package/src/content/Badge.vue +26 -0
  30. package/src/content/Callout.vue +27 -0
  31. package/src/content/FileTree.vue +118 -0
  32. package/src/content/Tab.vue +11 -0
  33. package/src/content/Tabs.vue +74 -0
  34. package/src/content/Timeline.vue +19 -0
  35. package/src/content/TimelineItem.vue +37 -0
  36. package/src/content/timeline.ts +4 -0
  37. package/src/index.ts +37 -1
  38. package/src/internal.ts +7 -2
  39. package/src/layout/FfBlog.vue +62 -0
  40. package/src/layout/FfLayout.vue +17 -1
  41. package/src/styles/_base.scss +1 -5
  42. package/src/styles/_blocks.scss +25 -1
  43. package/src/styles/_blog.scss +131 -0
  44. package/src/styles/_breakpoints.scss +26 -0
  45. package/src/styles/_code.scss +5 -5
  46. package/src/styles/_content.scss +276 -7
  47. package/src/styles/_doc.scss +18 -5
  48. package/src/styles/_home.scss +37 -17
  49. package/src/styles/_motion.scss +12 -3
  50. package/src/styles/_nav.scss +81 -8
  51. package/src/styles/_print.scss +77 -0
  52. package/src/styles/_sidebar.scss +2 -2
  53. package/src/styles/_tokens.scss +73 -7
  54. package/src/styles/index.scss +2 -0
  55. package/src/types.ts +122 -0
  56. package/types/blog/posts.data.d.ts +14 -0
  57. package/types/components/FfBackToTop.vue.d.ts +3 -0
  58. package/types/components/FfBanner.vue.d.ts +3 -0
  59. package/types/components/FfCopyStatus.vue.d.ts +3 -0
  60. package/types/components/FfDocMeta.vue.d.ts +3 -0
  61. package/types/components/FfFeature.vue.d.ts +13 -0
  62. package/types/components/FfFeedback.vue.d.ts +3 -0
  63. package/types/components/FfFooter.vue.d.ts +3 -0
  64. package/types/components/FfHero.vue.d.ts +42 -0
  65. package/types/components/FfHeroCommand.vue.d.ts +9 -0
  66. package/types/components/FfHomeSponsors.vue.d.ts +19 -0
  67. package/types/components/FfNavBarTitle.vue.d.ts +17 -0
  68. package/types/components/FfPost.vue.d.ts +3 -0
  69. package/types/components/FfProgress.vue.d.ts +3 -0
  70. package/types/components/FfVersionSwitcher.vue.d.ts +3 -0
  71. package/types/composables/blog.d.ts +10 -0
  72. package/types/composables/link.d.ts +12 -0
  73. package/types/composables/options.d.ts +15 -0
  74. package/types/composables/relativeTime.d.ts +2 -0
  75. package/types/composables/tabs.d.ts +15 -0
  76. package/types/content/Api.vue.d.ts +27 -0
  77. package/types/content/Badge.vue.d.ts +21 -0
  78. package/types/content/Callout.vue.d.ts +24 -0
  79. package/types/content/Card.vue.d.ts +23 -0
  80. package/types/content/CardGrid.vue.d.ts +20 -0
  81. package/types/content/FileTree.vue.d.ts +6 -0
  82. package/types/content/Kbd.vue.d.ts +15 -0
  83. package/types/content/Steps.vue.d.ts +15 -0
  84. package/types/content/Tab.vue.d.ts +19 -0
  85. package/types/content/Tabs.vue.d.ts +7 -0
  86. package/types/content/Timeline.vue.d.ts +21 -0
  87. package/types/content/TimelineItem.vue.d.ts +21 -0
  88. package/types/content/timeline.d.ts +3 -0
  89. package/types/index.d.ts +25 -0
  90. package/types/internal.d.ts +9 -0
  91. package/types/layout/FfBlog.vue.d.ts +3 -0
  92. package/types/layout/FfLayout.vue.d.ts +23 -0
  93. package/types/types.d.ts +256 -0
@@ -1,9 +1,9 @@
1
1
  <script setup lang="ts">
2
2
  import {
3
- Comment, computed, Fragment, Text, useSlots, type VNode
3
+ Comment, computed, Fragment, onBeforeUpdate, Text, useSlots, type VNode
4
4
  } from 'vue';
5
5
  import { useData } from 'vitepress';
6
- import { VPImage } from '../internal';
6
+ import { normalizeLink, VPImage } from '../internal';
7
7
  import FfHeroCommand from './FfHeroCommand.vue';
8
8
  import type { HeroExtras, HeroMetaItem } from '../types';
9
9
  import type { DefaultTheme } from 'vitepress/theme';
@@ -64,9 +64,19 @@ function filled(nodes?: VNode[]): boolean {
64
64
  }
65
65
 
66
66
  // Called from the template rather than cached in a computed: the slot has to be rendered where its
67
- // dependencies are tracked, and it changes with the page.
67
+ // dependencies are tracked, and it changes with the page. It is still only rendered once per
68
+ // render — the template and the helpers below ask several times — so the answer is kept until the
69
+ // next update starts.
70
+ let imageCache: boolean | undefined;
71
+
72
+ onBeforeUpdate(() => {
73
+ imageCache = undefined;
74
+ });
75
+
68
76
  function hasImage() {
69
- return !!props.image || filled(slots['home-hero-image']?.());
77
+ imageCache ??= !!props.image || filled(slots['home-hero-image']?.());
78
+
79
+ return imageCache;
70
80
  }
71
81
 
72
82
  // The second column carries the image when there is one, and the starting point otherwise. The
@@ -139,7 +149,7 @@ function hasInlineCommand() {
139
149
  :key="action.link"
140
150
  class="ff-btn"
141
151
  :class="`ff-btn-${action.theme ?? 'brand'}`"
142
- :href="action.link"
152
+ :href="normalizeLink(action.link)"
143
153
  :target="action.target"
144
154
  :rel="action.rel ?? (action.target === '_blank' ? 'noopener' : undefined)"
145
155
  >
@@ -197,7 +207,7 @@ function hasInlineCommand() {
197
207
  :key="action.link"
198
208
  class="ff-btn"
199
209
  :class="`ff-btn-${action.theme ?? 'brand'}`"
200
- :href="action.link"
210
+ :href="normalizeLink(action.link)"
201
211
  :target="action.target"
202
212
  :rel="action.rel ?? (action.target === '_blank' ? 'noopener' : undefined)"
203
213
  >
@@ -1,8 +1,7 @@
1
1
  <script setup lang="ts">
2
- import {
3
- computed, onUnmounted, ref, watch
4
- } from 'vue';
2
+ import { computed, useId } from 'vue';
5
3
  import { format, useLabels } from '../composables/options';
4
+ import { useCopy, useTabs } from '../composables/tabs';
6
5
  import type { HeroCommandTab } from '../types';
7
6
 
8
7
  // Used from both hero panel positions (inline and beside the headline, see FfHero), which are
@@ -19,39 +18,15 @@ const tabs = computed<HeroCommandTab[] | undefined>(() =>
19
18
  Array.isArray(props.command) ? props.command : undefined
20
19
  );
21
20
 
22
- const activeTab = ref(0);
21
+ const { active: activeTab, select, onKeydown } = useTabs(() => tabs.value?.map((tab) => tab.label) ?? []);
23
22
 
24
- // Client-side navigation can swap the tabs a shorter or longer array without remounting this
25
- // component (two home pages in the same site), so the index is reset rather than left pointing
26
- // past the end.
27
- watch(tabs, () => (activeTab.value = 0));
23
+ const id = useId();
28
24
 
29
25
  const activeCommand = computed<string>(() =>
30
26
  tabs.value ? (tabs.value[activeTab.value]?.value ?? '') : (props.command as string)
31
27
  );
32
28
 
33
- const copied = ref(false);
34
- let copiedTimer: ReturnType<typeof setTimeout> | undefined;
35
-
36
- async function copy() {
37
- if (!activeCommand.value) {
38
- return;
39
- }
40
-
41
- try {
42
- await navigator.clipboard.writeText(activeCommand.value);
43
- } catch {
44
- // Insecure context or denied permission: there is nothing to confirm.
45
- return;
46
- }
47
-
48
- copied.value = true;
49
-
50
- clearTimeout(copiedTimer);
51
- copiedTimer = setTimeout(() => (copied.value = false), 2000);
52
- }
53
-
54
- onUnmounted(() => clearTimeout(copiedTimer));
29
+ const { copied, copy } = useCopy(activeCommand);
55
30
  </script>
56
31
 
57
32
  <template>
@@ -66,23 +41,34 @@ onUnmounted(() => clearTimeout(copiedTimer));
66
41
  <div
67
42
  v-if="tabs"
68
43
  class="ff-hero-command-tabs"
69
- role="group"
44
+ role="tablist"
70
45
  :aria-label="labels.heroInstall"
46
+ @keydown="onKeydown"
71
47
  >
72
48
  <button
73
49
  v-for="(tab, index) in tabs"
50
+ :id="`${id}-tab-${index}`"
74
51
  :key="tab.label"
75
52
  type="button"
53
+ role="tab"
76
54
  class="ff-hero-command-tab"
77
55
  :class="{ active: index === activeTab }"
78
- :aria-pressed="index === activeTab"
79
- @click="activeTab = index"
56
+ :aria-selected="index === activeTab"
57
+ :aria-controls="`${id}-panel`"
58
+ :tabindex="index === activeTab ? 0 : -1"
59
+ @click="select(index)"
80
60
  >
81
61
  {{ tab.label }}
82
62
  </button>
83
63
  </div>
84
64
 
85
- <div class="ff-hero-command">
65
+ <!-- One panel whose command follows the active tab, rather than one panel per tab. -->
66
+ <div
67
+ :id="tabs ? `${id}-panel` : undefined"
68
+ class="ff-hero-command"
69
+ :role="tabs ? 'tabpanel' : undefined"
70
+ :aria-labelledby="tabs ? `${id}-tab-${activeTab}` : undefined"
71
+ >
86
72
  <code>
87
73
  <span
88
74
  class="ff-hero-prompt"
@@ -1,5 +1,5 @@
1
1
  <script setup lang="ts">
2
- import { VPSponsors } from '../internal';
2
+ import { normalizeLink, VPSponsors } from '../internal';
3
3
  import { useLabels } from '../composables/options';
4
4
 
5
5
  export interface SponsorItem {
@@ -48,7 +48,7 @@ const labels = useLabels();
48
48
  >
49
49
  <a
50
50
  class="ff-btn ff-btn-alt no-icon"
51
- :href="actionLink"
51
+ :href="normalizeLink(actionLink)"
52
52
  >{{ actionText ?? labels.sponsorsAction }}</a>
53
53
  </div>
54
54
  </div>
@@ -0,0 +1,63 @@
1
+ <script setup lang="ts">
2
+ // Replica of the default theme's VPNavBarTitle, with the version switcher rendered beside the
3
+ // title link. Its `nav-bar-title-after` slot sits inside that link, where an interactive menu
4
+ // would be invalid markup and every click would navigate home.
5
+ import { computed } from 'vue';
6
+ import { useData } from 'vitepress';
7
+ import {
8
+ normalizeLink, useLangs, useLayout, VPImage
9
+ } from '../internal';
10
+ import FfVersionSwitcher from './FfVersionSwitcher.vue';
11
+
12
+ const { site, theme } = useData();
13
+ const { hasSidebar } = useLayout();
14
+ const { currentLang } = useLangs();
15
+
16
+ const logoLink = computed(() =>
17
+ typeof theme.value.logoLink === 'string' ? {
18
+ link: theme.value.logoLink
19
+ } : theme.value.logoLink
20
+ );
21
+
22
+ // Plain-text title, surfaced as a native tooltip since the sidebar column truncates it.
23
+ const textTitle = computed(() => {
24
+ if (theme.value.siteTitle === false) {
25
+ return undefined;
26
+ }
27
+
28
+ const raw: string = theme.value.siteTitle ?? site.value.title;
29
+
30
+ return raw.replace(/<[^>]+>/g, '').trim() || undefined;
31
+ });
32
+ </script>
33
+
34
+ <template>
35
+ <div
36
+ class="VPNavBarTitle"
37
+ :class="{ 'has-sidebar': hasSidebar }"
38
+ >
39
+ <a
40
+ class="title"
41
+ :href="logoLink?.link ?? normalizeLink(currentLang.link)"
42
+ :rel="logoLink?.rel"
43
+ :target="logoLink?.target"
44
+ :title="textTitle"
45
+ >
46
+ <slot name="nav-bar-title-before" />
47
+ <VPImage
48
+ v-if="theme.logo"
49
+ class="logo"
50
+ :image="theme.logo"
51
+ />
52
+ <span
53
+ v-if="theme.siteTitle"
54
+ dir="auto"
55
+ v-html="theme.siteTitle"
56
+ />
57
+ <span v-else-if="theme.siteTitle === undefined">{{ site.title }}</span>
58
+ <slot name="nav-bar-title-after" />
59
+ </a>
60
+
61
+ <FfVersionSwitcher />
62
+ </div>
63
+ </template>
@@ -0,0 +1,49 @@
1
+ <script setup lang="ts">
2
+ import { computed } from 'vue';
3
+ import { useData } from 'vitepress';
4
+ import {
5
+ formatDate, resolveAuthor, useBlog
6
+ } from '../composables/blog';
7
+ import { format, useLabels } from '../composables/options';
8
+
9
+ const { frontmatter, lang } = useData();
10
+ const { isPost, authors } = useBlog();
11
+ const labels = useLabels();
12
+
13
+ const date = computed(() => (isPost.value ? new Date(frontmatter.value.date).toISOString() : ''));
14
+ const author = computed(() => resolveAuthor(authors.value, frontmatter.value.author));
15
+ const tags = computed<string[]>(() => (Array.isArray(frontmatter.value.tags) ? frontmatter.value.tags : []));
16
+ </script>
17
+
18
+ <template>
19
+ <div
20
+ v-if="isPost"
21
+ class="ff-post ff-label"
22
+ >
23
+ <time
24
+ class="ff-post-item"
25
+ :datetime="date"
26
+ >{{ formatDate(date, lang) }}</time>
27
+ <span
28
+ v-if="author"
29
+ class="ff-post-item ff-post-author"
30
+ >
31
+ <img
32
+ v-if="author.avatar"
33
+ :src="author.avatar"
34
+ alt=""
35
+ class="ff-post-avatar"
36
+ >
37
+ <a
38
+ v-if="author.link"
39
+ :href="author.link"
40
+ >{{ format(labels.blogBy, author.name) }}</a>
41
+ <template v-else>{{ format(labels.blogBy, author.name) }}</template>
42
+ </span>
43
+ <span
44
+ v-for="tag in tags"
45
+ :key="tag"
46
+ class="ff-post-item ff-post-tag"
47
+ >{{ tag }}</span>
48
+ </div>
49
+ </template>
@@ -0,0 +1,69 @@
1
+ <script setup lang="ts">
2
+ import {
3
+ computed, onMounted, ref, watchEffect
4
+ } from 'vue';
5
+ import { useData } from 'vitepress';
6
+ import { useThemeOptions } from '../composables/options';
7
+
8
+ const { frontmatter } = useData();
9
+ const options = useThemeOptions();
10
+
11
+ const enabled = computed(() => options.value.progress === true && frontmatter.value.progress !== false);
12
+
13
+ const progress = ref(0);
14
+
15
+ function update() {
16
+ const range = document.documentElement.scrollHeight - window.innerHeight;
17
+
18
+ progress.value = range > 0 ? Math.min(Math.max(window.scrollY / range, 0), 1) : 0;
19
+ }
20
+
21
+ // At most one state update per frame, however many scroll events fire.
22
+ let frame = 0;
23
+
24
+ function onChange() {
25
+ if (!frame) {
26
+ frame = requestAnimationFrame(() => {
27
+ frame = 0;
28
+ update();
29
+ });
30
+ }
31
+ }
32
+
33
+ // Listens only while the bar is enabled, and follows the option if it changes (locale switch,
34
+ // per-page frontmatter). The effect is stopped with the component, which runs its cleanup.
35
+ onMounted(() => {
36
+ watchEffect((onCleanup) => {
37
+ if (!enabled.value) {
38
+ return;
39
+ }
40
+
41
+ update();
42
+ window.addEventListener('scroll', onChange, {
43
+ passive: true
44
+ });
45
+
46
+ window.addEventListener('resize', onChange, {
47
+ passive: true
48
+ });
49
+
50
+ onCleanup(() => {
51
+ cancelAnimationFrame(frame);
52
+ frame = 0;
53
+ window.removeEventListener('scroll', onChange);
54
+ window.removeEventListener('resize', onChange);
55
+ });
56
+ });
57
+ });
58
+ </script>
59
+
60
+ <template>
61
+ <ClientOnly>
62
+ <div
63
+ v-if="enabled"
64
+ class="ff-progress"
65
+ aria-hidden="true"
66
+ :style="{ transform: `scaleX(${progress})` }"
67
+ />
68
+ </ClientOnly>
69
+ </template>
@@ -0,0 +1,20 @@
1
+ <script setup lang="ts">
2
+ import { computed } from 'vue';
3
+ import { VPFlyout } from '../internal';
4
+ import { useLabels, useThemeOptions } from '../composables/options';
5
+
6
+ const options = useThemeOptions();
7
+ const labels = useLabels();
8
+
9
+ const versions = computed(() => options.value.versions);
10
+ </script>
11
+
12
+ <template>
13
+ <VPFlyout
14
+ v-if="versions"
15
+ class="ff-version-switcher"
16
+ :button="versions.current"
17
+ :items="versions.items"
18
+ :label="`${labels.versionSwitcher} ${versions.current}`"
19
+ />
20
+ </template>
@@ -0,0 +1,38 @@
1
+ import { computed } from 'vue';
2
+ import { useData } from 'vitepress';
3
+ import { useThemeOptions } from './options';
4
+ import type { BlogAuthor } from '../types';
5
+
6
+ /** Blog options, with the directory normalised (no slash at either end). */
7
+ export function useBlog() {
8
+ const options = useThemeOptions();
9
+ const { page, frontmatter } = useData();
10
+
11
+ const dir = computed(() => (options.value.blog?.dir ?? 'blog').replace(/^\/+|\/+$/g, ''));
12
+
13
+ // A post is a dated page under the blog directory, the index excluded.
14
+ const isPost = computed(
15
+ () => page.value.relativePath.startsWith(`${dir.value}/`) && !!frontmatter.value.date
16
+ );
17
+
18
+ return {
19
+ dir,
20
+ isPost,
21
+ authors: computed(() => options.value.blog?.authors ?? {})
22
+ };
23
+ }
24
+
25
+ /** `author` is a key of `ff.blog.authors`, or a plain name used as is. */
26
+ export function resolveAuthor(authors: Record<string, BlogAuthor>, value?: string): BlogAuthor | null {
27
+ return value ? authors[value] ?? {
28
+ name: value
29
+ } : null;
30
+ }
31
+
32
+ // UTC, so the server and the browser print the same day whatever their time zone.
33
+ export function formatDate(date: string, lang: string) {
34
+ return new Intl.DateTimeFormat(lang, {
35
+ dateStyle: 'long',
36
+ timeZone: 'UTC'
37
+ }).format(new Date(date));
38
+ }
@@ -24,7 +24,18 @@ export const defaultLabels: Required<ThemeLabels> = {
24
24
  footerSocial: 'Follow',
25
25
  newTab: 'opens in a new tab',
26
26
  sponsors: 'Sponsors',
27
- sponsorsAction: 'Become a sponsor'
27
+ sponsorsAction: 'Become a sponsor',
28
+ apiSince: 'since {0}',
29
+ apiDeprecated: 'deprecated',
30
+ bannerCta: 'Read more',
31
+ feedbackQuestion: 'Was this page helpful?',
32
+ feedbackYes: 'Yes',
33
+ feedbackNo: 'No',
34
+ feedbackThanks: 'Thanks for your feedback',
35
+ copyMarkdown: 'Copy as Markdown',
36
+ versionSwitcher: 'Version',
37
+ blogBy: 'By {0}',
38
+ blogEmpty: 'No posts yet'
28
39
  };
29
40
 
30
41
  /**
@@ -0,0 +1,155 @@
1
+ import {
2
+ computed, onMounted, onUnmounted, reactive, ref, toValue, watch, type MaybeRefOrGetter
3
+ } from 'vue';
4
+
5
+ const STORAGE_PREFIX = 'ff-tabs:';
6
+
7
+ // Label picked for each sync key. Module-level so every tab group on the page reads the same
8
+ // value; the `storage` event only fires in *other* documents, which is what keeps tabs open
9
+ // side by side in agreement.
10
+ const synced = reactive<Record<string, string>>({});
11
+ let listening = false;
12
+
13
+ function listen() {
14
+ if (listening) {
15
+ return;
16
+ }
17
+
18
+ listening = true;
19
+
20
+ window.addEventListener('storage', (event) => {
21
+ if (event.key?.startsWith(STORAGE_PREFIX) && event.newValue !== null) {
22
+ synced[event.key.slice(STORAGE_PREFIX.length)] = event.newValue;
23
+ }
24
+ });
25
+ }
26
+
27
+ /**
28
+ * Active tab of a group of labels. With a sync key, the choice is shared by label with every
29
+ * group using the same key and remembered across visits.
30
+ */
31
+ export function useTabs(labels: MaybeRefOrGetter<string[]>, syncKey?: MaybeRefOrGetter<string | undefined>) {
32
+ const local = ref(0);
33
+
34
+ // Client-side navigation can swap the labels without remounting the component (two pages
35
+ // using the same layout), so the index is reset rather than left pointing past the end.
36
+ watch(() => toValue(labels), () => (local.value = 0));
37
+
38
+ const active = computed(() => {
39
+ const list = toValue(labels);
40
+ const key = toValue(syncKey);
41
+
42
+ if (key && synced[key] !== undefined) {
43
+ const index = list.indexOf(synced[key]);
44
+
45
+ if (index !== -1) {
46
+ return index;
47
+ }
48
+ }
49
+
50
+ return Math.min(local.value, Math.max(list.length - 1, 0));
51
+ });
52
+
53
+ function select(index: number) {
54
+ local.value = index;
55
+
56
+ const key = toValue(syncKey);
57
+ const label = toValue(labels)[index];
58
+
59
+ if (!key || label === undefined) {
60
+ return;
61
+ }
62
+
63
+ synced[key] = label;
64
+
65
+ try {
66
+ localStorage.setItem(STORAGE_PREFIX + key, label);
67
+ } catch {
68
+ // Storage disabled: the choice still holds for this page.
69
+ }
70
+ }
71
+
72
+ // Read after mount only, so the server and the hydrating client both render the first tab.
73
+ onMounted(() => {
74
+ const key = toValue(syncKey);
75
+
76
+ if (!key) {
77
+ return;
78
+ }
79
+
80
+ listen();
81
+
82
+ try {
83
+ const stored = localStorage.getItem(STORAGE_PREFIX + key);
84
+
85
+ if (stored !== null && synced[key] === undefined) {
86
+ synced[key] = stored;
87
+ }
88
+ } catch {
89
+ // Storage disabled: fall back to the first tab.
90
+ }
91
+ });
92
+
93
+ // Roving focus across the tab list, as the ARIA tabs pattern expects: arrows wrap around, Home
94
+ // and End jump to the ends, and selection follows focus. Bound on the `role="tablist"` element.
95
+ function onKeydown(event: KeyboardEvent) {
96
+ const count = toValue(labels).length;
97
+ const targets: Record<string, number> = {
98
+ ArrowRight: (active.value + 1) % count,
99
+ ArrowLeft: (active.value - 1 + count) % count,
100
+ Home: 0,
101
+ End: count - 1
102
+ };
103
+ const next = targets[event.key];
104
+
105
+ if (next === undefined) {
106
+ return;
107
+ }
108
+
109
+ event.preventDefault();
110
+ select(next);
111
+
112
+ const tabs = (event.currentTarget as HTMLElement).querySelectorAll<HTMLElement>('[role="tab"]');
113
+
114
+ tabs[next]?.focus();
115
+ }
116
+
117
+ return {
118
+ active,
119
+ select,
120
+ onKeydown
121
+ };
122
+ }
123
+
124
+ /** Copies a string to the clipboard and flags it as copied for two seconds. */
125
+ export function useCopy(text: MaybeRefOrGetter<string>) {
126
+ const copied = ref(false);
127
+ let timer: ReturnType<typeof setTimeout> | undefined;
128
+
129
+ async function copy() {
130
+ const value = toValue(text);
131
+
132
+ if (!value) {
133
+ return;
134
+ }
135
+
136
+ try {
137
+ await navigator.clipboard.writeText(value);
138
+ } catch {
139
+ // Insecure context or denied permission: there is nothing to confirm.
140
+ return;
141
+ }
142
+
143
+ copied.value = true;
144
+
145
+ clearTimeout(timer);
146
+ timer = setTimeout(() => (copied.value = false), 2000);
147
+ }
148
+
149
+ onUnmounted(() => clearTimeout(timer));
150
+
151
+ return {
152
+ copied,
153
+ copy
154
+ };
155
+ }
@@ -1,4 +1,8 @@
1
1
  <script setup lang="ts">
2
+ import { format, useLabels } from '../composables/options';
3
+
4
+ const labels = useLabels();
5
+
2
6
  defineProps<{
3
7
  /** Symbol being documented, e.g. `refs()`. */
4
8
  name: string
@@ -28,11 +32,11 @@ defineProps<{
28
32
  <span
29
33
  v-if="since"
30
34
  class="ff-api-tag ff-label"
31
- >since {{ since }}</span>
35
+ >{{ format(labels.apiSince, since) }}</span>
32
36
  <span
33
37
  v-if="deprecated"
34
38
  class="ff-api-tag ff-api-deprecated ff-label"
35
- >deprecated</span>
39
+ >{{ labels.apiDeprecated }}</span>
36
40
  </header>
37
41
 
38
42
  <p
@@ -0,0 +1,26 @@
1
+ <script setup lang="ts">
2
+ import { computed } from 'vue';
3
+ import { format, useLabels } from '../composables/options';
4
+ import { VPBadge } from '../internal';
5
+
6
+ const labels = useLabels();
7
+
8
+ const props = defineProps<{
9
+ /** Text of the badge; for `since`, the version, printed through the `apiSince` label. */
10
+ text?: string
11
+ /** `tip`, `info`, `warning` and `danger` come from VitePress; `new`, `beta`, `deprecated` and `since` from the theme. */
12
+ type?: string
13
+ }>();
14
+
15
+ const shown = computed(() => (props.type === 'since' && props.text ? format(labels.value.apiSince, props.text) : props.text));
16
+ </script>
17
+
18
+ <!-- VPBadge types `type` as a closed union but only uses it as a class name, hence the cast. -->
19
+ <template>
20
+ <VPBadge
21
+ :type="(type as 'tip' | undefined)"
22
+ :text="shown"
23
+ >
24
+ <slot />
25
+ </VPBadge>
26
+ </template>
@@ -0,0 +1,27 @@
1
+ <script setup lang="ts">
2
+ // Same markup as a `::: tip` container, so the margin-note styling of _blocks.scss applies as is.
3
+ // It exists for the places a container cannot reach: inside another component, or with a type or
4
+ // title bound to data.
5
+ withDefaults(defineProps<{
6
+ /** One of the container types: `tip`, `info`, `note`, `important`, `warning`, `danger`, `caution`. */
7
+ type?: string
8
+ /** Label printed above the text. Defaults to the type, like a container. */
9
+ title?: string
10
+ }>(), {
11
+ type: 'note',
12
+ title: undefined
13
+ });
14
+ </script>
15
+
16
+ <template>
17
+ <div
18
+ class="custom-block"
19
+ :class="type"
20
+ >
21
+ <p class="custom-block-title">
22
+ {{ title ?? type }}
23
+ </p>
24
+
25
+ <slot />
26
+ </div>
27
+ </template>