@lupinum/ginko-docs 0.2.2 → 0.2.3

package/app/components/mdc/MdcSteps.vue

@@ -1,25 +1,59 @@
 <script setup lang="ts">
-import type { HTMLAttributes } from "vue";
-import { computed, provide } from "vue";
+import type { HTMLAttributes, VNode } from "vue";
+import { cloneVNode, computed, h, resolveComponent, useSlots } from "vue";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 import { cn } from "../../utils";
 
 const props = withDefaults(
   defineProps<{
-    variant?: "icons" | "numbered";
+    mode?: "icons" | "numbered";
+    appearance?: "quiet" | "tint";
     class?: HTMLAttributes["class"];
   }>(),
-  {
-    variant: "icons",
-  },
+  { mode: "icons" },
 );
 
-const normalizedVariant = computed(() => (props.variant === "numbered" ? "numbered" : "icons"));
+const slots = useSlots();
+const appearance = useProseAppearance("steps", () => props.appearance);
 
-provide("mdcStepsVariant", normalizedVariant);
+const steps = computed(() => {
+  const result: Array<{ heading: VNode; body: VNode[] }> = [];
+  for (const node of slots.default?.() ?? []) {
+    if (typeof node.props?.id === "string") {
+      result.push({ heading: node, body: [] });
+    } else if (result.length) {
+      result.at(-1)!.body.push(node);
+    }
+  }
+  return result;
+});
+
+function renderSteps() {
+  const Icon = resolveComponent("Icon");
+  return h(
+    "div",
+    {
+      class: cn("content-steps not-prose", props.class),
+      "data-mode": props.mode,
+      "data-appearance": appearance.value,
+    },
+    steps.value.map((step, index) =>
+      h("section", { key: index, class: "content-step" }, [
+        h("span", { class: "content-step-marker", "aria-hidden": "true" }, [
+          props.mode === "icons"
+            ? h(Icon, { name: "lucide:check", class: "content-step-icon" })
+            : String(index + 1),
+        ]),
+        h("div", { class: "content-step-body content-prose content-prose-trim" }, [
+          cloneVNode(step.heading, { class: "content-step-title" }),
+          ...step.body,
+        ]),
+      ]),
+    ),
+  );
+}
 </script>
 
 <template>
-  <div :class="cn('content-steps not-prose', props.class)" :data-variant="normalizedVariant">
-    <slot />
-  </div>
+  <component :is="renderSteps" />
 </template>

package/app/components/mdc/MdcSuccess.vue

@@ -5,12 +5,19 @@ import MdcCallout from "./MdcCallout.vue";
 const props = defineProps<{
   title?: string;
   icon?: string;
+  appearance?: "quiet" | "tint";
   class?: HTMLAttributes["class"];
 }>();
 </script>
 
 <template>
-  <MdcCallout :title="title" :icon="icon" type="success" :class="props.class">
+  <MdcCallout
+    :title="title"
+    :icon="icon"
+    type="success"
+    :appearance="appearance"
+    :class="props.class"
+  >
     <slot />
   </MdcCallout>
 </template>

package/app/components/mdc/MdcTabs.vue

@@ -1,30 +1,33 @@
 <script setup lang="ts">
 import type { VNode } from "vue";
-import { h, ref, resolveComponent, useSlots } from "vue";
+import { cloneVNode, h, ref, resolveComponent, useId, useSlots } from "vue";
 import { cn } from "../../utils";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 import { resolveIconifyIcon } from "./icons";
 
 const props = withDefaults(
   defineProps<{
-    variant?: "separate" | "line";
+    layout?: "separate" | "line";
+    appearance?: "quiet" | "tint";
     padded?: boolean;
     inStack?: boolean;
   }>(),
   {
-    variant: "separate",
+    layout: "separate",
     padded: true,
     inStack: false,
   },
 );
+const appearance = useProseAppearance("tabs", () => props.appearance);
 
 const slots = useSlots();
-const activeValue = ref("");
+const activeIndex = ref(0);
+const tabsId = useId();
 
 type TabItem = {
   icon?: string;
   label: string;
   node: VNode;
-  value: string;
 };
 
 function getTabLabel(node: VNode, index: number) {
@@ -44,16 +47,29 @@ function getItems(): TabItem[] {
       icon: getTabIcon(node),
       label: getTabLabel(node, index),
       node,
-      value: getTabLabel(node, index),
     }));
 }
 
+function handleKeydown(event: KeyboardEvent, items: TabItem[], currentIndex: number) {
+  let nextIndex: number | undefined;
+  if (event.key === "ArrowRight") nextIndex = (currentIndex + 1) % items.length;
+  if (event.key === "ArrowLeft") nextIndex = (currentIndex - 1 + items.length) % items.length;
+  if (event.key === "Home") nextIndex = 0;
+  if (event.key === "End") nextIndex = items.length - 1;
+  if (nextIndex === undefined) return;
+
+  event.preventDefault();
+  activeIndex.value = nextIndex;
+  const buttons = (event.currentTarget as HTMLElement).parentElement?.querySelectorAll<HTMLElement>(
+    '[role="tab"]',
+  );
+  buttons?.[nextIndex]?.focus();
+}
+
 function renderTabs() {
   const items = getItems();
   const Icon = resolveComponent("Icon");
-  const resolvedValue = items.some((item) => item.value === activeValue.value)
-    ? activeValue.value
-    : activeValue.value || items[0]?.value || "";
+  const resolvedIndex = Math.min(activeIndex.value, items.length - 1);
 
   if (!items.length) {
     return null;
@@ -63,6 +79,9 @@ function renderTabs() {
     "div",
     {
       class: cn("content-tabs not-prose group", props.inStack && "content-tabs-in-stack"),
+      "data-appearance": appearance.value,
+      "data-layout": props.layout,
+      "data-padded": props.padded ? "true" : "false",
     },
     [
       h("div", { class: "content-tabs-header" }, [
@@ -72,21 +91,22 @@ function renderTabs() {
             class: "content-tabs-list",
             role: "tablist",
           },
-          items.map((item) =>
+          items.map((item, index) =>
             h(
               "button",
               {
-                key: item.value,
+                key: index,
                 type: "button",
                 role: "tab",
-                "aria-selected": resolvedValue === item.value,
-                class: cn(
-                  "content-tabs-tab",
-                  resolvedValue === item.value && "content-tabs-tab-active",
-                ),
+                id: `${tabsId}-tab-${index}`,
+                "aria-controls": `${tabsId}-panel-${index}`,
+                "aria-selected": resolvedIndex === index,
+                tabindex: resolvedIndex === index ? 0 : -1,
+                class: cn("content-tabs-tab", resolvedIndex === index && "content-tabs-tab-active"),
                 onClick: () => {
-                  activeValue.value = item.value;
+                  activeIndex.value = index;
                 },
+                onKeydown: (event: KeyboardEvent) => handleKeydown(event, items, index),
               },
               [
                 item.icon
@@ -105,20 +125,18 @@ function renderTabs() {
       h(
         "div",
         { class: "content-tabs-panels" },
-        items.map((item) =>
+        items.map((item, index) =>
           h(
             "div",
             {
-              key: item.value,
-              value: item.value,
+              key: index,
               role: "tabpanel",
-              class: cn(
-                "content-tabs-content-area content-prose content-prose-trim [&>figure:only-child]:-m-4 [&>figure:only-child]:border-none",
-                props.padded ? "p-4" : "p-0",
-              ),
-              style: resolvedValue === item.value ? undefined : { display: "none" },
+              id: `${tabsId}-panel-${index}`,
+              "aria-labelledby": `${tabsId}-tab-${index}`,
+              class: cn("content-tabs-content-area content-prose content-prose-trim"),
+              style: resolvedIndex === index ? undefined : { display: "none" },
             },
-            [h(item.node, { inGroup: true })],
+            [cloneVNode(item.node, { inGroup: true })],
           ),
         ),
       ),

package/app/components/mdc/MdcTimeline.vue

@@ -1,14 +1,17 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
 import { cn } from "../../utils";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 
 const props = defineProps<{
   class?: HTMLAttributes["class"];
+  appearance?: "quiet" | "tint";
 }>();
+const appearance = useProseAppearance("timeline", () => props.appearance);
 </script>
 
 <template>
-  <div :class="cn('not-prose mb-12 ml-4 border-l border-border pl-8', props.class)">
+  <div :class="cn('content-timeline not-prose', props.class)" :data-appearance="appearance">
     <slot />
   </div>
 </template>

package/app/components/mdc/MdcTimelineItem.vue

@@ -1,48 +1,39 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
+import { computed } from "vue";
 import { cn } from "../../utils";
+import { resolveIconifyIcon } from "./icons";
 
 const props = defineProps<{
   date?: string;
   label?: string;
   title?: string;
+  icon?: string;
+  active?: boolean;
   class?: HTMLAttributes["class"];
 }>();
+
+const iconName = computed(() => resolveIconifyIcon(props.icon));
 </script>
 
 <template>
-  <div :class="cn('relative pb-8 last:pb-0', props.class)">
-    <div
-      class="absolute top-0.5 -left-[2.45rem] flex h-5 w-5 items-center justify-center rounded-full border border-border bg-background"
-    >
-      <div class="size-2 rounded-full bg-primary" />
-    </div>
-    <div class="mb-2 flex flex-wrap items-center gap-2">
-      <span
-        v-if="date"
-        class="inline-flex items-center rounded-md border border-border bg-muted/50 px-2 py-0.5 text-xs font-medium text-muted-foreground"
-      >
+  <div :class="cn('content-timeline-item', props.class)" :data-active="active || undefined">
+    <span class="content-timeline-marker" aria-hidden="true">
+      <Icon v-if="iconName" :name="iconName" class="content-timeline-marker-icon" />
+      <span class="content-timeline-marker-dot" />
+    </span>
+    <div v-if="title || date || label" class="content-timeline-head">
+      <p v-if="title" class="content-timeline-title">
+        {{ title }}
+      </p>
+      <span v-if="date" class="content-timeline-date">
         {{ date }}
       </span>
-      <span
-        v-if="label"
-        class="inline-flex items-center rounded-md bg-primary/10 px-2 py-0.5 text-xs font-medium text-primary"
-      >
+      <span v-if="label" class="content-timeline-label">
         {{ label }}
       </span>
     </div>
-    <p v-if="title" class="mb-1 font-semibold text-foreground">
-      {{ title }}
-    </p>
-    <div
-      :class="
-        cn(
-          'content-prose content-prose-trim text-muted-foreground',
-          '[&_a]:font-medium [&_a]:text-foreground [&_a]:underline [&_a]:underline-offset-4',
-          '[&_p]:my-2 [&_p]:text-pretty [&_p:first-child]:mt-0 [&_p:last-child]:mb-0',
-        )
-      "
-    >
+    <div class="content-timeline-body content-prose content-prose-trim">
       <slot />
     </div>
   </div>

package/app/components/mdc/MdcWarning.vue

@@ -5,12 +5,19 @@ import MdcCallout from "./MdcCallout.vue";
 const props = defineProps<{
   title?: string;
   icon?: string;
+  appearance?: "quiet" | "tint";
   class?: HTMLAttributes["class"];
 }>();
 </script>
 
 <template>
-  <MdcCallout :title="title" :icon="icon" type="warning" :class="props.class">
+  <MdcCallout
+    :title="title"
+    :icon="icon"
+    type="warning"
+    :appearance="appearance"
+    :class="props.class"
+  >
     <slot />
   </MdcCallout>
 </template>

package/app/components/mdc/api.utils.ts

@@ -0,0 +1,132 @@
+export type ApiEntry = {
+  name: string;
+  annotation?: string;
+  optional?: boolean;
+  required?: boolean;
+  deprecated?: boolean;
+  since?: string;
+  default?: string;
+  description?: string;
+};
+
+export type ApiGroup = {
+  label: string;
+  entries: ApiEntry[];
+};
+
+export type InlinePart = {
+  code: boolean;
+  text: string;
+};
+
+function authoredError(message: string): never {
+  throw new TypeError(`Invalid API groups: ${message}`);
+}
+
+function requiredText(value: unknown, path: string): string {
+  if (typeof value !== "string" || !value.trim())
+    authoredError(`${path} must be a non-empty string`);
+  return value.trim();
+}
+
+function optionalText(value: unknown, path: string): string | undefined {
+  if (value === undefined) return undefined;
+  return requiredText(value, path);
+}
+
+function optionalBoolean(value: unknown, path: string): boolean {
+  if (value === undefined) return false;
+  if (typeof value !== "boolean") authoredError(`${path} must be a boolean`);
+  return value;
+}
+
+export function normalizeApiGroups(input: unknown): ApiGroup[] {
+  if (!Array.isArray(input) || input.length === 0) {
+    authoredError("groups must be a non-empty array");
+  }
+
+  const labels = new Set<string>();
+  const ids = new Set<string>();
+  return input.map((group, groupIndex): ApiGroup => {
+    if (typeof group !== "object" || group === null || Array.isArray(group)) {
+      authoredError(`groups[${groupIndex}] must be an object`);
+    }
+    const raw = group as Record<string, unknown>;
+    const label = requiredText(raw.label, `groups[${groupIndex}].label`);
+    if (labels.has(label)) authoredError(`duplicate group label "${label}"`);
+    labels.add(label);
+    if (!Array.isArray(raw.entries) || raw.entries.length === 0) {
+      authoredError(`groups[${groupIndex}].entries must be a non-empty array`);
+    }
+
+    const names = new Set<string>();
+    const entries = raw.entries.map((entry, entryIndex): ApiEntry => {
+      const path = `groups[${groupIndex}].entries[${entryIndex}]`;
+      if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        authoredError(`${path} must be an object`);
+      }
+      const rawEntry = entry as Record<string, unknown>;
+      const name = requiredText(rawEntry.name, `${path}.name`);
+      if (names.has(name)) authoredError(`duplicate entry name "${name}" in group "${label}"`);
+      names.add(name);
+      const required = optionalBoolean(rawEntry.required, `${path}.required`);
+      const optional = optionalBoolean(rawEntry.optional, `${path}.optional`);
+      if (required && optional) authoredError(`${path} cannot be both required and optional`);
+      const id = apiEntryId(label, name);
+      if (ids.has(id)) authoredError(`duplicate generated entry id "${id}"`);
+      ids.add(id);
+      return {
+        name,
+        annotation: optionalText(rawEntry.annotation, `${path}.annotation`),
+        optional,
+        required,
+        deprecated: optionalBoolean(rawEntry.deprecated, `${path}.deprecated`),
+        since: optionalText(rawEntry.since, `${path}.since`),
+        default: optionalText(rawEntry.default, `${path}.default`),
+        description: optionalText(rawEntry.description, `${path}.description`),
+      };
+    });
+    return { label, entries };
+  });
+}
+
+/**
+ * Everything after the entry name, built mechanically so authors never write
+ * signatures by hand: `?` + `: annotation` + ` = default`.
+ */
+export function signatureTail(entry: ApiEntry): string {
+  let tail = entry.optional ? "?" : "";
+  if (entry.annotation) tail += `: ${entry.annotation}`;
+  if (entry.default) tail += ` = ${entry.default}`;
+  return tail;
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** Stable deep-link id for an entry row, e.g. `api-flags-pm` for `--pm`. */
+export function apiEntryId(groupLabel: string, name: string): string {
+  return `api-${slugify(groupLabel)}-${slugify(name)}`;
+}
+
+/**
+ * Split a description string on backtick pairs so inline code renders as
+ * `<code>`. An unmatched backtick stays literal text.
+ */
+export function splitInlineCode(text: string): InlinePart[] {
+  const parts: InlinePart[] = [];
+  let rest = text;
+  for (;;) {
+    const match = /`([^`]+)`/.exec(rest);
+    if (!match) break;
+    if (match.index > 0) parts.push({ code: false, text: rest.slice(0, match.index) });
+    parts.push({ code: true, text: match[1]! });
+    rest = rest.slice(match.index + match[0].length);
+  }
+  if (rest) parts.push({ code: false, text: rest });
+  return parts;
+}

package/app/components/mdc/code-tree.utils.ts

@@ -0,0 +1,22 @@
+export function validateCodeTreePaths(paths: string[], defaultValue?: string): void {
+  if (paths.length === 0) throw new TypeError("Code tree requires at least one labeled file");
+
+  const seen = new Set<string>();
+  for (const path of paths) {
+    const parts = path.split("/");
+    if (!path.trim() || parts.some((part) => !part.trim() || part === "." || part === "..")) {
+      throw new TypeError(`Invalid code tree path "${path}"`);
+    }
+    if (seen.has(path)) throw new TypeError(`Duplicate code tree path "${path}"`);
+    seen.add(path);
+  }
+
+  for (const path of paths) {
+    if (paths.some((candidate) => candidate !== path && candidate.startsWith(`${path}/`))) {
+      throw new TypeError(`Code tree file "${path}" is also used as a directory`);
+    }
+  }
+  if (defaultValue !== undefined && !seen.has(defaultValue)) {
+    throw new TypeError(`Code tree defaultValue does not match a file: "${defaultValue}"`);
+  }
+}

package/app/components/mdc/quiz.utils.ts

@@ -0,0 +1,38 @@
+export type QuizOption = { text: string; correct: boolean };
+export type QuizType = "single" | "multiple";
+
+export function parseQuizOptions(input: unknown, type: unknown): QuizOption[] {
+  if (type !== "single" && type !== "multiple") {
+    throw new TypeError('Quiz type must be "single" or "multiple"');
+  }
+  if (!Array.isArray(input) || input.length < 2) {
+    throw new TypeError("Quiz options must contain at least two choices");
+  }
+
+  const labels = new Set<string>();
+  const options = input.map((value, index): QuizOption => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new TypeError(`Quiz option ${index + 1} must be an object`);
+    }
+    const raw = value as Record<string, unknown>;
+    if (typeof raw.text !== "string" || !raw.text.trim()) {
+      throw new TypeError(`Quiz option ${index + 1} must have non-empty text`);
+    }
+    const text = raw.text.trim();
+    if (labels.has(text)) throw new TypeError(`Quiz option text must be unique: "${text}"`);
+    labels.add(text);
+    if (typeof raw.correct !== "boolean") {
+      throw new TypeError(`Quiz option ${index + 1}.correct must be a boolean`);
+    }
+    return { text, correct: raw.correct };
+  });
+
+  const correctCount = options.filter((option) => option.correct).length;
+  if (type === "single" && correctCount !== 1) {
+    throw new TypeError("A single-choice quiz must have exactly one correct option");
+  }
+  if (type === "multiple" && correctCount < 1) {
+    throw new TypeError("A multiple-choice quiz must have at least one correct option");
+  }
+  return options;
+}

package/app/components/prose/ProseBlockquote.vue

@@ -1,14 +1,30 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
+import { computed, useAttrs } from "vue";
 import { cn } from "../../utils";
+import MdcCallout from "../mdc/MdcCallout.vue";
 
 const props = defineProps<{
+  dataAlert?: "note" | "tip" | "important" | "warning" | "caution";
   class?: HTMLAttributes["class"];
 }>();
+
+const attrs = useAttrs();
+const alert = computed(() => props.dataAlert ?? attrs["data-alert"]);
+const callout = computed(() => {
+  if (alert.value === "tip") return { type: "success" as const, title: "Tip" };
+  if (alert.value === "important") return { type: "info" as const, title: "Important" };
+  if (alert.value === "warning") return { type: "warning" as const, title: "Warning" };
+  if (alert.value === "caution") return { type: "error" as const, title: "Caution" };
+  return { type: "note" as const, title: "Note" };
+});
 </script>
 
 <template>
-  <blockquote :class="cn(props.class)">
+  <MdcCallout v-if="alert" :type="callout.type" :title="callout.title" :class="props.class">
+    <slot />
+  </MdcCallout>
+  <blockquote v-else :class="cn(props.class)">
     <slot />
   </blockquote>
 </template>

package/app/components/prose/ProseH1.vue

@@ -9,7 +9,7 @@ const props = defineProps<{
 </script>
 
 <template>
-  <h1 :id="id" :class="cn('scroll-mt-28', props.class)">
+  <h1 :id="id" :class="cn('scroll-mt-[var(--content-scroll-margin)]', props.class)">
     <a v-if="id" :href="`#${id}`" class="inline-flex items-center gap-2">
       <slot />
     </a>

package/app/components/prose/ProseH2.vue

@@ -9,14 +9,19 @@ const props = defineProps<{
 </script>
 
 <template>
-  <h2 :id="id" :class="cn('flex scroll-mt-28 flex-row items-center gap-1.5', props.class)">
+  <h2
+    :id="id"
+    :class="
+      cn('flex scroll-mt-[var(--content-scroll-margin)] flex-row items-center gap-1.5', props.class)
+    "
+  >
     <a v-if="id" :href="`#${id}`" class="peer" data-card="">
       <slot />
     </a>
     <Icon
       v-if="id"
       name="lucide:link"
-      class="size-3 shrink-0 text-muted-foreground opacity-0 transition-opacity peer-hover:opacity-100"
+      class="size-3 shrink-0 text-muted-foreground opacity-0 transition-opacity peer-hover:opacity-100 peer-focus-visible:opacity-100"
       aria-hidden="true"
     />
     <slot v-else />

package/app/components/prose/ProseH3.vue

@@ -9,14 +9,19 @@ const props = defineProps<{
 </script>
 
 <template>
-  <h3 :id="id" :class="cn('flex scroll-mt-28 flex-row items-center gap-1.5', props.class)">
+  <h3
+    :id="id"
+    :class="
+      cn('flex scroll-mt-[var(--content-scroll-margin)] flex-row items-center gap-1.5', props.class)
+    "
+  >
     <a v-if="id" :href="`#${id}`" class="peer" data-card="">
       <slot />
     </a>
     <Icon
       v-if="id"
       name="lucide:link"
-      class="size-3 shrink-0 text-muted-foreground opacity-0 transition-opacity peer-hover:opacity-100"
+      class="size-3 shrink-0 text-muted-foreground opacity-0 transition-opacity peer-hover:opacity-100 peer-focus-visible:opacity-100"
       aria-hidden="true"
     />
     <slot v-else />

package/app/components/prose/ProseH4.vue

@@ -3,12 +3,27 @@ import type { HTMLAttributes } from "vue";
 import { cn } from "../../utils";
 
 const props = defineProps<{
+  id?: string;
   class?: HTMLAttributes["class"];
 }>();
 </script>
 
 <template>
-  <h4 :class="cn('scroll-mt-28', props.class)">
-    <slot />
+  <h4
+    :id="id"
+    :class="
+      cn('flex scroll-mt-[var(--content-scroll-margin)] flex-row items-center gap-1.5', props.class)
+    "
+  >
+    <a v-if="id" :href="`#${id}`" class="peer" data-card="">
+      <slot />
+    </a>
+    <Icon
+      v-if="id"
+      name="lucide:link"
+      class="size-3 shrink-0 text-muted-foreground opacity-0 transition-opacity peer-hover:opacity-100 peer-focus-visible:opacity-100"
+      aria-hidden="true"
+    />
+    <slot v-else />
   </h4>
 </template>