@lupinum/ginko-docs 0.2.2 → 0.2.5

package/app/components/site/SiteLocaleSwitcher.vue

@@ -7,13 +7,13 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from "#ginko-docs/components/ui/dropdown-menu";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 import { computed } from "vue";
 import { useI18n } from "#imports";
 import { useLocalizedRouteSwitch } from "#ginko-docs/composables/useLocalizedRouteSwitch";
 import { locales as configuredLocales } from "../../../i18n/locales";
 
-type LocaleSwitcherVariant = "dropdown" | "menu-row" | "menu-tile" | "segmented";
+type LocaleSwitcherVariant = "dropdown" | "menu-row" | "menu-tile" | "segmented" | "pill";
 
 type LocaleEntry = {
   code: string;
@@ -105,7 +105,7 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
     <ClientOnly>
       <DropdownMenu>
         <DropdownMenuTrigger as-child>
-          <Button variant="outline" class="h-9 gap-1.5 px-2.5" :aria-label="t('nav.language')">
+          <Button variant="ghost" class="h-9 gap-1.5 px-2.5" :aria-label="t('nav.language')">
             <Icon
               v-if="currentLocale?.flagIcon"
               :name="currentLocale.flagIcon"
@@ -151,21 +151,37 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
       </DropdownMenu>
 
       <template #fallback>
-        <span
-          class="inline-flex h-9 w-[4.25rem] rounded-md border border-border bg-background"
-          aria-hidden="true"
-        />
+        <!-- Reserves the trigger's box before hydration. -->
+        <span class="inline-flex h-9 w-[4.25rem] rounded-md" aria-hidden="true" />
       </template>
     </ClientOnly>
   </div>
 
   <div
-    v-else-if="localeLinks.length > 1 && (variant === 'menu-row' || variant === 'menu-tile')"
+    v-else-if="
+      localeLinks.length > 1 &&
+      (variant === 'menu-row' || variant === 'menu-tile' || variant === 'pill')
+    "
     :class="cn('items-center', props.class)"
   >
     <DropdownMenu>
       <DropdownMenuTrigger as-child>
         <Button
+          v-if="variant === 'pill'"
+          variant="outline"
+          class="h-9 gap-2 rounded-full px-4 text-sm font-semibold"
+          :aria-label="t('nav.language')"
+        >
+          <Icon
+            v-if="currentLocale?.flagIcon"
+            :name="currentLocale.flagIcon"
+            class="size-4 rounded-full"
+            aria-hidden="true"
+          />
+          <span>{{ currentLocale?.shortLabel }}</span>
+        </Button>
+        <Button
+          v-else
           variant="ghost"
           :class="
             cn(
@@ -204,7 +220,7 @@ function trackLocaleNavigation(_entry: { code: string; current: boolean; to: unk
           />
         </Button>
       </DropdownMenuTrigger>
-      <DropdownMenuContent align="end" class="w-44">
+      <DropdownMenuContent align="end" class="w-44" portal-disabled>
         <DropdownMenuItem v-for="entry in localeLinks" :key="entry.code" as-child>
           <NuxtLink
             :to="entry.to"

package/app/components/site/SiteSocialLinks.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { Button } from "#ginko-docs/components/ui/button";
+import { useSiteNavigation } from "#ginko-docs/composables/useSiteNavigation";
+
+const { socialLinks } = useSiteNavigation();
+
+defineEmits<{ navigate: [] }>();
+</script>
+
+<template>
+  <div v-if="socialLinks.length" class="flex items-center">
+    <Button
+      v-for="link in socialLinks"
+      :key="link.href"
+      as-child
+      variant="ghost"
+      size="icon"
+      class="text-muted-foreground hover:text-foreground"
+    >
+      <NuxtLink
+        :to="link.href"
+        target="_blank"
+        rel="noopener noreferrer"
+        :aria-label="link.label"
+        @click="$emit('navigate')"
+      >
+        <Icon :name="link.icon ?? 'lucide:link'" class="size-[18px]" aria-hidden="true" />
+      </NuxtLink>
+    </Button>
+  </div>
+</template>

package/app/components/ui/badge/Badge.vue

@@ -4,7 +4,7 @@ import type { HTMLAttributes } from "vue";
 import type { BadgeVariants } from ".";
 import { reactiveOmit } from "@vueuse/core";
 import { Primitive } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 import { badgeVariants } from ".";
 
 const props = defineProps<

package/app/components/ui/button/Button.vue

@@ -3,7 +3,7 @@ import type { PrimitiveProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import type { ButtonVariants } from ".";
 import { Primitive } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 import { buttonVariants } from ".";
 
 interface Props extends PrimitiveProps {

package/app/components/ui/collapsible/CollapsibleContent.vue

@@ -3,7 +3,7 @@ import type { CollapsibleContentProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { CollapsibleContent } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<CollapsibleContentProps & { class?: HTMLAttributes["class"] }>();
 

package/app/components/ui/dropdown-menu/DropdownMenuContent.vue

@@ -3,27 +3,37 @@ import type { DropdownMenuContentEmits, DropdownMenuContentProps } from "reka-ui
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { DropdownMenuContent, DropdownMenuPortal, useForwardPropsEmits } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 defineOptions({
   inheritAttrs: false,
 });
 
 const props = withDefaults(
-  defineProps<DropdownMenuContentProps & { class?: HTMLAttributes["class"] }>(),
+  defineProps<
+    DropdownMenuContentProps & {
+      class?: HTMLAttributes["class"];
+      /**
+       * Render in place instead of teleporting to body. Required inside modal
+       * dialogs (e.g. the mobile menu sheet), where body-level portals are
+       * blocked by the dialog's pointer-events lock.
+       */
+      portalDisabled?: boolean;
+    }
+  >(),
   {
     sideOffset: 4,
   },
 );
 const emits = defineEmits<DropdownMenuContentEmits>();
 
-const delegatedProps = reactiveOmit(props, "class");
+const delegatedProps = reactiveOmit(props, "class", "portalDisabled");
 
 const forwarded = useForwardPropsEmits(delegatedProps, emits);
 </script>
 
 <template>
-  <DropdownMenuPortal>
+  <DropdownMenuPortal :disabled="props.portalDisabled">
     <DropdownMenuContent
       data-slot="dropdown-menu-content"
       v-bind="{ ...$attrs, ...forwarded }"

package/app/components/ui/dropdown-menu/DropdownMenuItem.vue

@@ -3,7 +3,7 @@ import type { DropdownMenuItemProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { DropdownMenuItem, useForwardProps } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = withDefaults(
   defineProps<

package/app/components/ui/dropdown-menu/DropdownMenuRadioItem.vue

@@ -3,7 +3,7 @@ import type { DropdownMenuRadioItemEmits, DropdownMenuRadioItemProps } from "rek
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { DropdownMenuItemIndicator, DropdownMenuRadioItem, useForwardPropsEmits } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<DropdownMenuRadioItemProps & { class?: HTMLAttributes["class"] }>();
 

package/app/components/ui/dropdown-menu/DropdownMenuSeparator.vue

@@ -3,7 +3,7 @@ import type { DropdownMenuSeparatorProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { DropdownMenuSeparator } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<
   DropdownMenuSeparatorProps & {

package/app/components/ui/dropdown-menu/index.ts

@@ -1,16 +1,7 @@
 export { default as DropdownMenu } from "./DropdownMenu.vue";
-
-export { default as DropdownMenuCheckboxItem } from "./DropdownMenuCheckboxItem.vue";
 export { default as DropdownMenuContent } from "./DropdownMenuContent.vue";
-export { default as DropdownMenuGroup } from "./DropdownMenuGroup.vue";
 export { default as DropdownMenuItem } from "./DropdownMenuItem.vue";
-export { default as DropdownMenuLabel } from "./DropdownMenuLabel.vue";
 export { default as DropdownMenuRadioGroup } from "./DropdownMenuRadioGroup.vue";
 export { default as DropdownMenuRadioItem } from "./DropdownMenuRadioItem.vue";
 export { default as DropdownMenuSeparator } from "./DropdownMenuSeparator.vue";
-export { default as DropdownMenuShortcut } from "./DropdownMenuShortcut.vue";
-export { default as DropdownMenuSub } from "./DropdownMenuSub.vue";
-export { default as DropdownMenuSubContent } from "./DropdownMenuSubContent.vue";
-export { default as DropdownMenuSubTrigger } from "./DropdownMenuSubTrigger.vue";
 export { default as DropdownMenuTrigger } from "./DropdownMenuTrigger.vue";
-export { DropdownMenuPortal } from "reka-ui";

package/app/components/ui/kbd/Kbd.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<{
   class?: HTMLAttributes["class"];

package/app/components/ui/kbd/index.ts

@@ -2,7 +2,6 @@ import type { VariantProps } from "class-variance-authority";
 import { cva } from "class-variance-authority";
 
 export { default as Kbd } from "./Kbd.vue";
-export { default as KbdGroup } from "./KbdGroup.vue";
 
 export const kbdVariants = cva(
   "bg-muted text-muted-foreground ring-1 ring-border pointer-events-none inline-flex w-fit items-center justify-center gap-1 rounded-sm font-sans font-medium select-none [&_svg:not([class*='size-'])]:size-3 [[data-slot=tooltip-content]_&]:bg-background/20 [[data-slot=tooltip-content]_&]:text-background dark:[[data-slot=tooltip-content]_&]:bg-background/10",

package/app/components/ui/scroll-area/ScrollArea.vue

@@ -3,7 +3,7 @@ import type { ScrollAreaRootProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { ScrollAreaCorner, ScrollAreaRoot, ScrollAreaViewport } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 import ScrollBar from "./ScrollBar.vue";
 
 const props = defineProps<

package/app/components/ui/scroll-area/ScrollBar.vue

@@ -3,7 +3,7 @@ import type { ScrollAreaScrollbarProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { ScrollAreaScrollbar, ScrollAreaThumb } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = withDefaults(
   defineProps<ScrollAreaScrollbarProps & { class?: HTMLAttributes["class"] }>(),

package/app/components/ui/separator/Separator.vue

@@ -3,7 +3,7 @@ import type { SeparatorProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { Separator } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = withDefaults(defineProps<SeparatorProps & { class?: HTMLAttributes["class"] }>(), {
   orientation: "horizontal",

package/app/components/ui/sheet/SheetContent.vue

@@ -3,7 +3,7 @@ import type { DialogContentEmits, DialogContentProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { DialogClose, DialogContent, DialogPortal, useForwardPropsEmits } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 import SheetOverlay from "./SheetOverlay.vue";
 
 interface SheetContentProps extends DialogContentProps {

package/app/components/ui/sheet/SheetDescription.vue

@@ -3,7 +3,7 @@ import type { DialogDescriptionProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { DialogDescription } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<DialogDescriptionProps & { class?: HTMLAttributes["class"] }>();
 

package/app/components/ui/sheet/SheetOverlay.vue

@@ -3,7 +3,7 @@ import type { DialogOverlayProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { DialogOverlay } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<DialogOverlayProps & { class?: HTMLAttributes["class"] }>();
 

package/app/components/ui/sheet/SheetTitle.vue

@@ -3,7 +3,7 @@ import type { DialogTitleProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { DialogTitle } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<DialogTitleProps & { class?: HTMLAttributes["class"] }>();
 

package/app/components/ui/sheet/index.ts

@@ -1,8 +1,5 @@
 export { default as Sheet } from "./Sheet.vue";
-export { default as SheetClose } from "./SheetClose.vue";
 export { default as SheetContent } from "./SheetContent.vue";
 export { default as SheetDescription } from "./SheetDescription.vue";
-export { default as SheetFooter } from "./SheetFooter.vue";
-export { default as SheetHeader } from "./SheetHeader.vue";
 export { default as SheetTitle } from "./SheetTitle.vue";
 export { default as SheetTrigger } from "./SheetTrigger.vue";

package/app/components/ui/tabs/Tabs.vue

@@ -3,7 +3,7 @@ import type { TabsRootEmits, TabsRootProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { TabsRoot, useForwardPropsEmits } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<TabsRootProps & { class?: HTMLAttributes["class"] }>();
 const emits = defineEmits<TabsRootEmits>();

package/app/components/ui/tabs/TabsList.vue

@@ -3,7 +3,7 @@ import type { TabsListProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { TabsList } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<TabsListProps & { class?: HTMLAttributes["class"] }>();
 

package/app/components/ui/tabs/TabsTrigger.vue

@@ -3,7 +3,7 @@ import type { TabsTriggerProps } from "reka-ui";
 import type { HTMLAttributes } from "vue";
 import { reactiveOmit } from "@vueuse/core";
 import { TabsTrigger, useForwardProps } from "reka-ui";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "#ginko-docs/utils";
 
 const props = defineProps<TabsTriggerProps & { class?: HTMLAttributes["class"] }>();
 

package/app/components/ui/tabs/index.ts

@@ -1,4 +1,3 @@
 export { default as Tabs } from "./Tabs.vue";
-export { default as TabsContent } from "./TabsContent.vue";
 export { default as TabsList } from "./TabsList.vue";
 export { default as TabsTrigger } from "./TabsTrigger.vue";

package/app/composables/site-navigation.utils.ts

@@ -1,4 +1,8 @@
-import type { GinkoDocsAppConfig, GinkoDocsLink } from "../../shared/types/app-config";
+import type {
+  GinkoDocsAppConfig,
+  GinkoDocsLink,
+  GinkoDocsSocialPlatform,
+} from "../../shared/types/app-config";
 import { getLocalizedSiteText } from "../config/site.utils";
 
 export interface NavItem {
@@ -6,6 +10,9 @@ export interface NavItem {
   href: string;
   external?: boolean;
   icon?: string;
+  description?: string;
+  /** Set on social links so features can find a platform without matching its icon. */
+  platform?: GinkoDocsSocialPlatform;
 }
 
 export interface MainNavContext {
@@ -15,6 +22,8 @@ export interface MainNavContext {
   blogExists: boolean;
   docsLabel: string;
   blogLabel: string;
+  docsDescription?: string;
+  blogDescription?: string;
 }
 
 const isExternalHref = (href: string) => /^https?:\/\//.test(href);
@@ -30,21 +39,68 @@ export function resolveMainNav(
         label: getLocalizedSiteText(link.label, ctx.locale),
         href,
         external: isExternalHref(href),
+        icon: link.icon,
+        description: link.description
+          ? getLocalizedSiteText(link.description, ctx.locale)
+          : undefined,
       };
     });
   }
 
-  const items: NavItem[] = [{ label: ctx.docsLabel, href: ctx.docsPath }];
+  const items: NavItem[] = [
+    {
+      label: ctx.docsLabel,
+      href: ctx.docsPath,
+      icon: "lucide:book-open",
+      description: ctx.docsDescription,
+    },
+  ];
   if (ctx.blogExists) {
-    items.push({ label: ctx.blogLabel, href: ctx.blogPath });
+    items.push({
+      label: ctx.blogLabel,
+      href: ctx.blogPath,
+      icon: "lucide:file-text",
+      description: ctx.blogDescription,
+    });
   }
   return items;
 }
 
+/**
+ * Brand names are not translated, so the labels are literals. The icons are
+ * bundled defaults — Lucide has no Discord mark, so chat is the closest generic
+ * stand-in and sites that ship the real one override `icon` per entry.
+ */
+const socialDefaults: Record<GinkoDocsSocialPlatform, { label: string; icon: string }> = {
+  github: { label: "GitHub", icon: "lucide:github" },
+  discord: { label: "Discord", icon: "lucide:message-circle" },
+  linkedin: { label: "LinkedIn", icon: "lucide:linkedin" },
+};
+
+export function resolveSocialLinks(social: GinkoDocsAppConfig["social"]): NavItem[] {
+  // Config order is render order, so a site can list Discord ahead of GitHub.
+  return Object.entries(social).flatMap<NavItem>(([key, entry]) => {
+    const platform = key as GinkoDocsSocialPlatform;
+    const defaults = socialDefaults[platform];
+    if (!defaults || !entry) return [];
+
+    const link = typeof entry === "string" ? { href: entry } : entry;
+    if (!link.href) return [];
+
+    return [
+      {
+        label: link.label ?? defaults.label,
+        href: link.href,
+        external: true,
+        icon: link.icon ?? defaults.icon,
+        platform,
+      },
+    ];
+  });
+}
+
 export interface BannerContext {
   locale: string;
-  blogPath: string;
-  blogExists: boolean;
   defaultText: string;
   defaultLinkLabel: string;
 }
@@ -65,16 +121,17 @@ export function resolveBanner(
   config: GinkoDocsAppConfig["banner"],
   ctx: BannerContext,
 ): ResolvedBanner {
-  const show = config.enabled === "auto" ? ctx.blogExists : config.enabled;
   const text = config.text ? getLocalizedSiteText(config.text, ctx.locale) : ctx.defaultText;
-  const linkHref = config.link?.to
-    ? getLocalizedSiteText(config.link.to, ctx.locale)
-    : ctx.blogExists
-      ? ctx.blogPath
-      : undefined;
+  const linkHref = config.link?.to ? getLocalizedSiteText(config.link.to, ctx.locale) : undefined;
   const linkLabel = config.link?.label
     ? getLocalizedSiteText(config.link.label, ctx.locale)
     : ctx.defaultLinkLabel;
 
-  return { show, text, linkLabel, linkHref, storageKey: bannerStorageKey(config.id) };
+  return {
+    show: config.enabled,
+    text,
+    linkLabel,
+    linkHref,
+    storageKey: bannerStorageKey(config.id),
+  };
 }

package/app/composables/useContentRouteAlternates.ts

@@ -18,26 +18,18 @@ export function useContentRouteAlternates() {
     state.value.sourcePath === route.path ? state.value.alternates : [],
   );
 
-  return current;
-}
-
-export function syncContentRouteAlternates(
-  page: Ref<{ route?: { alternates?: ContentAlternate[] } } | null | undefined>,
-) {
-  const route = useRoute();
-  const state = useState<ContentRouteAlternatesState>("content-route-alternates", () => ({
-    sourcePath: "",
-    alternates: [],
-  }));
+  function sync(page: Ref<{ route?: { alternates?: ContentAlternate[] } } | null | undefined>) {
+    watch(
+      page,
+      (document) => {
+        state.value = {
+          sourcePath: route.path,
+          alternates: document?.route?.alternates ?? [],
+        };
+      },
+      { immediate: true },
+    );
+  }
 
-  watch(
-    page,
-    (document) => {
-      state.value = {
-        sourcePath: route.path,
-        alternates: document?.route?.alternates ?? [],
-      };
-    },
-    { immediate: true },
-  );
+  return { current, sync };
 }

package/app/composables/useLocalizedRouteSwitch.ts

@@ -6,7 +6,7 @@ import { isLocaleCode } from "../../i18n/locales";
 export function useLocalizedRouteSwitch() {
   const route = useRoute();
   const switchLocalePath = useSwitchLocalePath();
-  const alternates = useContentRouteAlternates();
+  const { current: alternates } = useContentRouteAlternates();
 
   function switchPathname(targetLocale: string) {
     if (!isLocaleCode(targetLocale)) {

package/app/composables/useMetaKey.ts

@@ -0,0 +1,18 @@
+import { onMounted, ref, type Ref } from "vue";
+
+/**
+ * Platform-aware modifier key label. Defaults to "Ctrl" during SSR and
+ * upgrades to "⌘" on Apple platforms after mount (onMounted is client-only,
+ * so hydration stays consistent).
+ */
+export function useMetaKey(): Ref<string> {
+  const metaSymbol = ref("Ctrl");
+
+  onMounted(() => {
+    if (typeof navigator !== "undefined" && navigator.userAgent.includes("Macintosh")) {
+      metaSymbol.value = "⌘";
+    }
+  });
+
+  return metaSymbol;
+}

package/app/composables/useProseAppearance.ts

@@ -0,0 +1,24 @@
+import { computed, type MaybeRefOrGetter, toValue } from "vue";
+import type { GinkoDocsProseAppearance, GinkoDocsProseFamily } from "../../shared/types/app-config";
+import { useGinkoDocsConfig } from "./useGinkoDocsConfig";
+
+const DEFAULT_APPEARANCE: GinkoDocsProseAppearance = "quiet";
+
+function normalizeAppearance(value: unknown): GinkoDocsProseAppearance | undefined {
+  return value === "quiet" || value === "tint" ? value : undefined;
+}
+
+export function useProseAppearance(
+  family: GinkoDocsProseFamily,
+  appearance?: MaybeRefOrGetter<string | undefined>,
+) {
+  const config = useGinkoDocsConfig();
+
+  return computed<GinkoDocsProseAppearance>(
+    () =>
+      normalizeAppearance(toValue(appearance)) ??
+      normalizeAppearance(config.prose?.components?.[family]) ??
+      normalizeAppearance(config.prose?.appearance) ??
+      DEFAULT_APPEARANCE,
+  );
+}