@writedocs/generator 0.1.0

package/src/components/ApiSchemaField.astro

@@ -0,0 +1,54 @@
+---
+// Recursive renderer for a Body/Response schema tree (SchemaRow[] from
+// openapi-render.ts's schemaRows()) - one .wd-api-param row per field,
+// same name/type/required markup and CSS as ApiPlayground.astro's own
+// path/query/header parameter rows (those classes live in that file's
+// global <style> block, not duplicated here - this component only ever
+// renders inside a page that already has ApiPlayground on it). A field
+// with nested properties (an object, or an array of objects) wraps its
+// own children in an <Expandable> - the same collapsible "Show/Hide
+// properties" control already used for hand-written Parameter/Expandable
+// content elsewhere on API pages (see Expandable.astro's own comment) -
+// rather than the flat, permanently-open, depth-indented list this used
+// to be. Collapsed by default (defaultOpen={false}, overriding
+// Expandable's own open-by-default) - a schema with several levels of
+// nesting (kitchen-sink's price/dimensions/components/manufacturer
+// example) reads better as "click to see what's inside" than as a wall
+// of every field at every depth shown at once. `<Astro.self>` recurses
+// the same way NavTree.astro's own nested sidebar groups do - same
+// established pattern in this codebase for "a tree of unknown depth, one
+// component handles every level."
+import Expandable from './Expandable.astro';
+import type { SchemaRow } from '../lib/openapi-render';
+
+interface Props {
+  rows: SchemaRow[];
+  // Request-body fields show a "required" pill (a caller genuinely needs
+  // to know); response-body fields never did, even before this component
+  // existed (a response shape doesn't have optional-vs-required in the
+  // same actionable sense a request payload does) - kept as an explicit
+  // opt-out rather than dropped, so ApiPlayground.astro's two call sites
+  // (request body, response body) can each keep their own prior behavior
+  // through this one shared, recursive renderer.
+  showRequired?: boolean;
+}
+const { rows, showRequired = true } = Astro.props as Props;
+---
+
+{
+  rows.map((row) => (
+    <div class="wd-api-param">
+      <div class="wd-api-param-head">
+        <span class="wd-api-param-name">{row.name}</span>
+        <span class="wd-api-pill wd-api-pill-type">{row.type}</span>
+        {showRequired && row.required && <span class="wd-api-pill wd-api-pill-required">required</span>}
+      </div>
+      {row.description && <p class="wd-api-param-desc">{row.description}</p>}
+      {row.children.length > 0 && (
+        <Expandable title={`${row.name} properties`} defaultOpen={false}>
+          <Astro.self rows={row.children} showRequired={showRequired} />
+        </Expandable>
+      )}
+    </div>
+  ))
+}

package/src/components/AppIcon.astro

@@ -0,0 +1,32 @@
+---
+// Renders any writedocs.json `icon` string, whichever of the two forms it
+// takes (see resolveIcon() in lib/config.ts): an Iconify icon id (looked
+// up against whatever @iconify-json/* collections are installed - see
+// astro.config.mjs) rendered as a real <svg>, or literal text/emoji
+// rendered as-is. Centralizes the icon/text branch so BaseLayout.astro
+// and Card.astro (the two places writedocs.json icon strings get rendered)
+// don't each need their own copy of the resolveIcon() call + branch.
+import { Icon } from 'astro-icon/components';
+import { resolveIcon } from '../lib/config';
+
+interface Props {
+  icon?: string;
+  class?: string;
+  // Optional inline style passthrough - Icon.astro is the one real
+  // consumer, needing this to apply its own per-instance `size`/`color`
+  // props (arbitrary values, not a fixed set of classes like every
+  // other AppIcon call site uses). Left off Props' required list and
+  // undefined by default so every existing caller (BaseLayout, Card,
+  // Badge) is unaffected.
+  style?: string;
+}
+const { icon, class: className = 'wd-icon', style } = Astro.props as Props;
+const resolved = icon ? resolveIcon(icon) : null;
+---
+{resolved && (
+  resolved.kind === 'iconify' ? (
+    <Icon name={resolved.name} class={className} style={style} />
+  ) : (
+    <span class={className} style={style}>{resolved.value}</span>
+  )
+)}

package/src/components/Badge.astro

@@ -0,0 +1,128 @@
+---
+// A small inline label - status indicators, version tags, "Beta"/"New"
+// markers - modeled on Mintlify's own Badge
+// (https://www.mintlify.com/docs/components/badge). Renders as an
+// inline <span> (not a block element) so it drops naturally into a
+// sentence, the same way <Hint> does, rather than needing its own line.
+//
+// Colors are a fixed semantic set (not arbitrary hex) using the same
+// --wd-*-accent CSS-custom-property pattern Callout.astro's own
+// .wd-callout-note/-info/-tip/-warning/-danger classes already
+// establish - one shared color per class name, everything else in the
+// component reads it via var(). Mintlify's own color list additionally
+// has white/surface/white-destructive/surface-destructive variants,
+// tied to their specific light/dark neutral-surface tokens; left out
+// here since they don't map onto this site's own (simpler) light/dark
+// token set, and "gray" already covers the neutral case.
+import AppIcon from './AppIcon.astro';
+
+interface Props {
+  color?: 'gray' | 'blue' | 'green' | 'yellow' | 'orange' | 'red' | 'purple';
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+  shape?: 'rounded' | 'pill';
+  icon?: string;
+  stroke?: boolean;
+  disabled?: boolean;
+}
+const { color = 'gray', size = 'md', shape = 'rounded', icon, stroke = false, disabled = false } =
+  Astro.props as Props;
+
+const KNOWN_COLORS = ['gray', 'blue', 'green', 'yellow', 'orange', 'red', 'purple'];
+const colorClass = KNOWN_COLORS.includes(color) ? color : 'gray';
+const KNOWN_SIZES = ['xs', 'sm', 'md', 'lg'];
+const sizeClass = KNOWN_SIZES.includes(size) ? size : 'md';
+const shapeClass = shape === 'pill' ? 'pill' : 'rounded';
+---
+
+<span
+  class:list={[
+    'wd-badge',
+    `wd-badge-${colorClass}`,
+    `wd-badge-${sizeClass}`,
+    `wd-badge-${shapeClass}`,
+    stroke && 'wd-badge-stroke',
+    disabled && 'wd-badge-disabled',
+  ]}
+>
+  {icon && <AppIcon icon={icon} class="wd-badge-icon" />}<slot />
+</span>
+<style>
+  .wd-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.35em;
+    line-height: 1;
+    font-weight: 600;
+    white-space: nowrap;
+    vertical-align: middle;
+    border: 1px solid transparent;
+    /* Filled by default - a tint of the accent color over the page
+       background, with the accent itself as the text color. */
+    background: color-mix(in srgb, var(--wd-badge-accent) 14%, var(--wd-background));
+    color: var(--wd-badge-accent);
+  }
+  /* :global() is load-bearing here, same reason as Card.astro's own
+     identical comment on its .wd-card-icon rules: AppIcon.astro
+     renders this span/svg, not Badge.astro, so it never carries
+     Badge's own scope attribute. Sized in em so it scales with
+     whichever size class is active without needing its own
+     xs/sm/md/lg variants. */
+  :global(.wd-badge-icon) {
+    display: block;
+    width: 1em;
+    height: 1em;
+    flex-shrink: 0;
+  }
+  .wd-badge-gray {
+    --wd-badge-accent: #64748b;
+  }
+  .wd-badge-blue {
+    --wd-badge-accent: #3b82f6;
+  }
+  .wd-badge-green {
+    --wd-badge-accent: #16a34a;
+  }
+  .wd-badge-yellow {
+    --wd-badge-accent: #ca8a04;
+  }
+  .wd-badge-orange {
+    --wd-badge-accent: #d97706;
+  }
+  .wd-badge-red {
+    --wd-badge-accent: #dc2626;
+  }
+  .wd-badge-purple {
+    --wd-badge-accent: #9333ea;
+  }
+  /* Outline instead of filled - a subtler treatment for the same
+     color, per Mintlify's own "stroke" prop. */
+  .wd-badge-stroke {
+    background: transparent;
+    border-color: var(--wd-badge-accent);
+  }
+  .wd-badge-rounded {
+    border-radius: 0.35em;
+  }
+  .wd-badge-pill {
+    border-radius: 999px;
+  }
+  .wd-badge-xs {
+    padding: 0.05em 0.45em;
+    font-size: 0.65rem;
+  }
+  .wd-badge-sm {
+    padding: 0.1em 0.55em;
+    font-size: 0.72rem;
+  }
+  .wd-badge-md {
+    padding: 0.15em 0.65em;
+    font-size: 0.8rem;
+  }
+  .wd-badge-lg {
+    padding: 0.25em 0.8em;
+    font-size: 0.92rem;
+  }
+  .wd-badge-disabled {
+    opacity: 0.5;
+  }
+</style>

package/src/components/Callout.astro

@@ -0,0 +1,168 @@
+---
+// See src/components/{Note,Tip,Warning,Danger,Info}.astro - one thin
+// wrapper per `type` below, each just `<Callout type="x">` under the
+// hood, so a page can write either `<Callout type="info">` or the
+// shorthand `<Info>` and get an identical result. Both forms take the
+// same `title` prop.
+import AppIcon from "./AppIcon.astro";
+
+interface Props {
+  type?: "note" | "tip" | "warning" | "danger" | "info";
+  title?: string;
+  // Set automatically by remarkCalloutAnchorIds (src/lib/mdx-callout-anchor-ids.js)
+  // for every <Callout title="...">/<Note title="...">/etc. it finds in an
+  // .mdx file's own JSX, already deduped (-2, -3, ...) against every other
+  // callout title on that same page - see that plugin's own comment for
+  // why the dedup has to happen there, one level up, rather than here.
+  // Not meant to be set by hand in content; the `slugify(title)` fallback
+  // below covers every case this doesn't reach (plain .md content, a
+  // dynamic `title={expr}`, or this component used directly from a .astro
+  // file rather than through MDX).
+  _titleId?: string;
+}
+const { type = "note", title, _titleId } = Astro.props as Props;
+// FontAwesome Solid (fa6-solid, already an installed @iconify-json/*
+// collection - see astro.config.mjs's own comment on icon() needing no
+// allowlist) rather than a literal emoji, so every callout gets a real,
+// theme-colored <svg> instead of a platform-dependent glyph.
+const icons: Record<string, string> = {
+  note: "fa6-solid:note-sticky",
+  info: "fa6-solid:circle-info",
+  tip: "fa6-solid:lightbulb",
+  warning: "fa6-solid:triangle-exclamation",
+  danger: "fa6-solid:circle-xmark",
+};
+// Astro's own heading-id slugging (github-slugger, via the markdown
+// pipeline) never sees this - `title` is a component prop, not a
+// markdown heading, so it gets no id unless we make one ourselves.
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+const titleId = title ? (_titleId ?? slugify(title)) : undefined;
+---
+
+<div class:list={["wd-callout", `wd-callout-${type}`, { "wd-callout-titled": Boolean(title) }]}>
+  <AppIcon icon={icons[type]} class="wd-callout-icon" />
+  <div class="wd-callout-content">
+    {
+      title && (
+        <div class="wd-callout-title" id={titleId}>
+          {title}
+          <a class="wd-heading-anchor" href={`#${titleId}`} aria-label="Link to this section">
+            #
+          </a>
+        </div>
+      )
+    }
+    <div class="wd-callout-body"><slot /></div>
+  </div>
+</div>
+<style>
+  .wd-callout {
+    display: flex;
+    gap: 0.7rem;
+    padding: 0.85rem 1.1rem;
+    border-radius: 0.6rem;
+    border-left: 3px solid var(--wd-callout-accent);
+    background: color-mix(in srgb, var(--wd-callout-accent) 10%, var(--wd-background));
+    margin: 1.25rem 0;
+  }
+  /* A titled callout has two stacked lines (title, then body) - the icon
+     should align with the title's cap-height, not float centered across
+     the whole two-line block the way it does in the single-line,
+     untitled case above. */
+  .wd-callout.wd-callout-titled {
+    padding-block: 1rem;
+  }
+  /* :global() is load-bearing on every rule below, not just this one -
+     AppIcon.astro renders the actual <svg class="wd-callout-icon">, not
+     Callout.astro, so none of these ever carry Callout's own scope
+     attribute. A selector like `.wd-callout-icon { color: ... }` with
+     no :global() compiles to `.wd-callout-icon[data-astro-cid-x]`,
+     which can never match that svg - it silently does nothing rather
+     than erroring, which is exactly what happened here the first time
+     around (icon rendered at the right size, via the one rule that
+     *was* already global, but stayed un-colored black - the default
+     SVG fill - since its color rule was scoped and never matched).
+     Same root cause Card.astro's own icon rule already works around. */
+  :global(svg.wd-callout-icon) {
+    display: block;
+    flex-shrink: 0;
+    width: 1.15rem;
+    height: 1.15rem;
+    color: var(--wd-callout-accent);
+    fill: currentColor;
+    margin-top: 0.2rem;
+  }
+  .wd-callout-content {
+    flex: 1;
+    min-width: 0;
+  }
+  /* --wd-topbar-offset is a custom property set on <html> by
+     initTopbarOffset() (src/scripts/topbar-offset.ts) - inherits down to
+     here like any other CSS var regardless of Astro's scoping (that only
+     affects selector matching, not the ordinary property cascade), so
+     this reads the exact same live value [...slug].astro's own h2/h3/h4
+     scroll-margin-top rules do. Without it, jumping to a #callout-title
+     anchor landed the callout right at the viewport's true top edge,
+     partly hidden under the sticky topbar - the same bug those heading
+     rules exist to prevent, just missing here since this id didn't exist
+     until the anchor feature above was added. The extra flat + 1rem on
+     top of the measured topbar height (headings don't need this - a
+     heading's own text sits flush at its scroll target; a callout's
+     title sits inside the box's own 1rem top padding, `padding-block: 1rem`
+     on .wd-callout-titled above, so landing at exactly the topbar's
+     height alone still let that padding strip tuck under it, reading as
+     "still a bit cut off") is breathing room, not a topbar measurement -
+     it doesn't need to come from the live-measured var itself. */
+  .wd-callout-title {
+    font-weight: 700;
+    color: var(--wd-callout-accent);
+    margin-bottom: 0.3rem;
+    scroll-margin-top: calc(var(--wd-topbar-offset, 5rem) + 1rem);
+  }
+  /* .wd-heading-anchor's base look (color, opacity: 0, transition) comes
+     from [...slug].astro's own <style is:global> block - it already
+     applies anywhere that class shows up, headings or not. Only the
+     hover trigger needs to live here, and unlike the icon rules above,
+     no :global() is needed for it: both .wd-callout-title and the
+     anchor inside it are rendered directly by this component's own
+     template, so they both carry the same scope attribute and this
+     plain selector matches correctly as-is. */
+  .wd-callout-title:hover .wd-heading-anchor {
+    opacity: 1;
+  }
+  .wd-callout-body {
+    color: var(--wd-text);
+  }
+  .wd-callout-body :global(p:first-child) {
+    margin-top: 0;
+  }
+  .wd-callout-body :global(p:last-child) {
+    margin-bottom: 0;
+  }
+
+  /* One accent color per type, in both light and dark mode - the
+     background/border/icon/title all derive from this single value via
+     color-mix() against --wd-background (which already resolves
+     correctly per [data-theme] on its own), so there's no separate
+     [data-theme='dark'] override block needed here at all. */
+  .wd-callout-note {
+    --wd-callout-accent: #64748b;
+  }
+  .wd-callout-info {
+    --wd-callout-accent: #3b82f6;
+  }
+  .wd-callout-tip {
+    --wd-callout-accent: #16a34a;
+  }
+  .wd-callout-warning {
+    --wd-callout-accent: #d97706;
+  }
+  .wd-callout-danger {
+    --wd-callout-accent: #dc2626;
+  }
+</style>

package/src/components/Card.astro

@@ -0,0 +1,136 @@
+---
+import AppIcon from './AppIcon.astro';
+
+// Three visual variants, chosen by which optional prop is set - never more
+// than one of icon/img/method actually renders at once, but they're kept
+// as independent props (not a single `variant` union) since `icon` is
+// meant to keep working exactly as before for existing content, and `href`
+// applies identically to all three.
+interface Props {
+  title: string;
+  icon?: string;
+  // Renders a full-width image above the title instead of AppIcon's small
+  // icon - takes priority over `icon` if both are somehow set (see the
+  // template below), since a real image is the more deliberate/specific
+  // choice of the two.
+  img?: string;
+  // API-reference style: a solid, colored method badge next to the title,
+  // top-right. Same 5 known methods + fallback-gray "other" as the
+  // sidebar's own OpenAPI badges (NavTree.astro's wd-nav-method-*) and the
+  // Try-it playground's header (ApiPlayground.astro's wd-api-method-*) -
+  // this is a third, independent copy of that same get/post/put/patch/
+  // delete color set rather than a shared import, consistent with how
+  // those two already don't share one either (different visual treatment
+  // each - tinted pill in the sidebar, solid pill in the playground, solid
+  // pill here too but sized for a card heading, not worth forcing into one
+  // generic component over a handful of literal hex values).
+  method?: string;
+  href?: string;
+}
+const { title, icon, img, method, href } = Astro.props as Props;
+const Tag = href ? 'a' : 'div';
+const KNOWN_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+const methodLower = method?.toLowerCase();
+const methodClass = methodLower && KNOWN_METHODS.includes(methodLower) ? methodLower : 'other';
+---
+<Tag class="wd-card" href={href}>
+  {img && <img src={img} alt="" class="wd-card-image" />}
+  {!img && <AppIcon icon={icon} class="wd-card-icon" />}
+  <div class="wd-card-title-row">
+    <h3 class="wd-card-title">{title}</h3>
+    {
+      method && (
+        <span class:list={['wd-card-method', `wd-card-method-${methodClass}`]}>
+          {method.toUpperCase()}
+        </span>
+      )
+    }
+  </div>
+  <div class="wd-card-body"><slot /></div>
+</Tag>
+<style>
+  .wd-card {
+    display: block;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.6rem;
+    padding: 1.1rem 1.2rem;
+    text-decoration: none;
+    color: inherit;
+    transition: border-color 0.15s ease;
+  }
+  a.wd-card:hover {
+    border-color: var(--wd-primary);
+  }
+  /* :global() is load-bearing: AppIcon.astro renders this span/svg, not
+     Card.astro, so it never carries Card's own scope attribute - without
+     :global() these selectors compile to something that can never match. */
+  :global(span.wd-card-icon) {
+    display: block;
+    font-size: 1.3rem;
+  }
+  :global(svg.wd-card-icon) {
+    display: block;
+    width: 1.3rem;
+    height: 1.3rem;
+  }
+  .wd-card-image {
+    display: block;
+    width: 100%;
+    height: 9rem;
+    object-fit: cover;
+    border-radius: 0.4rem;
+    background: var(--wd-surface);
+  }
+  /* Same 0.4rem/0.3rem the title itself used to carry directly, moved up
+     onto this wrapper so it stays correct whether the row holds just a
+     title (icon/img/no-icon variants) or a title + method badge side by
+     side - a flex row's own margin does the same job a block element's
+     margin did, without changing how any existing (no-method) card looks. */
+  .wd-card-title-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+    margin: 0.4rem 0 0.3rem;
+  }
+  .wd-card-title {
+    margin: 0;
+    font-size: 1rem;
+  }
+  .wd-card-method {
+    flex-shrink: 0;
+    display: inline-block;
+    padding: 0.2rem 0.55rem;
+    border-radius: 0.3rem;
+    font-size: 0.72rem;
+    font-weight: 700;
+    letter-spacing: 0.02em;
+    color: #fff;
+  }
+  .wd-card-method-get {
+    background: #16a34a;
+  }
+  .wd-card-method-post {
+    background: #2563eb;
+  }
+  .wd-card-method-put {
+    background: #9333ea;
+  }
+  .wd-card-method-patch {
+    background: #d97706;
+  }
+  .wd-card-method-delete {
+    background: #dc2626;
+  }
+  .wd-card-method-other {
+    background: var(--wd-text-muted);
+  }
+  .wd-card-body {
+    font-size: 0.9rem;
+    color: var(--wd-text-muted);
+    margin: 0;
+  }
+  .wd-card-body :global(p) {
+    margin: 0;
+  }
+</style>

package/src/components/CardGroup.astro

@@ -0,0 +1,20 @@
+---
+interface Props {
+  cols?: number;
+}
+const { cols = 2 } = Astro.props as Props;
+---
+<div class="wd-card-group" style={`--wd-cols: ${cols}`}>
+  <slot />
+</div>
+<style>
+  .wd-card-group {
+    display: grid;
+    grid-template-columns: repeat(var(--wd-cols), minmax(0, 1fr));
+    gap: 1rem;
+    margin: 1.25rem 0;
+  }
+  @media (max-width: 640px) {
+    .wd-card-group { grid-template-columns: 1fr; }
+  }
+</style>