@writedocs/generator 0.4.6 → 0.4.8

package/src/components/Tile.astro

@@ -0,0 +1,65 @@
+---
+// Mintlify's <Tile> - a visual preview (the slot, usually an image or a
+// light/dark image pair) on a patterned background, with a title and
+// description under it. Usually laid out in a <Columns> grid. `title`
+// takes inline Markdown (`code`, **bold**, *italic*), like Mintlify's.
+import { inlineMarkdown } from '../lib/inline-markdown.js';
+
+interface Props {
+  href?: string;
+  title?: string;
+  description?: string;
+}
+const { href, title, description } = Astro.props as Props;
+const Tag = href ? 'a' : 'div';
+---
+<Tag class="wd-tile" href={href}>
+  <div class="wd-tile-preview"><slot /></div>
+  {title && <div class="wd-tile-title" set:html={inlineMarkdown(title)} />}
+  {description && <div class="wd-tile-description">{description}</div>}
+</Tag>
+<style>
+  .wd-tile {
+    display: block;
+    text-decoration: none;
+    color: inherit;
+  }
+  /* Dotted pattern behind the preview, drawn from the theme's own border
+     color so it reads in both themes. */
+  .wd-tile-preview {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 10rem;
+    overflow: hidden;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.6rem;
+    background-color: var(--wd-surface);
+    background-image: radial-gradient(var(--wd-border) 1px, transparent 1px);
+    background-size: 14px 14px;
+    transition: border-color 0.15s ease;
+  }
+  a.wd-tile:hover .wd-tile-preview {
+    border-color: var(--wd-primary);
+  }
+  .wd-tile-preview :global(img),
+  .wd-tile-preview :global(svg) {
+    max-width: 100%;
+    max-height: 100%;
+    object-fit: contain;
+    margin: 0;
+  }
+  .wd-tile-preview :global(p) {
+    display: contents;
+  }
+  .wd-tile-title {
+    margin-top: 0.6rem;
+    font-weight: 600;
+    color: var(--wd-text);
+  }
+  .wd-tile-description {
+    margin-top: 0.15rem;
+    font-size: 0.875rem;
+    color: var(--wd-text-muted);
+  }
+</style>

package/src/components/Tooltip.astro

@@ -0,0 +1,13 @@
+---
+// Mintlify's <Tooltip tip headline cta href> - rendered by Hint.astro,
+// which is the same inline hover bubble under writedocs' own name.
+import Hint from './Hint.astro';
+interface Props {
+  tip: string;
+  headline?: string;
+  cta?: string;
+  href?: string;
+}
+const props = Astro.props as Props;
+---
+<Hint {...props}><slot /></Hint>

package/src/components/Tree.astro

@@ -0,0 +1,213 @@
+---
+// Mintlify's <Tree> (alias <FileTree>) - a file/folder tree built from
+// <Tree.Folder> and <Tree.File> (TreeFolder.astro / TreeFile.astro,
+// attached as properties in components/compound.ts), or from a Markdown
+// list, which remarkMintlifyTreeLists (lib/mdx-mintlify.js) rewrites into
+// those same elements at build time.
+//
+// Rendered as an ARIA tree. The script below adds Mintlify's documented
+// keyboard navigation: Up/Down between visible items, Right to open a
+// folder (or step into it), Left to close it (or step out to its parent),
+// Home/End, Enter/Space to toggle, * to open every sibling folder, and
+// type-ahead to jump to an item by its first letters.
+//
+// The highlight color is the `--tree-highlight` custom property, which a
+// page can set on the tree itself: <Tree style={{ "--tree-highlight": "..." }}>.
+interface Props {
+  style?: string | Record<string, string>;
+  class?: string;
+  className?: string;
+}
+const { style, class: className, className: mintlifyClassName } = Astro.props as Props;
+---
+<ul class:list={['wd-tree', className, mintlifyClassName]} role="tree" style={style}><slot /></ul>
+<script>
+  function initTrees(root: ParentNode) {
+    root.querySelectorAll<HTMLElement>('.wd-tree').forEach((tree) => {
+      if (tree.dataset.wdInit) return;
+      tree.dataset.wdInit = 'true';
+      const items = () => Array.from(tree.querySelectorAll<HTMLElement>('.wd-tree-item'));
+      const isFolder = (el: HTMLElement) => el.classList.contains('wd-tree-folder');
+      const isOpen = (el: HTMLElement) => el.getAttribute('aria-expanded') === 'true';
+      // Visible = not inside a closed folder.
+      const visible = () =>
+        items().filter((el) => {
+          let parent = el.parentElement?.closest<HTMLElement>('.wd-tree-folder');
+          while (parent && tree.contains(parent)) {
+            if (!isOpen(parent)) return false;
+            parent = parent.parentElement?.closest<HTMLElement>('.wd-tree-folder');
+          }
+          return true;
+        });
+      const setOpen = (el: HTMLElement, open: boolean) => {
+        if (!isFolder(el) || el.classList.contains('wd-tree-static')) return;
+        el.setAttribute('aria-expanded', String(open));
+      };
+      const focus = (el: HTMLElement | undefined) => {
+        if (!el) return;
+        items().forEach((i) => (i.tabIndex = -1));
+        el.tabIndex = 0;
+        el.focus();
+      };
+      const first = items()[0];
+      if (first) first.tabIndex = 0;
+
+      tree.addEventListener('click', (e) => {
+        const row = (e.target as HTMLElement).closest('.wd-tree-row');
+        const item = row?.parentElement as HTMLElement | null;
+        if (!item || !tree.contains(item)) return;
+        if (isFolder(item)) setOpen(item, !isOpen(item));
+        focus(item);
+      });
+
+      let typed = '';
+      let typedAt = 0;
+      tree.addEventListener('keydown', (e) => {
+        const current = (e.target as HTMLElement).closest<HTMLElement>('.wd-tree-item');
+        if (!current) return;
+        const list = visible();
+        const i = list.indexOf(current);
+        const parentFolder = current.parentElement?.closest<HTMLElement>('.wd-tree-folder');
+        switch (e.key) {
+          case 'ArrowDown':
+            focus(list[i + 1]);
+            break;
+          case 'ArrowUp':
+            focus(list[i - 1]);
+            break;
+          case 'ArrowRight':
+            if (isFolder(current) && !isOpen(current) && !current.classList.contains('wd-tree-static')) setOpen(current, true);
+            else if (isFolder(current) && isOpen(current)) focus(current.querySelector<HTMLElement>('.wd-tree-item') ?? undefined);
+            break;
+          case 'ArrowLeft':
+            if (isFolder(current) && isOpen(current) && !current.classList.contains('wd-tree-static')) setOpen(current, false);
+            else if (parentFolder && tree.contains(parentFolder)) focus(parentFolder);
+            break;
+          case 'Home':
+            focus(list[0]);
+            break;
+          case 'End':
+            focus(list[list.length - 1]);
+            break;
+          case 'Enter':
+          case ' ':
+            if (isFolder(current)) setOpen(current, !isOpen(current));
+            break;
+          case '*':
+            Array.from(current.parentElement?.children ?? [])
+              .filter((el): el is HTMLElement => el instanceof HTMLElement && isFolder(el))
+              .forEach((el) => setOpen(el, true));
+            break;
+          default:
+            if (e.key.length === 1 && /\S/.test(e.key) && !e.ctrlKey && !e.metaKey && !e.altKey) {
+              const now = Date.now();
+              typed = now - typedAt > 700 ? e.key.toLowerCase() : typed + e.key.toLowerCase();
+              typedAt = now;
+              const nameOf = (el: HTMLElement) =>
+                el.querySelector(':scope > .wd-tree-row .wd-tree-name')?.textContent?.toLowerCase() ?? '';
+              // A single letter looks past the current item; a longer
+              // prefix (typed quickly) keeps matching from it, so "pa"
+              // after "p" landed on page.tsx stays there.
+              const startAt = typed.length > 1 ? i : i + 1;
+              const ordered = [...list.slice(startAt), ...list.slice(0, startAt)];
+              const match = ordered.find((el) => nameOf(el).startsWith(typed));
+              if (match) focus(match);
+              break;
+            }
+            return;
+        }
+        e.preventDefault();
+      });
+    });
+  }
+  initTrees(document);
+  document.addEventListener('astro:page-load', () => initTrees(document));
+</script>
+<style is:global>
+  .wd-tree {
+    --wd-tree-accent: var(--tree-highlight, var(--wd-primary));
+    margin: 1.25rem 0;
+    padding: 0.6rem;
+    list-style: none;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.6rem;
+    font-family: monospace;
+    font-size: 0.875rem;
+  }
+  .wd-tree .wd-tree-group {
+    margin: 0;
+    padding-left: 1.1rem;
+    list-style: none;
+  }
+  .wd-tree .wd-tree-item {
+    margin: 0;
+    padding: 0;
+    outline: none;
+  }
+  .wd-tree-folder[aria-expanded='false'] > .wd-tree-group {
+    display: none;
+  }
+  .wd-tree-row {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.2rem 0.4rem;
+    border-radius: 0.35rem;
+    color: var(--wd-text);
+    cursor: default;
+    user-select: none;
+  }
+  .wd-tree-folder:not(.wd-tree-static) > .wd-tree-row {
+    cursor: pointer;
+  }
+  .wd-tree-row:hover,
+  .wd-tree-item:focus-visible > .wd-tree-row {
+    background: var(--wd-surface);
+  }
+  .wd-tree-item:focus-visible > .wd-tree-row {
+    box-shadow: inset 0 0 0 1px var(--wd-tree-accent);
+  }
+  .wd-tree-chevron {
+    width: 0.8rem;
+    flex-shrink: 0;
+    display: inline-flex;
+    justify-content: center;
+  }
+  .wd-tree-folder > .wd-tree-row > .wd-tree-chevron::before {
+    content: '';
+    width: 0.35rem;
+    height: 0.35rem;
+    border-right: 1.5px solid var(--wd-text-muted);
+    border-bottom: 1.5px solid var(--wd-text-muted);
+    transform: rotate(-45deg);
+    transition: transform 0.12s ease;
+  }
+  .wd-tree-folder[aria-expanded='true'] > .wd-tree-row > .wd-tree-chevron::before {
+    transform: rotate(45deg);
+  }
+  .wd-tree-static > .wd-tree-row > .wd-tree-chevron::before {
+    opacity: 0.35;
+  }
+  svg.wd-tree-icon {
+    width: 1em;
+    height: 1em;
+    flex-shrink: 0;
+    color: var(--wd-text-muted);
+  }
+  .wd-tree-folder[aria-expanded='true'] > .wd-tree-row > .wd-tree-icon-closed,
+  .wd-tree-folder[aria-expanded='false'] > .wd-tree-row > .wd-tree-icon-open {
+    display: none;
+  }
+  /* The highlighted item gets a tinted row; a highlighted folder also
+     tints the text of everything inside it, so the active path reads. */
+  .wd-tree-highlight > .wd-tree-row {
+    background: color-mix(in srgb, var(--wd-tree-accent) 14%, transparent);
+    color: var(--wd-tree-accent);
+    font-weight: 600;
+  }
+  .wd-tree-highlight > .wd-tree-row .wd-tree-icon,
+  .wd-tree-folder.wd-tree-highlight .wd-tree-row,
+  .wd-tree-folder.wd-tree-highlight .wd-tree-icon {
+    color: var(--wd-tree-accent);
+  }
+</style>

package/src/components/TreeFile.astro

@@ -0,0 +1,17 @@
+---
+// Mintlify's <Tree.File name="..."> - see Tree.astro. `highlight` marks it
+// as the active item.
+import AppIcon from './AppIcon.astro';
+interface Props {
+  name: string;
+  highlight?: boolean;
+}
+const { name, highlight = false } = Astro.props as Props;
+---
+<li class:list={['wd-tree-item', 'wd-tree-file', { 'wd-tree-highlight': highlight }]} role="treeitem" tabindex="-1">
+  <span class="wd-tree-row">
+    <span class="wd-tree-chevron wd-tree-chevron-spacer" aria-hidden="true"></span>
+    <AppIcon icon="lucide:file" class="wd-tree-icon" />
+    <span class="wd-tree-name">{name}</span>
+  </span>
+</li>

package/src/components/TreeFolder.astro

@@ -0,0 +1,28 @@
+---
+// Mintlify's <Tree.Folder name="..."> - see Tree.astro. `defaultOpen`
+// starts it expanded; `openable={false}` makes it a fixed, non-toggling
+// folder (shown open or closed per `defaultOpen`); `highlight` marks it as
+// the active item and tints everything inside it.
+import AppIcon from './AppIcon.astro';
+interface Props {
+  name: string;
+  defaultOpen?: boolean;
+  openable?: boolean;
+  highlight?: boolean;
+}
+const { name, defaultOpen = false, openable = true, highlight = false } = Astro.props as Props;
+---
+<li
+  class:list={['wd-tree-item', 'wd-tree-folder', { 'wd-tree-highlight': highlight, 'wd-tree-static': !openable }]}
+  role="treeitem"
+  aria-expanded={defaultOpen ? 'true' : 'false'}
+  tabindex="-1"
+>
+  <span class="wd-tree-row">
+    <span class="wd-tree-chevron" aria-hidden="true"></span>
+    <AppIcon icon="lucide:folder" class="wd-tree-icon wd-tree-icon-closed" />
+    <AppIcon icon="lucide:folder-open" class="wd-tree-icon wd-tree-icon-open" />
+    <span class="wd-tree-name">{name}</span>
+  </span>
+  <ul class="wd-tree-group" role="group"><slot /></ul>
+</li>

package/src/components/Update.astro

@@ -0,0 +1,171 @@
+---
+// Mintlify's <Update> - one changelog entry: `label` (usually a date or
+// version) in a left column that sticks while its content scrolls, with
+// `description` and `tags` under it. The label is a linkable anchor, deduped
+// against every other anchor on the page by remarkTitleAnchorIds, same as a
+// Callout/Accordion title. Stacks into one column on narrow screens.
+//
+// When any Update on the page has `tags`, a row of tag filters appears
+// above the first one (the script below) - Mintlify shows the same filters
+// in its right-hand panel. `rss` is accepted but unused: writedocs doesn't
+// generate an RSS feed from updates.
+interface Props {
+  label: string;
+  description?: string;
+  tags?: string[];
+  rss?: { title?: string; description?: string };
+  _titleId?: string;
+}
+const { label, description, tags = [], _titleId } = Astro.props as Props;
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+const id = _titleId ?? slugify(label);
+---
+<section class="wd-update" data-update-tags={JSON.stringify(tags)}>
+  <div class="wd-update-meta">
+    <div class="wd-update-label" id={id}>
+      <a href={`#${id}`}>{label}</a>
+    </div>
+    {description && <div class="wd-update-description">{description}</div>}
+    {tags.length > 0 && (
+      <div class="wd-update-tags">
+        {tags.map((tag) => <span class="wd-update-tag">{tag}</span>)}
+      </div>
+    )}
+  </div>
+  <div class="wd-update-body"><slot /></div>
+</section>
+<script>
+  // Builds one tag-filter bar per page, before the first Update, from every
+  // Update's tags. Clicking a tag shows only the updates that have it;
+  // clicking it again (or "All") shows everything.
+  function initUpdateFilters(root: ParentNode) {
+    const updates = Array.from(root.querySelectorAll<HTMLElement>('.wd-update'));
+    if (updates.length === 0 || updates[0].dataset.wdInit) return;
+    updates.forEach((u) => (u.dataset.wdInit = 'true'));
+    const tagsOf = (u: HTMLElement): string[] => {
+      try {
+        return JSON.parse(u.dataset.updateTags ?? '[]');
+      } catch {
+        return [];
+      }
+    };
+    const allTags = [...new Set(updates.flatMap(tagsOf))];
+    if (allTags.length === 0) return;
+
+    const bar = document.createElement('div');
+    bar.className = 'wd-update-filters';
+    bar.setAttribute('role', 'toolbar');
+    bar.setAttribute('aria-label', 'Filter updates by tag');
+    let active: string | null = null;
+    const buttons: HTMLButtonElement[] = [];
+    const apply = () => {
+      updates.forEach((u) => (u.hidden = active !== null && !tagsOf(u).includes(active)));
+      buttons.forEach((b) => b.setAttribute('aria-pressed', String((b.dataset.tag ?? null) === active)));
+    };
+    for (const tag of [null, ...allTags]) {
+      const b = document.createElement('button');
+      b.type = 'button';
+      b.className = 'wd-update-filter';
+      b.textContent = tag ?? 'All';
+      if (tag !== null) b.dataset.tag = tag;
+      b.addEventListener('click', () => {
+        active = tag === null || active === tag ? null : tag;
+        apply();
+      });
+      buttons.push(b);
+      bar.appendChild(b);
+    }
+    updates[0].before(bar);
+    apply();
+  }
+  initUpdateFilters(document);
+  document.addEventListener('astro:page-load', () => initUpdateFilters(document));
+</script>
+<style>
+  .wd-update {
+    display: grid;
+    grid-template-columns: 11rem minmax(0, 1fr);
+    gap: 2rem;
+    padding: 2rem 0;
+    border-top: 1px solid var(--wd-border);
+  }
+  .wd-update:first-of-type {
+    border-top: 0;
+  }
+  .wd-update[hidden] {
+    display: none;
+  }
+  .wd-update-meta {
+    position: sticky;
+    top: calc(var(--wd-topbar-offset, 5rem) + 1rem);
+    align-self: start;
+  }
+  .wd-update-label {
+    scroll-margin-top: calc(var(--wd-topbar-offset, 5rem) + 1rem);
+  }
+  .wd-update-label a {
+    display: inline-block;
+    padding: 0.2rem 0.6rem;
+    border-radius: 999px;
+    font-size: 0.85rem;
+    font-weight: 600;
+    text-decoration: none;
+    color: var(--wd-primary);
+    background: color-mix(in srgb, var(--wd-primary) 12%, transparent);
+  }
+  .wd-update-description {
+    margin-top: 0.5rem;
+    font-size: 0.85rem;
+    color: var(--wd-text-muted);
+  }
+  .wd-update-tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.3rem;
+    margin-top: 0.5rem;
+  }
+  .wd-update-tag {
+    padding: 0.05rem 0.45rem;
+    border: 1px solid var(--wd-border);
+    border-radius: 999px;
+    font-size: 0.72rem;
+    color: var(--wd-text-muted);
+  }
+  .wd-update-body > :global(:first-child) {
+    margin-top: 0;
+  }
+  @media (max-width: 720px) {
+    .wd-update {
+      grid-template-columns: minmax(0, 1fr);
+      gap: 0.75rem;
+    }
+    .wd-update-meta {
+      position: static;
+    }
+  }
+  :global(.wd-update-filters) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+    margin: 1rem 0 0.5rem;
+  }
+  :global(.wd-update-filter) {
+    padding: 0.2rem 0.7rem;
+    border: 1px solid var(--wd-border);
+    border-radius: 999px;
+    background: none;
+    color: var(--wd-text-muted);
+    font-size: 0.8rem;
+    cursor: pointer;
+  }
+  :global(.wd-update-filter[aria-pressed='true']) {
+    border-color: var(--wd-primary);
+    color: var(--wd-primary);
+    background: color-mix(in srgb, var(--wd-primary) 10%, transparent);
+  }
+</style>