@lupinum/ginko-docs 0.2.2 → 0.2.3

package/app/components/mdc/MdcAccordion.vue

@@ -2,6 +2,7 @@
 import { onMounted, ref } from "vue";
 import { AccordionRoot } from "reka-ui";
 import { cn } from "../../utils";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 
 const props = withDefaults(
   defineProps<{
@@ -9,12 +10,14 @@ const props = withDefaults(
     collapsible?: boolean;
     defaultValue?: string | string[];
     class?: string;
+    appearance?: "quiet" | "tint";
   }>(),
   {
     type: "single",
     collapsible: true,
   },
 );
+const appearance = useProseAppearance("accordion", () => props.appearance);
 
 const root = ref<HTMLElement | null>(null);
 const value = ref<string | string[]>(
@@ -53,10 +56,10 @@ onMounted(() => {
       v-model="value"
       :type="props.type"
       :collapsible="props.collapsible"
+      :unmount-on-hide="false"
       data-slot="accordion"
-      :class="
-        cn('not-prose my-4 w-full divide-y overflow-hidden rounded-lg border bg-card', props.class)
-      "
+      :data-appearance="appearance"
+      :class="cn('content-accordion not-prose', props.class)"
     >
       <slot />
     </AccordionRoot>

package/app/components/mdc/MdcAccordionItem.vue

@@ -15,35 +15,26 @@ const autoValue = useId();
   <AccordionItem
     :value="props.value || autoValue"
     :data-accordion-value="props.value || autoValue"
-    class="border-b last:border-b-0"
+    class="content-accordion-item"
   >
-    <AccordionHeader class="flex">
-      <AccordionTrigger
-        class="flex flex-1 items-start justify-between gap-4 rounded-md px-4 py-3 text-left text-sm font-medium transition-all outline-none hover:no-underline focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180"
-      >
+    <AccordionHeader class="content-accordion-header">
+      <AccordionTrigger class="content-accordion-trigger">
         <slot name="title">
           {{ title }}
         </slot>
-        <Icon
-          name="lucide:chevron-down"
-          class="pointer-events-none size-4 shrink-0 translate-y-0.5 text-muted-foreground transition-transform duration-200"
-          aria-hidden="true"
-        />
+        <Icon name="lucide:chevron-down" class="content-accordion-chevron" aria-hidden="true" />
       </AccordionTrigger>
     </AccordionHeader>
     <AccordionContent
       data-slot="accordion-content"
-      class="accordion-content overflow-hidden text-sm"
+      class="content-accordion-content accordion-content"
     >
       <slot name="content">
-        <div v-if="content" class="text-muted-foreground">
+        <div v-if="content" class="content-accordion-copy">
           {{ content }}
         </div>
       </slot>
-      <div
-        v-if="$slots.default"
-        class="content-prose content-prose-trim px-4 pb-2 text-muted-foreground"
-      >
+      <div v-if="$slots.default" class="content-accordion-copy content-prose content-prose-trim">
         <slot unwrap="p" />
       </div>
     </AccordionContent>

package/app/components/mdc/MdcApi.vue

@@ -0,0 +1,159 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, useId } from "vue";
+import { cn } from "../../utils";
+import { apiEntryId, normalizeApiGroups, signatureTail, splitInlineCode } from "./api.utils";
+import { resolveIconifyIcon } from "./icons";
+import { useProseAppearance } from "../../composables/useProseAppearance";
+
+const props = defineProps<{
+  title?: string;
+  icon?: string;
+  method?: string;
+  path?: string;
+  groups?: unknown;
+  appearance?: "quiet" | "tint";
+}>();
+const appearance = useProseAppearance("api", () => props.appearance);
+
+const groups = computed(() => normalizeApiGroups(props.groups));
+const activeIndex = ref(0);
+const panelId = useId();
+
+const iconName = computed(() => resolveIconifyIcon(props.icon));
+
+function handleKeydown(event: KeyboardEvent, currentIndex: number) {
+  let nextIndex: number | undefined;
+  if (event.key === "ArrowRight") nextIndex = (currentIndex + 1) % groups.value.length;
+  if (event.key === "ArrowLeft") {
+    nextIndex = (currentIndex - 1 + groups.value.length) % groups.value.length;
+  }
+  if (event.key === "Home") nextIndex = 0;
+  if (event.key === "End") nextIndex = groups.value.length - 1;
+  if (nextIndex === undefined) return;
+
+  event.preventDefault();
+  activeIndex.value = nextIndex;
+  const tabs = (event.currentTarget as HTMLElement).parentElement?.querySelectorAll<HTMLElement>(
+    '[role="tab"]',
+  );
+  tabs?.[nextIndex]?.focus();
+}
+
+function applyHash(hash: string) {
+  if (!hash) return;
+  const index = groups.value.findIndex((group) =>
+    group.entries.some((entry) => apiEntryId(group.label, entry.name) === hash),
+  );
+  if (index === -1) return;
+  activeIndex.value = index;
+  requestAnimationFrame(() => {
+    document.getElementById(hash)?.scrollIntoView();
+  });
+}
+
+onMounted(() => {
+  applyHash(window.location.hash.slice(1));
+});
+</script>
+
+<template>
+  <div
+    v-if="groups.length"
+    class="content-api content-tabs not-prose"
+    :data-appearance="appearance"
+    :data-stacked-header="groups.length > 1 ? 'true' : undefined"
+  >
+    <div class="content-tabs-header content-api-header">
+      <span v-if="method && path" class="content-api-identity">
+        <span class="content-api-method">
+          {{ method.toUpperCase() }}
+        </span>
+        <span class="content-api-path">{{ path }}</span>
+      </span>
+      <span v-else-if="title" class="content-api-identity content-api-title">
+        <Icon
+          v-if="iconName"
+          :name="iconName"
+          mode="svg"
+          class="content-api-title-icon"
+          aria-hidden="true"
+        />
+        <span class="content-api-path">{{ title }}</span>
+      </span>
+
+      <div class="content-tabs-list content-api-tabs" role="tablist">
+        <button
+          v-for="(group, index) in groups"
+          :key="group.label"
+          type="button"
+          role="tab"
+          :id="`${panelId}-tab-${index}`"
+          :aria-selected="activeIndex === index"
+          :aria-controls="`${panelId}-${index}`"
+          :tabindex="activeIndex === index ? 0 : -1"
+          :class="cn('content-tabs-tab', activeIndex === index && 'content-tabs-tab-active')"
+          @click="activeIndex = index"
+          @keydown="handleKeydown($event, index)"
+        >
+          {{ group.label }}
+          <span class="content-api-count">
+            {{ group.entries.length }}
+          </span>
+        </button>
+      </div>
+    </div>
+
+    <div class="content-tabs-panels">
+      <div
+        v-for="(group, index) in groups"
+        :id="`${panelId}-${index}`"
+        :key="group.label"
+        role="tabpanel"
+        :aria-labelledby="`${panelId}-tab-${index}`"
+        :style="activeIndex === index ? undefined : { display: 'none' }"
+      >
+        <div
+          v-for="entry in group.entries"
+          :id="apiEntryId(group.label, entry.name)"
+          :key="entry.name"
+          class="content-api-row"
+          style="scroll-margin-top: var(--content-scroll-margin)"
+        >
+          <code class="content-api-signature" :data-entry="entry.name">
+            <span
+              :class="cn('content-api-name', entry.deprecated && 'content-api-name-deprecated')"
+              >{{ entry.name }}</span
+            ><span v-if="signatureTail(entry)" class="content-api-type">{{
+              signatureTail(entry)
+            }}</span>
+          </code>
+
+          <span v-if="entry.required || entry.deprecated || entry.since" class="content-api-badges">
+            <span v-if="entry.required" class="content-api-badge" data-state="required">
+              required
+            </span>
+            <span v-if="entry.deprecated" class="content-api-badge" data-state="deprecated">
+              deprecated
+            </span>
+            <span v-if="entry.since" class="content-api-badge" data-state="since">
+              since {{ entry.since }}
+            </span>
+          </span>
+
+          <!-- A div, not a p: the prose stylesheet's unlayered `.content-prose p`
+            rules (1rem margins, inherited 1rem/1.75 type) override layered
+            utilities and are not guarded by not-prose. -->
+          <div v-if="entry.description" class="content-api-description">
+            <template
+              v-for="(part, partIndex) in splitInlineCode(entry.description)"
+              :key="partIndex"
+            >
+              <code v-if="part.code" class="content-api-inline-code">{{ part.text }}</code
+              ><template v-else>{{ part.text }}</template>
+            </template>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/mdc/MdcAside.vue

@@ -1,26 +1,22 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 import { cn } from "../../utils";
 
 const props = defineProps<{
   label?: string;
+  appearance?: "quiet" | "tint";
   class?: HTMLAttributes["class"];
 }>();
+const appearance = useProseAppearance("aside", () => props.appearance);
 </script>
 
 <template>
-  <aside
-    :class="
-      cn(
-        'not-prose my-4 rounded-lg border-l-2 border-muted-foreground/20 bg-muted/20 px-4 py-3',
-        props.class,
-      )
-    "
-  >
-    <p v-if="label" class="mb-2 text-xs font-medium tracking-wider text-muted-foreground uppercase">
+  <aside :data-appearance="appearance" :class="cn('content-aside not-prose', props.class)">
+    <p v-if="label" class="content-aside-label">
       {{ label }}
     </p>
-    <div :class="cn('content-prose content-prose-trim text-muted-foreground')">
+    <div class="content-aside-body content-prose content-prose-trim">
       <slot />
     </div>
   </aside>

package/app/components/mdc/MdcCallout.vue

@@ -1,16 +1,18 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
 import { computed } from "vue";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 import { cn } from "../../utils";
 import { resolveIconifyIcon } from "./icons";
 
-type CalloutType = "note" | "alert" | "info" | "warn" | "warning" | "error" | "success" | "idea";
+type CalloutType = "note" | "info" | "warning" | "error" | "success" | "idea";
 
 const props = withDefaults(
   defineProps<{
     title?: string;
     type?: CalloutType;
     icon?: string;
+    appearance?: "quiet" | "tint";
     class?: HTMLAttributes["class"];
   }>(),
   {
@@ -18,11 +20,7 @@ const props = withDefaults(
   },
 );
 
-const normalizedType = computed(() => {
-  if (props.type === "warn" || props.type === "alert") return "warning";
-
-  return props.type;
-});
+const appearance = useProseAppearance("callout", () => props.appearance);
 
 const iconName = computed(() => {
   if (props.icon) return resolveIconifyIcon(props.icon) ?? props.icon;
@@ -35,7 +33,7 @@ const iconName = computed(() => {
       error: "lucide:circle-x",
       success: "lucide:circle-check",
       idea: "lucide:lightbulb",
-    }[normalizedType.value] ?? "lucide:info"
+    }[props.type] ?? "lucide:info"
   );
 });
 </script>
@@ -43,12 +41,13 @@ const iconName = computed(() => {
 <template>
   <div
     data-slot="alert"
-    role="alert"
-    :class="cn('content-callout not-prose my-4', `content-callout-${normalizedType}`, props.class)"
+    :data-appearance="appearance"
+    role="note"
+    :class="cn('content-callout not-prose my-4', `content-callout-${props.type}`, props.class)"
   >
     <span class="content-callout-bar" aria-hidden="true" />
     <span data-slot="alert-icon" class="content-callout-icon" aria-hidden="true">
-      <Icon :name="iconName" class="mt-1 size-5" />
+      <Icon :name="iconName" />
     </span>
     <div class="content-callout-body">
       <div v-if="title" data-slot="alert-title" class="content-alert-title">

package/app/components/mdc/MdcCard.vue

@@ -1,8 +1,16 @@
 <script setup lang="ts">
 import { NuxtLink } from "#components";
-import { computed, inject, useSlots, type CSSProperties, type HTMLAttributes } from "vue";
+import {
+  computed,
+  inject,
+  useSlots,
+  type ComputedRef,
+  type CSSProperties,
+  type HTMLAttributes,
+} from "vue";
 import { cn } from "../../utils";
 import { isExternalLink, resolveIconifyIcon } from "./icons";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 
 type CardIconColor =
   | "muted"
@@ -27,6 +35,7 @@ const props = withDefaults(
     horizontal?: boolean;
     inStack?: boolean;
     class?: HTMLAttributes["class"];
+    appearance?: "quiet" | "tint";
   }>(),
   {
     showLinkIcon: true,
@@ -37,6 +46,12 @@ const props = withDefaults(
 
 const slots = useSlots();
 const inGroup = inject("contentCardInGroup", false);
+// Instance prop wins, then the surrounding ::cards tray, then config.
+const groupAppearance = inject<ComputedRef<"quiet" | "tint"> | null>(
+  "contentCardsAppearance",
+  null,
+);
+const appearance = useProseAppearance("cards", () => props.appearance ?? groupAppearance?.value);
 
 const wrapperTag = computed(() => (props.to ? (isExternalLink(props.to) ? "a" : NuxtLink) : "div"));
 
@@ -93,66 +108,43 @@ const cardIconStyle = computed<CSSProperties | undefined>(() =>
   <component
     :is="wrapperTag"
     v-bind="linkProps || {}"
+    :data-appearance="appearance"
     :class="
       cn(
-        'content-card group not-prose relative block h-auto',
-        !inStack && !inGroup && 'my-4',
-        to &&
-          'rounded-xl focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:outline-none',
+        'content-card group not-prose',
+        !inStack && !inGroup && 'content-card-standalone',
+        inStack && 'content-card-in-stack',
+        to && 'focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none',
         props.class,
       )
     "
   >
-    <div
-      data-slot="card"
-      :class="
-        cn(
-          'content-card-surface relative overflow-hidden rounded-xl border bg-card text-card-foreground shadow-xs transition-colors',
-          hasBody || hasFooter ? 'p-0' : 'p-0',
-          to && 'cursor-pointer hover:bg-accent/50',
-          showOutgoingLinkIcon && (hasBody || hasFooter ? '' : 'pr-10'),
-          inStack &&
-            'rounded-none border-x-0 shadow-none first:rounded-t-xl first:border-t last:rounded-b-xl last:border-b',
-        )
-      "
-    >
-      <img v-if="img" :src="img" alt="" class="w-full border-b border-border object-cover" />
+    <div data-slot="card" class="content-card-surface">
+      <img v-if="img" :src="img" alt="" class="content-card-media" />
 
       <div
         v-if="hasHeader"
-        :class="
-          cn(
-            hasBody || hasFooter ? 'p-4 pb-0' : 'p-4',
-            showOutgoingLinkIcon && 'pr-10',
-            horizontal && 'flex items-start gap-3',
-          )
-        "
+        class="content-card-header"
+        :data-trailing="hasBody || hasFooter ? 'true' : undefined"
+        :data-horizontal="horizontal ? 'true' : undefined"
+        :data-reserve-link-icon="showOutgoingLinkIcon ? 'true' : undefined"
       >
         <div
           v-if="iconName"
-          :style="cardIconStyle"
-          :class="
-            cn(
-              'content-card-icon flex size-10 shrink-0 items-center justify-center rounded-lg border bg-muted shadow-xs [&_.iconify]:size-5',
-              horizontal ? '' : 'mb-2',
-            )
-          "
+          v-bind="cardIconStyle ? { style: cardIconStyle } : {}"
+          class="content-card-icon content-card-tile"
         >
           <Icon :name="iconName" aria-hidden="true" />
         </div>
 
-        <div :class="cn('min-w-0', horizontal ? 'flex-1 space-y-1' : 'space-y-1')">
-          <div
-            v-if="title || $slots.title"
-            data-slot="card-title"
-            :class="cn('text-sm font-medium', !horizontal && 'mb-0')"
-          >
+        <div class="content-card-copy">
+          <div v-if="title || $slots.title" data-slot="card-title" class="content-card-title">
             <slot name="title">{{ title }}</slot>
           </div>
           <div
             v-if="description || $slots.description"
             data-slot="card-description"
-            class="text-sm leading-snug text-pretty"
+            class="content-card-description"
           >
             <slot name="description">{{ description }}</slot>
           </div>
@@ -162,23 +154,20 @@ const cardIconStyle = computed<CSSProperties | undefined>(() =>
       <div
         v-if="hasBody"
         data-slot="card-content"
-        class="content-prose content-prose-trim p-4 pt-2 text-muted-foreground"
+        class="content-card-body content-prose content-prose-trim"
+        :data-reserve-link-icon="showOutgoingLinkIcon && !hasHeader ? 'true' : undefined"
       >
         <slot unwrap="p" />
       </div>
 
-      <div
-        v-if="hasFooter"
-        data-slot="card-footer"
-        class="flex flex-col items-stretch border-t px-4 py-3 text-xs text-muted-foreground [&_p]:my-0 [&_p]:leading-normal"
-      >
+      <div v-if="hasFooter" data-slot="card-footer" class="content-card-footer">
         <slot name="footer">{{ footer }}</slot>
       </div>
 
       <Icon
         v-if="showOutgoingLinkIcon"
         name="lucide:arrow-up-right"
-        class="pointer-events-none absolute top-4 right-4 size-4 text-muted-foreground/50 transition-colors group-hover:text-foreground"
+        class="content-card-arrow"
         aria-hidden="true"
       />
     </div>

package/app/components/mdc/MdcCards.vue

@@ -0,0 +1,30 @@
+<script setup lang="ts">
+import { computed, provide, type HTMLAttributes } from "vue";
+import { useProseAppearance } from "../../composables/useProseAppearance";
+import { cn } from "../../utils";
+
+const props = withDefaults(
+  defineProps<{
+    cols?: 1 | 2 | 3 | "1" | "2" | "3";
+    appearance?: "quiet" | "tint";
+    class?: HTMLAttributes["class"];
+  }>(),
+  { cols: 2 },
+);
+
+provide("contentCardInGroup", true);
+const appearance = useProseAppearance("cards", () => props.appearance);
+// Children must render on the same surface as the tray they sit in.
+provide("contentCardsAppearance", appearance);
+const columns = computed(() => Math.min(3, Math.max(1, Number(props.cols) || 2)));
+</script>
+
+<template>
+  <div
+    :class="cn('content-cards not-prose', props.class)"
+    :data-appearance="appearance"
+    :data-columns="columns"
+  >
+    <slot />
+  </div>
+</template>

package/app/components/mdc/MdcCodeGroup.vue

@@ -4,6 +4,7 @@ import { Comment, cloneVNode, computed, h, ref, resolveComponent, useSlots } fro
 import { useClipboard } from "@vueuse/core";
 import { useI18n } from "#imports";
 import { cn } from "../../utils";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 
 type CodeBlockProps = {
   code?: string;
@@ -24,6 +25,8 @@ const slots = useSlots();
 const activeValue = ref("");
 const { copy, copied } = useClipboard();
 const { t } = useI18n();
+const props = defineProps<{ appearance?: "quiet" | "tint" }>();
+const appearance = useProseAppearance("code", () => props.appearance);
 
 const PACKAGE_ICONS: Record<string, string> = {
   bun: "logos:bun",
@@ -113,6 +116,7 @@ function renderCodeGroup() {
     "div",
     {
       class: "content-codegroup not-prose group",
+      "data-appearance": appearance.value,
     },
     [
       h("div", { class: "content-codegroup-header" }, [