@lupinum/ginko-docs 0.2.2 → 0.2.3

package/app/components/mdc/MdcCodeTree.vue

@@ -0,0 +1,234 @@
+<script setup lang="ts">
+import type { VNode } from "vue";
+import { Comment, cloneVNode, h, ref, resolveComponent, useSlots } from "vue";
+import { cn } from "../../utils";
+import { resolveFileIcon } from "../../utils/file-icons";
+import { useProseAppearance } from "../../composables/useProseAppearance";
+import { validateCodeTreePaths } from "./code-tree.utils";
+
+type CodeBlockProps = {
+  code?: string;
+  filename?: string | null;
+  language?: string | null;
+  meta?: string | null;
+};
+
+type TreeLeaf = {
+  path: string;
+  node: VNode;
+};
+
+type TreeNode = {
+  label: string;
+  path: string;
+  children?: TreeNode[];
+};
+
+const props = defineProps<{
+  /** Path of the file to show initially, e.g. "app/app.config.ts". */
+  defaultValue?: string;
+  expandAll?: boolean;
+  appearance?: "quiet" | "tint";
+}>();
+const appearance = useProseAppearance("code", () => props.appearance);
+
+const slots = useSlots();
+
+function isRenderableNode(node: VNode) {
+  return node.type !== Comment;
+}
+
+function cleanLabel(input: string | null | undefined): string {
+  return (
+    input
+      ?.trim()
+      .replace(/^\[(.*)]$/, "$1")
+      .trim() || ""
+  );
+}
+
+function labelFromMeta(meta: string | null | undefined): string {
+  const match = meta?.match(/\[([^\]]+)]/);
+  return cleanLabel(match?.[1]);
+}
+
+function resolveLeaves(): TreeLeaf[] {
+  const leaves = (slots.default?.() || []).filter(isRenderableNode).map((node) => {
+    const nodeProps = (node.props || {}) as CodeBlockProps;
+    const path = cleanLabel(nodeProps.filename) || labelFromMeta(nodeProps.meta);
+    if (!path) throw new TypeError("Every code tree block requires a filename label");
+    return { path, node };
+  });
+  validateCodeTreePaths(
+    leaves.map((leaf) => leaf.path),
+    props.defaultValue,
+  );
+  return leaves;
+}
+
+function buildTree(paths: string[]): TreeNode[] {
+  const map = new Map<string, TreeNode>();
+  const root: TreeNode[] = [];
+
+  for (const fullPath of paths) {
+    const parts = fullPath.split("/");
+    let path = "";
+
+    parts.forEach((part, i) => {
+      path = path ? `${path}/${part}` : part;
+      if (map.has(path)) return;
+
+      const node: TreeNode = { label: part, path, ...(i < parts.length - 1 && { children: [] }) };
+      map.set(path, node);
+      if (i === 0) root.push(node);
+      else map.get(parts.slice(0, i).join("/"))?.children?.push(node);
+    });
+  }
+
+  const sort = (nodes: TreeNode[]): TreeNode[] =>
+    nodes
+      .sort((a, b) =>
+        !!a.children === !!b.children ? a.label.localeCompare(b.label) : b.children ? 1 : -1,
+      )
+      .map((node) => ({ ...node, children: node.children && sort(node.children) }));
+
+  return sort(root);
+}
+
+function ancestorsOf(path: string): string[] {
+  const parts = path.split("/");
+  return parts.slice(0, -1).map((_, i) => parts.slice(0, i + 1).join("/"));
+}
+
+const selectedPath = ref(props.defaultValue ?? "");
+const expanded = ref(new Set<string>());
+const expansionChanged = ref(false);
+
+function toggleDir(path: string, initial: Set<string>) {
+  if (!expansionChanged.value) {
+    expanded.value = new Set(initial);
+    expansionChanged.value = true;
+  }
+  if (expanded.value.has(path)) expanded.value.delete(path);
+  else expanded.value.add(path);
+}
+
+const rowClass = "content-code-tree-row";
+
+function renderRows(
+  nodes: TreeNode[],
+  openPaths: Set<string>,
+  activePath: string,
+): (VNode | null)[] {
+  const Icon = resolveComponent("Icon");
+
+  return nodes.map((node) => {
+    if (node.children) {
+      const isOpen = openPaths.has(node.path);
+      return h("li", { key: node.path, role: "none" }, [
+        h(
+          "button",
+          {
+            type: "button",
+            class: rowClass,
+            "aria-expanded": isOpen ? "true" : "false",
+            onClick: () => toggleDir(node.path, openPaths),
+          },
+          [
+            h(Icon, {
+              name: "lucide:chevron-right",
+              class: "content-code-tree-chevron",
+              "data-open": isOpen ? "true" : undefined,
+              "aria-hidden": "true",
+            }),
+            h(Icon, {
+              name: isOpen ? "lucide:folder-open" : "lucide:folder",
+              class: "content-code-tree-icon",
+              "aria-hidden": "true",
+            }),
+            h("span", { class: "content-code-tree-label" }, node.label),
+          ],
+        ),
+        isOpen
+          ? h(
+              "ul",
+              { role: "group", class: "content-code-tree-branch" },
+              renderRows(node.children, openPaths, activePath),
+            )
+          : null,
+      ]);
+    }
+
+    const isSelected = activePath === node.path;
+    return h("li", { key: node.path, role: "none" }, [
+      h(
+        "button",
+        {
+          type: "button",
+          class: cn(rowClass, isSelected && "content-code-tree-row-active"),
+          "aria-current": isSelected ? "true" : undefined,
+          onClick: () => (selectedPath.value = node.path),
+        },
+        [
+          h("span", { class: "content-code-tree-spacer", "aria-hidden": "true" }),
+          h(resolveComponent("Icon"), {
+            name: resolveFileIcon(node.label),
+            class: "content-code-tree-icon",
+            "aria-hidden": "true",
+          }),
+          h("span", { class: "content-code-tree-label" }, node.label),
+        ],
+      ),
+    ]);
+  });
+}
+
+function renderCodeTree() {
+  const leaves = resolveLeaves();
+  if (!leaves.length) return null;
+  const activePath = leaves.some((leaf) => leaf.path === selectedPath.value)
+    ? selectedPath.value
+    : leaves[0]!.path;
+  const initialOpenPaths = new Set(
+    props.expandAll ? leaves.flatMap((leaf) => ancestorsOf(leaf.path)) : ancestorsOf(activePath),
+  );
+  const openPaths = expansionChanged.value ? expanded.value : initialOpenPaths;
+  const tree = buildTree(leaves.map((leaf) => leaf.path));
+
+  return h(
+    "div",
+    {
+      class: "content-code-tree not-prose",
+      "data-appearance": appearance.value,
+    },
+    [
+      h(
+        "ul",
+        {
+          class: "content-code-tree-list",
+        },
+        renderRows(tree, openPaths, activePath),
+      ),
+      h(
+        "div",
+        { class: "content-code-tree-pane" },
+        leaves.map((leaf) =>
+          h(
+            "div",
+            {
+              key: leaf.path,
+              class: "content-code-tree-panel",
+              style: activePath === leaf.path ? undefined : { display: "none" },
+            },
+            [cloneVNode(leaf.node)],
+          ),
+        ),
+      ),
+    ],
+  );
+}
+</script>
+
+<template>
+  <component :is="renderCodeTree" />
+</template>

package/app/components/mdc/MdcCollapse.vue

@@ -0,0 +1,61 @@
+<script setup lang="ts">
+import { computed, onMounted, provide, ref, useId } from "vue";
+import { useResizeObserver } from "@vueuse/core";
+import { useI18n } from "#imports";
+import { useProseAppearance } from "../../composables/useProseAppearance";
+
+const props = defineProps<{ appearance?: "quiet" | "tint" }>();
+const appearance = useProseAppearance("code", () => props.appearance);
+// The clipped code block must render on the surface the collapse declares.
+provide("contentCodeAppearance", appearance);
+
+// Clips tall authored content (usually a long code block) at a fixed height
+// until the reader expands it. Expanding removes the cap entirely, so the page
+// owns scrolling instead of a nested scroll area.
+const { t } = useI18n();
+const regionId = useId();
+const region = ref<HTMLElement | null>(null);
+const expanded = ref(false);
+const overflows = ref(false);
+const lineCount = ref(0);
+
+function measure() {
+  const el = region.value;
+  if (!el) return;
+  overflows.value = el.scrollHeight - el.clientHeight > 2;
+}
+
+onMounted(() => {
+  lineCount.value = region.value?.querySelectorAll("pre .line").length ?? 0;
+  measure();
+});
+useResizeObserver(region, measure);
+
+const label = computed(() =>
+  lineCount.value ? t("docs.showAllLines", { count: lineCount.value }) : t("docs.showMore"),
+);
+</script>
+
+<template>
+  <div class="content-collapse" :data-appearance="appearance">
+    <div
+      :id="regionId"
+      ref="region"
+      class="content-collapse-region"
+      :data-collapsed="!expanded || undefined"
+    >
+      <slot />
+    </div>
+    <div v-if="!expanded && overflows" class="content-collapse-fade">
+      <button
+        type="button"
+        class="content-collapse-button"
+        :aria-controls="regionId"
+        aria-expanded="false"
+        @click="expanded = true"
+      >
+        {{ label }}
+      </button>
+    </div>
+  </div>
+</template>

package/app/components/mdc/MdcError.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="error" :class="props.class">
+  <MdcCallout
+    :title="title"
+    :icon="icon"
+    type="error"
+    :appearance="appearance"
+    :class="props.class"
+  >
     <slot />
   </MdcCallout>
 </template>

package/app/components/mdc/MdcExcerpt.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { useProseAppearance } from "../../composables/useProseAppearance";
+import { cn } from "../../utils";
+
+const props = defineProps<{
+  label?: string;
+  source?: string;
+  appearance?: "quiet" | "tint";
+  class?: HTMLAttributes["class"];
+}>();
+
+const appearance = useProseAppearance("excerpt", () => props.appearance);
+</script>
+
+<template>
+  <figure :class="cn('content-excerpt not-prose', props.class)" :data-appearance="appearance">
+    <p v-if="label" class="content-excerpt-label">
+      {{ label }}
+    </p>
+    <blockquote class="content-excerpt-body content-prose content-prose-trim">
+      <slot />
+    </blockquote>
+    <figcaption v-if="source" class="content-excerpt-source">{{ source }}</figcaption>
+  </figure>
+</template>

package/app/components/mdc/MdcFigure.vue

@@ -1,20 +1,41 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
+import { Motion } from "motion-v";
 import { computed } from "vue";
+import { useI18n } from "#imports";
+import ImageZoomDialog from "#ginko-docs/components/content/ImageZoomDialog.vue";
+import { useGinkoDocsConfig } from "#ginko-docs/composables/useGinkoDocsConfig";
 import { cn } from "../../utils";
+import { useProseAppearance } from "../../composables/useProseAppearance";
 
-const props = defineProps<{
-  src?: string;
-  alt?: string;
-  caption?: string;
-  width?: string | number;
-  height?: string | number;
-  bleed?: boolean | string;
-  aspect?: "auto" | "video" | "wide" | "square" | "portrait";
-  fit?: "cover" | "contain";
-  class?: HTMLAttributes["class"];
-}>();
+const props = withDefaults(
+  defineProps<{
+    src?: string;
+    alt?: string;
+    caption?: string;
+    width?: string | number;
+    height?: string | number;
+    bleed?: boolean | string;
+    aspect?: "auto" | "video" | "wide" | "square" | "portrait";
+    fit?: "cover" | "contain";
+    zoom?: boolean | string;
+    class?: HTMLAttributes["class"];
+    appearance?: "quiet" | "tint";
+  }>(),
+  {
+    // Vue casts an absent Boolean-typed prop to false; "auto" preserves the
+    // site-wide images.zoom default unless the author overrides it.
+    zoom: "auto",
+  },
+);
+const appearance = useProseAppearance("figure", () => props.appearance);
 
+const { t } = useI18n();
+const config = useGinkoDocsConfig();
+const zoomEnabled = computed(() => {
+  if (props.zoom === "auto") return config.images?.zoom !== false;
+  return props.zoom === true || props.zoom === "true";
+});
 const shouldBleed = computed(
   () => props.bleed === true || props.bleed === "true" || props.bleed === "outside",
 );
@@ -28,23 +49,36 @@ const aspectClass = computed(() => {
     portrait: "aspect-[4/5]",
   }[props.aspect ?? "auto"];
 });
+
+const imageClass = computed(() =>
+  cn("w-full", aspectClass.value, props.fit === "contain" ? "object-contain" : "object-cover"),
+);
 </script>
 
 <template>
   <figure
     :class="cn('content-media not-prose', props.class)"
     :data-bleed="shouldBleed ? 'true' : undefined"
+    :data-appearance="appearance"
   >
-    <img
-      v-if="src"
-      :src="src"
-      :alt="alt"
-      :width="width"
-      :height="height"
-      :class="cn('w-full', aspectClass, fit === 'contain' ? 'object-contain' : 'object-cover')"
-    />
+    <template v-if="src">
+      <ImageZoomDialog v-if="zoomEnabled" :src="src" :alt="alt" :label="caption">
+        <template #trigger="{ layoutId, transition }">
+          <button
+            type="button"
+            class="block w-full cursor-zoom-in rounded-[inherit] focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+            :aria-label="`${t('docs.zoomImage')}: ${alt ?? ''}`"
+          >
+            <Motion as-child :layout-id="layoutId" :transition="transition">
+              <img :src="src" :alt="alt" :width="width" :height="height" :class="imageClass" />
+            </Motion>
+          </button>
+        </template>
+      </ImageZoomDialog>
+      <img v-else :src="src" :alt="alt" :width="width" :height="height" :class="imageClass" />
+    </template>
     <slot />
-    <figcaption v-if="caption || alt" class="text-center">
+    <figcaption v-if="caption || alt">
       {{ caption || alt }}
     </figcaption>
   </figure>

package/app/components/mdc/MdcFiles.vue

@@ -0,0 +1,120 @@
+<script setup lang="ts">
+import type { VNode } from "vue";
+import { h, resolveComponent, useSlots } from "vue";
+import { useProseAppearance } from "../../composables/useProseAppearance";
+import { resolveFileIcon } from "../../utils/file-icons";
+
+type FileEntry = {
+  name: string;
+  path: string;
+  children?: FileEntry[];
+};
+
+const props = defineProps<{
+  active?: string;
+  annotations?: Record<string, string>;
+  appearance?: "quiet" | "tint";
+}>();
+
+const slots = useSlots();
+const appearance = useProseAppearance("files", () => props.appearance);
+
+function childrenOf(node: VNode): VNode[] {
+  if (Array.isArray(node.children)) return node.children.filter(isVNode);
+  if (node.children && typeof node.children === "object") {
+    const slot = (node.children as { default?: () => unknown }).default;
+    const children = typeof slot === "function" ? slot() : [];
+    if (Array.isArray(children)) return children.filter(isVNode);
+    return isVNode(children) ? [children] : [];
+  }
+  return [];
+}
+
+function isVNode(value: unknown): value is VNode {
+  return value !== null && typeof value === "object" && "type" in value;
+}
+
+function textOf(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.map(textOf).join("");
+  if (!isVNode(value)) return "";
+  if (typeof value.children === "string") return value.children;
+  if (value.children && typeof value.children === "object") {
+    const slot = (value.children as { default?: () => unknown }).default;
+    if (typeof slot === "function") return textOf(slot());
+  }
+  return childrenOf(value).map(textOf).join("");
+}
+
+function parseList(list: VNode, parent = ""): FileEntry[] {
+  return childrenOf(list)
+    .map((item) => {
+      const children = childrenOf(item);
+      const nested = children.length > 1 ? children.at(-1) : undefined;
+      const name = children
+        .filter((node) => node !== nested)
+        .map(textOf)
+        .join("")
+        .trim();
+      const path = parent ? `${parent}/${name}` : name;
+      return {
+        name,
+        path,
+        ...(nested ? { children: parseList(nested, path) } : {}),
+      };
+    })
+    .filter((entry) => entry.name.length > 0);
+}
+
+function renderEntries(items: FileEntry[]): VNode {
+  const Icon = resolveComponent("Icon");
+  return h(
+    "ul",
+    { class: "content-files-list" },
+    items.map((entry) => {
+      const folder = Boolean(entry.children);
+      const active = props.active === entry.path;
+      return h("li", { key: entry.path, class: "content-files-item" }, [
+        h(
+          "div",
+          {
+            class: "content-files-row",
+            "data-active": active || undefined,
+            "aria-current": active ? "true" : undefined,
+          },
+          [
+            h(Icon, {
+              name: folder ? "lucide:folder-open" : resolveFileIcon(entry.name),
+              class: "content-files-icon",
+              "aria-hidden": "true",
+            }),
+            h("span", { class: "content-files-name" }, entry.name),
+            props.annotations?.[entry.path]
+              ? h("span", { class: "content-files-annotation" }, props.annotations[entry.path])
+              : null,
+          ],
+        ),
+        entry.children?.length ? renderEntries(entry.children) : null,
+      ]);
+    }),
+  );
+}
+
+function renderFiles() {
+  const list = slots.default?.()[0];
+  const entries = list ? parseList(list) : [];
+  if (!entries.length) return null;
+  return h(
+    "div",
+    {
+      class: "content-files not-prose",
+      "data-appearance": appearance.value,
+    },
+    [renderEntries(entries)],
+  );
+}
+</script>
+
+<template>
+  <component :is="renderFiles" />
+</template>

package/app/components/mdc/MdcIdea.vue

@@ -5,12 +5,13 @@ 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="idea" :class="props.class">
+  <MdcCallout :title="title" :icon="icon" type="idea" :appearance="appearance" :class="props.class">
     <slot />
   </MdcCallout>
 </template>

package/app/components/mdc/MdcInfo.vue

@@ -5,12 +5,13 @@ 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="info" :class="props.class">
+  <MdcCallout :title="title" :icon="icon" type="info" :appearance="appearance" :class="props.class">
     <slot />
   </MdcCallout>
 </template>

package/app/components/mdc/MdcInlineToc.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import type { HTMLAttributes } from "vue";
+import { computed, inject } from "vue";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "#ginko-docs/components/ui/collapsible";
+import DocsToc from "#ginko-docs/features/docs/components/DocsToc.vue";
+import { docsTocKey } from "#ginko-docs/features/docs/toc-context";
+import { filterTocByDepth } from "#ginko-docs/utils/content";
+import { useI18n } from "#imports";
+import { cn } from "../../utils";
+
+const props = defineProps<{
+  title?: string;
+  /** Restrict to headings up to this depth (within the page TOC depth). */
+  depth?: number;
+  open?: boolean | string;
+  class?: HTMLAttributes["class"];
+}>();
+
+const { t } = useI18n();
+const pageToc = inject(docsTocKey, undefined);
+
+const items = computed(() => {
+  const all = pageToc?.value ?? [];
+  return props.depth ? filterTocByDepth(all, props.depth) : all;
+});
+
+const defaultOpen = computed(
+  () => props.open !== undefined && props.open !== false && props.open !== "false",
+);
+</script>
+
+<template>
+  <Collapsible
+    v-if="items.length"
+    :default-open="defaultOpen"
+    :class="cn('content-inline-toc not-prose', props.class)"
+  >
+    <CollapsibleTrigger class="content-inline-toc-trigger">
+      <Icon name="lucide:list" class="content-inline-toc-icon" aria-hidden="true" />
+      <span class="content-inline-toc-title">{{ title ?? t("docs.toc") }}</span>
+      <Icon name="lucide:chevron-down" class="content-inline-toc-chevron" aria-hidden="true" />
+    </CollapsibleTrigger>
+    <CollapsibleContent class="content-inline-toc-content">
+      <DocsToc :items="items" :show-title="false" />
+    </CollapsibleContent>
+  </Collapsible>
+</template>

package/app/components/{ui/dialog/DialogHeader.vue → mdc/MdcKbd.vue}

@@ -1,12 +1,10 @@
 <script setup lang="ts">
 import type { HTMLAttributes } from "vue";
-import { cn } from "#ginko-docs/lib/utils";
+import { cn } from "../../utils";
 
 const props = defineProps<{ class?: HTMLAttributes["class"] }>();
 </script>
 
 <template>
-  <div data-slot="dialog-header" :class="cn('flex flex-col gap-1.5', props.class)">
-    <slot />
-  </div>
+  <kbd :class="cn('content-kbd', props.class)"><slot /></kbd>
 </template>

package/app/components/mdc/MdcNote.vue

@@ -5,12 +5,13 @@ 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="note" :class="props.class">
+  <MdcCallout :title="title" :icon="icon" type="note" :appearance="appearance" :class="props.class">
     <slot />
   </MdcCallout>
 </template>