blume 2.0.2 → 2.1.0

package/src/components/content/ApiPlayground.astro

@@ -0,0 +1,62 @@
+---
+// A hand-written endpoint's Try it panel and request samples, at the head of
+// its rail: the page's `<ParamField>`s become the parameters and body of an
+// operation model like a spec'd operation's (see `api-page.ts`), so the
+// playground and the samples are the OpenAPI reference's own. A page's own
+// `<RequestExample>` stands in for the generated samples, and its
+// `playground` frontmatter can drop the Try it panel (`simple`).
+import data from "blume:data";
+
+import { operationModel } from "../openapi/operation-model.ts";
+import Playground from "../openapi/Playground.astro";
+import { buildRequest, defaultValues } from "../openapi/request.ts";
+import RequestPanel from "../openapi/RequestPanel.astro";
+import { sampleLanguages } from "../openapi/snippets.ts";
+import {
+  endpointBody,
+  endpointParameters,
+  endpointSecurity,
+  endpointTarget,
+  readEndpointSpec,
+} from "./api-page.ts";
+
+interface Props {
+  /** The endpoint, as the page's plugin wrote it. */
+  spec: string;
+}
+
+const spec = readEndpointSpec(Astro.props.spec);
+const { api } = data.config;
+const { path, servers } = endpointTarget(spec.target, api.server);
+const model = operationModel({
+  method: spec.method,
+  parameters: endpointParameters(spec.fields),
+  path,
+  requestBody: endpointBody(spec.fields),
+  schemas: {},
+  security: endpointSecurity(spec.authMethod, api.auth),
+  servers,
+});
+const tryIt = spec.playground !== "simple" && api.playground.enabled;
+---
+
+{
+  tryIt && (
+    <Playground
+      model={model}
+      operation={`${spec.method} ${spec.target}`}
+      proxy={api.playground.proxy}
+      slug="api-pages"
+    />
+  )
+}
+{
+  !spec.requestExample && (
+    <RequestPanel
+      languages={sampleLanguages([])}
+      responses={{}}
+      sample={buildRequest(model, defaultValues(model))}
+      schemas={{}}
+    />
+  )
+}

package/src/components/content/ApiRail.astro

@@ -0,0 +1,19 @@
+---
+// The column `<RequestExample>` and `<ResponseExample>` pin to, which
+// `markdown/api-rail.ts` gathers at the end of the page. At `xl` it sits
+// beside the page's content, which the layout pads to make room, and sticks
+// under the header like an OpenAPI operation's sample panel; below `xl` it
+// follows the content.
+import OperationPanel from "../openapi/OperationPanel.astro";
+---
+
+<div
+  class="not-prose mt-10 xl:absolute xl:inset-y-0 xl:end-0 xl:mt-0 xl:w-[28rem]"
+  data-blume-api-rail
+>
+  <OperationPanel>
+    <div class="flex flex-col gap-4 [&>*]:my-0">
+      <slot />
+    </div>
+  </OperationPanel>
+</div>

package/src/components/content/Badge.astro

@@ -1,5 +1,5 @@
 ---
-import { STROKE, TINT } from "../colors.ts";
+import { ACCENT_STROKE, ACCENT_TINT, STROKE, TINT } from "../colors.ts";
 import Icon from "../Icon.astro";
 import { badgeColorName } from "./badge-color.ts";
 
@@ -38,10 +38,11 @@ const isDisabled = disabled === true || disabled === "true";
 const colorName = badgeColorName(variant, color);
 const customColor = colorName.startsWith("#") ? colorName : null;
 
-// The hue rows come from the shared table (see colors.ts for the contrast
-// rule); the neutral and surface rows are Badge's own.
+// The hue and theme-accent rows come from the shared table (see colors.ts for
+// the contrast rule); the neutral and surface rows are Badge's own.
 const filledColorClass: Record<string, string> = {
   ...TINT,
+  accent: ACCENT_TINT,
   gray: "bg-muted text-muted-foreground",
   surface: "bg-background text-muted-foreground ring-1 ring-border",
   "surface-destructive":
@@ -53,6 +54,7 @@ const filledColorClass: Record<string, string> = {
 
 const strokeColorClass: Record<string, string> = {
   ...STROKE,
+  accent: ACCENT_STROKE,
   gray: "border-border text-muted-foreground",
   surface: "border-border text-muted-foreground",
   "surface-destructive": "border-red-500/40 text-red-700 dark:text-red-300",

package/src/components/content/Color.astro

@@ -10,6 +10,7 @@ const { variant = "compact" } = Astro.props;
       : "grid grid-cols-2 gap-x-5 gap-y-4 sm:grid-cols-4",
   ]}
   data-blume-color={variant}
+  data-blume-narration="skip"
 >
   <slot />
 </div>

package/src/components/content/Component.astro

@@ -13,7 +13,7 @@ import data from "blume:data";
 import { CODE_PADDING_BLOCK_REM } from "../../theme/code-block-padding.ts";
 
 import { highlightCode } from "../../markdown/index.ts";
-import { withBase } from "../islands/base-path.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 import { contentStrings } from "./content-strings.ts";
 import { EXAMPLE_PANE_MIN_PX } from "./example-pane.ts";
 import Tab from "./Tab.astro";
@@ -35,7 +35,7 @@ const { content: strings } = contentStrings(data, Astro.currentLocale);
 // by their own design system (e.g. shadcn, via the configured `examples.css`).
 // The frame syncs its theme with this document before first paint.
 const previewSrc = entry
-  ? withBase(
+  ? withMountedBase(
       `${examplesBase}/${path.split("/").map(encodeURIComponent).join("/")}`
     )
   : undefined;

package/src/components/content/FileTree.astro

@@ -3,6 +3,7 @@
 
 <div
   class="not-prose my-6 rounded-blume border border-border p-5 text-sm [&_ul]:m-0! [&_ul]:list-none [&_ul]:ps-4 [&>ul]:ps-0"
+  data-blume-narration="skip"
 >
   <slot />
 </div>

package/src/components/content/GithubInfo.astro

@@ -73,6 +73,7 @@ const { content: strings } = contentStrings(data, Astro.currentLocale);
   owner && repo && (
     <a
       class="not-prose my-6 flex flex-col gap-2 rounded-blume border border-border p-4 no-underline! transition-colors hover:border-foreground/30 hover:bg-muted/40"
+      data-blume-narration="skip"
       href={`${host}/${owner}/${repo}`}
       {...NEW_TAB_ATTRS}
     >

package/src/components/content/Panel.astro

@@ -4,6 +4,7 @@ const { title } = Astro.props;
 
 <aside
   class="not-prose my-6 overflow-hidden rounded-blume border border-border/80 bg-background shadow-sm shadow-border/30"
+  data-blume-narration="skip"
   data-blume-panel
   data-blume-right-rail-item
 >

package/src/components/content/ParamField.astro

@@ -0,0 +1,25 @@
+---
+// `<ParamField query="limit" type="integer" required>`: a request parameter,
+// named by the attribute that says where it goes (`path`, `query`, `header`,
+// or `body`), with its description in the slot. On a page with `api`
+// frontmatter the fields also build that page's playground.
+import ApiField from "./ApiField.astro";
+import { paramField } from "./api-field.ts";
+import type { ParamFieldProps } from "./api-field.ts";
+
+type Props = ParamFieldProps;
+
+const { location, name } = paramField(Astro.props);
+const { default: value, deprecated, required, type } = Astro.props;
+---
+
+<ApiField
+  default={value}
+  deprecated={deprecated}
+  location={location}
+  name={name}
+  required={required}
+  type={type}
+>
+  <slot />
+</ApiField>

package/src/components/content/RequestExample.astro

@@ -0,0 +1,17 @@
+---
+// `<RequestExample>`: code blocks showing a request, one tab per titled
+// fence (or a language menu with `dropdown`). On a wide screen it pins to the
+// column beside the page (see `ApiRail.astro`), above any `<ResponseExample>`.
+import CodeGroup from "./CodeGroup.astro";
+
+interface Props {
+  /** A language menu in place of tabs. */
+  dropdown?: boolean;
+}
+
+const { dropdown = false } = Astro.props;
+---
+
+<CodeGroup dropdown={dropdown}>
+  <slot />
+</CodeGroup>

package/src/components/content/ResponseExample.astro

@@ -0,0 +1,17 @@
+---
+// `<ResponseExample>`: code blocks showing a response, one tab per titled
+// fence (or a language menu with `dropdown`). On a wide screen it pins to the
+// column beside the page (see `ApiRail.astro`), below any `<RequestExample>`.
+import CodeGroup from "./CodeGroup.astro";
+
+interface Props {
+  /** A language menu in place of tabs. */
+  dropdown?: boolean;
+}
+
+const { dropdown = false } = Astro.props;
+---
+
+<CodeGroup dropdown={dropdown}>
+  <slot />
+</CodeGroup>

package/src/components/content/ResponseField.astro

@@ -0,0 +1,32 @@
+---
+// `<ResponseField name="id" type="string" required>`: a field of the
+// response, with optional `pre` and `post` labels around its name and its
+// description in the slot.
+import ApiField from "./ApiField.astro";
+import { fieldLabels } from "./api-field.ts";
+import type { ResponseFieldProps } from "./api-field.ts";
+
+type Props = ResponseFieldProps;
+
+const {
+  default: value,
+  deprecated,
+  name,
+  post,
+  pre,
+  required,
+  type,
+} = Astro.props;
+---
+
+<ApiField
+  default={value}
+  deprecated={deprecated}
+  name={name}
+  post={fieldLabels(post)}
+  pre={fieldLabels(pre)}
+  required={required}
+  type={type}
+>
+  <slot />
+</ApiField>

package/src/components/content/Step.astro

@@ -17,6 +17,7 @@ const canRenderIcon =
 
 <div
   class="relative [counter-increment:blume-step]"
+  data-blume-step
 >
   <span class:list={[markerClass, !canRenderIcon && "before:[content:counter(blume-step)]"]}>
     {canRenderIcon && <Icon name={icon} size={14} />}

package/src/components/content/Tab.astro

@@ -44,7 +44,6 @@ const tabId = id ?? componentSlug(title);
   data-tab-id={tabId}
   data-title={title}
   id={id}
-  role="tabpanel"
 >
   <slot />
   {

package/src/components/content/Tabs.astro

@@ -237,6 +237,10 @@ const { content: strings } = contentStrings(data, Astro.currentLocale);
           }
           trigger.id = `blume-tab-${slug}-${instance}`;
           trigger.setAttribute("aria-controls", panel.id);
+          // The role rides with the labelling tab: adopted panels (CodeGroup
+          // fences, ts2js pairs, nested groups) have none of their own, and
+          // dropdown mode renders no tabs, so its panels take no role.
+          panel.setAttribute("role", "tabpanel");
           panel.setAttribute("aria-labelledby", trigger.id);
           trigger.setAttribute(
             "aria-selected",

package/src/components/content/Tile.astro

@@ -17,6 +17,7 @@ const previewPattern =
 >
   <div
     class="flex aspect-[16/9] min-h-32 items-center justify-center bg-muted/40 p-4 text-muted-foreground [&_img]:max-h-full [&_img]:max-w-full [&_svg]:max-h-full [&_svg]:max-w-full"
+    data-blume-narration="skip"
     data-blume-tile-preview
     style={previewPattern}
   >

package/src/components/content/Tooltip.astro

@@ -39,6 +39,7 @@ const tooltipId = tooltipIdFor(Astro.locals, [
   />
   <span
     class="absolute bottom-full left-1/2 z-20 mb-2 w-max max-w-[min(20rem,calc(100vw-1rem))] -translate-x-1/2 rounded-blume border border-border bg-background p-3 text-start font-sans text-foreground text-sm shadow-lg"
+    data-blume-narration="skip"
     data-blume-tooltip-panel
     id={tooltipId}
     role="tooltip"

package/src/components/content/Tree.astro

@@ -3,6 +3,7 @@
 
 <blume-tree
   class="not-prose my-6 block rounded-blume border border-border bg-background p-3 text-sm"
+  data-blume-narration="skip"
   data-blume-tree
   role="tree"
 >

package/src/components/content/TypeTable.astro

@@ -37,7 +37,10 @@ const columns = "grid grid-cols-[1fr_2fr_auto] items-center gap-4";
 
 {
   entries.length > 0 && (
-    <div class="not-prose my-6 rounded-blume border border-border bg-muted/30 p-1.5">
+    <div
+      class="not-prose my-6 rounded-blume border border-border bg-muted/30 p-1.5"
+      data-blume-narration="skip"
+    >
       <div class={`${columns} px-3 py-2 font-medium text-muted-foreground text-xs`}>
         <span>{strings.prop}</span>
         <span>{strings.type}</span>

package/src/components/content/View.astro

@@ -0,0 +1,21 @@
+---
+/**
+ * One view of a page written for several (`<View title="Python">`), as
+ * Mintlify writes them. Each distinct title is an option of the page's view
+ * picker, and blocks sharing a title show and hide together, so a page can
+ * alternate between prose everyone reads and view-specific sections. The
+ * picker and the hiding live in `ViewSwitcher.astro`; `icon` shows beside
+ * the view's name there.
+ */
+interface Props {
+  class?: string;
+  icon?: string;
+  title: string;
+}
+
+const { class: className, title } = Astro.props;
+---
+
+<div class={className} data-blume-view={title}>
+  <slot />
+</div>

package/src/components/content/ViewSwitcher.astro

@@ -0,0 +1,168 @@
+---
+import type { PageView } from "../../markdown/views.ts";
+import Icon from "../Icon.astro";
+import { VIEW_INIT_SCRIPT, viewStyle } from "./view-switcher.ts";
+
+/**
+ * The picker for a page written in `<View>` blocks, rendered above the
+ * content with the page's views (collected by `markdown/views.ts`). The
+ * style hides every other view's blocks and table of contents entries, and
+ * the inline script applies a linked or remembered choice before the views
+ * paint (see `view-switcher.ts`).
+ */
+interface Props {
+  /** The select's accessible name (`content.selectView`). */
+  label: string;
+  views: PageView[];
+}
+
+const { label, views } = Astro.props;
+const titles = views.map((view) => view.title);
+---
+
+<blume-view-switcher
+  class="not-prose mt-4 mb-8 flex items-center gap-2"
+  data-views={JSON.stringify(titles)}
+>
+  <style is:inline set:html={viewStyle(titles)} />
+  {
+    views.map(
+      (view) =>
+        view.icon && (
+          <span
+            class="inline-flex shrink-0 text-muted-foreground"
+            data-blume-view={view.title}
+          >
+            <Icon name={view.icon} size={16} />
+          </span>
+        )
+    )
+  }
+  <select
+    aria-label={label}
+    class="cursor-pointer rounded-blume border border-border bg-background px-3 py-1.5 font-medium text-foreground text-sm"
+  >
+    {views.map((view) => <option value={view.title}>{view.title}</option>)}
+  </select>
+  <script is:inline set:html={VIEW_INIT_SCRIPT} />
+</blume-view-switcher>
+
+<script>
+  import {
+    chooseView,
+    VIEW_PARAM,
+    VIEW_STORAGE_KEY,
+  } from "./view-switcher.ts";
+
+  const HEADINGS = "h2[id], h3[id], h4[id], h5[id], h6[id]";
+
+  const stored = (): string | null => {
+    try {
+      return localStorage.getItem(VIEW_STORAGE_KEY);
+    } catch {
+      return null;
+    }
+  };
+
+  /** The view holding the element a `#hash` link points at, if any. */
+  const linkedView = (): string | undefined => {
+    const id = decodeURIComponent(location.hash.slice(1));
+    const target = id ? document.getElementById(id) : null;
+    return (
+      target?.closest<HTMLElement>("article [data-blume-view]")?.dataset
+        .blumeView ?? undefined
+    );
+  };
+
+  /**
+   * Tag each table of contents entry with the view its heading is in, so the
+   * page's view style hides it with the view.
+   */
+  const tagTableOfContents = () => {
+    const views = new Map<string, string>();
+    for (const view of document.querySelectorAll<HTMLElement>(
+      "article [data-blume-view]"
+    )) {
+      for (const heading of view.querySelectorAll(HEADINGS)) {
+        views.set(heading.id, view.dataset.blumeView ?? "");
+      }
+    }
+    for (const link of document.querySelectorAll<HTMLAnchorElement>(
+      'blume-toc a[href^="#"]'
+    )) {
+      const id = decodeURIComponent(link.getAttribute("href")?.slice(1) ?? "");
+      const item = link.closest("li");
+      const title = views.get(id);
+      if (item && title) {
+        item.dataset.blumeView = title;
+      }
+    }
+  };
+
+  class BlumeViewSwitcher extends HTMLElement {
+    #titles: string[] = [];
+
+    connectedCallback() {
+      try {
+        this.#titles = JSON.parse(this.dataset.views ?? "[]");
+      } catch {
+        this.#titles = [];
+      }
+      tagTableOfContents();
+      this.#show(
+        chooseView(this.#titles, [
+          linkedView(),
+          new URL(location.href).searchParams.get(VIEW_PARAM),
+          stored(),
+        ])
+      );
+      this.querySelector("select")?.addEventListener("change", this.#onPick);
+      window.addEventListener("hashchange", this.#onHash);
+    }
+
+    disconnectedCallback() {
+      this.querySelector("select")?.removeEventListener("change", this.#onPick);
+      window.removeEventListener("hashchange", this.#onHash);
+    }
+
+    #show(title: string | undefined) {
+      if (title === undefined) {
+        return;
+      }
+      document.body.dataset.blumeView = title;
+      const select = this.querySelector("select");
+      if (select) {
+        select.value = title;
+      }
+    }
+
+    #onPick = (event: Event) => {
+      // SAFETY: the listener is only added to this picker's <select>.
+      const { value } = event.currentTarget as HTMLSelectElement;
+      this.#show(value);
+      try {
+        localStorage.setItem(VIEW_STORAGE_KEY, value);
+      } catch {
+        // Storage can be off; the choice still holds for this page.
+      }
+      // replaceState: the link stays shareable without a history entry per
+      // pick, and the client router needs the entry's state kept.
+      const url = new URL(location.href);
+      url.searchParams.set(VIEW_PARAM, value);
+      history.replaceState(history.state, "", url);
+    };
+
+    // An in-page link to a heading in another view switches to that view.
+    #onHash = () => {
+      const view = linkedView();
+      if (view && view !== document.body.dataset.blumeView) {
+        this.#show(view);
+        document.getElementById(decodeURIComponent(location.hash.slice(1)))?.scrollIntoView();
+      }
+    };
+  }
+
+  if (!customElements.get("blume-view-switcher")) {
+    customElements.define("blume-view-switcher", BlumeViewSwitcher);
+  }
+</script>

package/src/components/content/api-field.ts

@@ -0,0 +1,100 @@
+/**
+ * The props `<ParamField>` and `<ResponseField>` take, in Mintlify's shape: a
+ * parameter names its location with the attribute that carries its name
+ * (`<ParamField query="limit">`), and both take `type`, `required`,
+ * `deprecated`, and `default`; a response field adds `pre` and `post` labels
+ * around its name. Pure, so the Markdown downlevel and the playground can
+ * read fields the way the components render them.
+ */
+
+/** Where a `<ParamField>` parameter goes, in the order the attributes are checked. */
+export const PARAM_LOCATIONS = ["path", "query", "header", "body"] as const;
+
+/** A parameter's location. */
+export type ParamLocation = (typeof PARAM_LOCATIONS)[number];
+
+/** A literal value as MDX passes it: a string attribute, or an expression's data. */
+export type FieldValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | FieldValue[]
+  | { [key: string]: FieldValue };
+
+/** A boolean prop: MDX shorthand (`required`) is `true`, `required="true"` a string. */
+export type FlagProp = boolean | string;
+
+/** What both field components take. */
+export interface FieldProps {
+  /** The value used when none is given. */
+  default?: FieldValue;
+  deprecated?: FlagProp;
+  required?: FlagProp;
+  /** Free text: `string`, `integer`, `string[]`, `object`. */
+  type?: string;
+}
+
+/** `<ParamField>`: a request parameter, named by its location attribute. */
+export interface ParamFieldProps extends FieldProps {
+  body?: string;
+  header?: string;
+  /** The name, for a field with no location attribute. */
+  name?: string;
+  path?: string;
+  /** Placeholder text for the parameter's playground input. */
+  placeholder?: string;
+  query?: string;
+}
+
+/** `<ResponseField>`: a field of the response. */
+export interface ResponseFieldProps extends FieldProps {
+  name: string;
+  /** Labels after the name. */
+  post?: string | string[];
+  /** Labels before the name. */
+  pre?: string | string[];
+}
+
+/** Whether a flag prop is on. */
+export const isOn = (value?: FlagProp): boolean =>
+  value === true || value === "true";
+
+/** Where a parameter goes, and what it's called. */
+export interface ParamFieldName {
+  location?: ParamLocation;
+  name?: string;
+}
+
+/** A parameter's location and name: the first location attribute set, else `name`. */
+export const paramField = (props: ParamFieldProps): ParamFieldName => {
+  for (const location of PARAM_LOCATIONS) {
+    const name = props[location];
+    if (name !== undefined) {
+      return { location, name };
+    }
+  }
+  return { name: props.name };
+};
+
+const isText = (value: FieldValue): value is string =>
+  typeof value === "string";
+
+/** A default value as shown: text as written, anything else as JSON; `null` when there is none. */
+export const defaultLabel = (value?: FieldValue): string | null => {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  return isText(value) ? value : JSON.stringify(value);
+};
+
+/** `pre`/`post` labels as a list, whether one was written or several. */
+export const fieldLabels = (value?: string | string[]): string[] => {
+  if (value === undefined) {
+    return [];
+  }
+  return (Array.isArray(value) ? value : [value]).filter(
+    (label) => label !== ""
+  );
+};