andesine 0.1.0 → 0.4.0

package/dist/templates/pages/src/components/reference/fields.astro

@@ -0,0 +1,102 @@
+---
+import type { FieldView, VariantView } from "@andesine/pages";
+import Facts from "./facts.astro";
+import { descriptionClass, labelClass, nameClass, requiredClass } from "./styles";
+
+interface Props {
+  fields: FieldView[];
+  variants?: VariantView[];
+  expanded?: boolean;
+}
+
+const { fields, variants = [], expanded = false } = Astro.props;
+const kindLabels = { oneOf: "One of", anyOf: "Any of" };
+// A schema can have both kinds; each gets its own label.
+const variantGroups = (["oneOf", "anyOf"] as const)
+  .map((kind) => variants.filter((variant) => variant.kind === kind))
+  .filter((group) => group.length > 0);
+// Nested fields have no card: a toggle, and a line below its chevron.
+const toggleClass =
+  "flex w-fit cursor-pointer list-none items-center gap-1.5 py-0.5 text-sm font-medium text-gray-500 transition duration-200 ease-out @hover:text-gray-700 focus-visible:text-gray-700 [&::-webkit-details-marker]:hidden";
+const chevronClass =
+  "i-lucide:chevron-right h-3.5 w-3.5 shrink-0 transition-transform duration-200 [[open]>summary>&]:rotate-90";
+const nestedClass = "ml-[0.4375rem] mt-2 border-l border-gray-200 pl-4";
+const countLabel = (count: number): string => `${count} ${count === 1 ? "field" : "fields"}`;
+---
+
+{
+  fields.length > 0 && (
+    <div role="list" class="divide-y divide-gray-200">
+      {fields.map((field) => {
+        const nestedCount = field.fields.length + field.variants.length;
+
+        return (
+          <div
+            role="listitem"
+            id={field.id}
+            class="flex scroll-mt-30 flex-col gap-1 py-3 first:pt-0 last:pb-0"
+          >
+            <div class="flex flex-wrap items-baseline gap-x-2 gap-y-0.5">
+              <code class={nameClass}>
+                {field.name}
+                {field.required && (
+                  <span title="Required" class={requiredClass}>
+                    *
+                  </span>
+                )}
+              </code>
+              <span class="font-mono text-xs text-gray-500">{field.type}</span>
+              {field.deprecated && (
+                <span class="text-sm font-medium text-amber-600">deprecated</span>
+              )}
+              {field.readOnly && <span class="text-sm text-gray-400">read-only</span>}
+              {field.writeOnly && <span class="text-sm text-gray-400">write-only</span>}
+            </div>
+            {field.description && <div class={descriptionClass} set:html={field.description} />}
+            <Facts facts={field.facts} />
+            {field.recursive && (
+              <a
+                href={field.recursive.href}
+                class="not-prose self-start text-sm font-medium text-gray-500 underline decoration-gray-300 underline-offset-2 @hover:text-gray-700"
+              >
+                Repeats {field.recursive.name}
+              </a>
+            )}
+            {nestedCount > 0 && (
+              <details open={expanded}>
+                <summary class={toggleClass}>
+                  <span aria-hidden="true" class={chevronClass} />
+                  {field.fields.length > 0 ? countLabel(field.fields.length) : "Options"}
+                </summary>
+                <div class={nestedClass}>
+                  <Astro.self fields={field.fields} variants={field.variants} />
+                </div>
+              </details>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  )
+}
+{
+  variantGroups.map((group, index) => (
+    <div class:list={["flex flex-col gap-1", (fields.length > 0 || index > 0) && "mt-3"]}>
+      <p class={labelClass}>{kindLabels[group[0]!.kind]}</p>
+      {group.map((variant) => (
+        <details id={variant.id} class="scroll-mt-30">
+          <summary class={toggleClass}>
+            <span aria-hidden="true" class={chevronClass} />
+            <span class="font-mono text-gray-700">{variant.label}</span>
+            <span class="font-mono text-xs font-normal">{variant.type}</span>
+          </summary>
+          <div class:list={[nestedClass, "flex flex-col gap-2"]}>
+            {variant.description && <div class={descriptionClass} set:html={variant.description} />}
+            <Facts facts={variant.facts} />
+            <Astro.self fields={variant.fields} variants={variant.variants} />
+          </div>
+        </details>
+      ))}
+    </div>
+  ))
+}

package/dist/templates/pages/src/components/reference/method-badge.astro

@@ -0,0 +1,18 @@
+---
+import { getMethodColor } from "./methods";
+
+interface Props {
+  method: string;
+}
+
+const { method } = Astro.props;
+---
+
+<span
+  class:list={[
+    "shrink-0 rounded-md bg-gray-100 font-mono text-sm font-bold uppercase",
+    getMethodColor(method)
+  ]}
+>
+  {method}
+</span>

package/dist/templates/pages/src/components/reference/methods.ts

@@ -0,0 +1,17 @@
+/** Text colors of HTTP methods, in the badges and the navigation. */
+const methodColors: Record<string, string> = {
+  get: "text-emerald-500",
+  post: "text-sky-500",
+  put: "text-amber-500",
+  patch: "text-orange-500",
+  delete: "text-red-500",
+  head: "text-violet-500",
+  options: "text-cyan-500"
+};
+const methodLabels: Record<string, string> = { delete: "DEL", options: "OPT" };
+
+const getMethodColor = (method: string): string => methodColors[method] ?? "text-gray-500";
+/** A short label that fits the navigation, e.g. `DEL` for `delete`. */
+const getMethodLabel = (method: string): string => methodLabels[method] ?? method.toUpperCase();
+
+export { getMethodColor, getMethodLabel };

package/dist/templates/pages/src/components/reference/operation.astro

@@ -0,0 +1,252 @@
+---
+import type { CodeView, MediaView } from "@andesine/pages";
+import { getOperationView, type OperationProps } from "@andesine/pages/astro";
+import Callout from "../content/callout.astro";
+import CodeBlock from "../content/code-block.astro";
+import CodeGroup from "../content/code-group.astro";
+import { CopyButton } from "../content/copy-button";
+import { ScrollArea } from "../primitives/scroll-area";
+import Fields from "./fields.astro";
+import MethodBadge from "./method-badge.astro";
+import { descriptionClass, labelClass, nameClass, requiredClass } from "./styles";
+
+/** A reference page passes `view`; an embed passes `source` and `id`, like the MDX component. */
+type Props = OperationProps;
+
+const view = await getOperationView(Astro.props);
+// Embeds sit under the headings of their page.
+const Heading = view.embedded ? "h3" : "h2";
+const [server] = view.servers;
+const serverURL = server?.url.replace(/\/$/, "") ?? "";
+const successStatus = view.responses.find((response) => response.status.startsWith("2"))?.status;
+const headingClass = view.embedded
+  ? "not-prose scroll-mt-30 text-lg font-semibold text-gray-900"
+  : "not-prose scroll-mt-30 text-xl font-semibold text-gray-900";
+const toMediaTypes = (contents: MediaView[]): string => {
+  return contents.map((media) => media.type).join(", ");
+};
+const toLabels = (examples: CodeView[]): string => {
+  return JSON.stringify(examples.map((example) => example.label));
+};
+---
+
+<div
+  class:list={[
+    "grid gap-8",
+    view.embedded
+      ? "my-6 border-y border-gray-200 py-6"
+      : "mt-4 xl:grid-cols-[minmax(0,1fr)_minmax(22rem,0.8fr)] xl:items-start"
+  ]}
+>
+  <div class="flex min-w-0 flex-col gap-8">
+    <div class="flex flex-col gap-3">
+      {
+        view.embedded && (
+          <a
+            href={view.href}
+            class="not-prose group flex w-fit items-center gap-1.5 text-lg font-semibold text-gray-900"
+          >
+            {view.title}
+            <span
+              aria-hidden="true"
+              class="i-lucide:arrow-up-right h-4.5 w-4.5 text-gray-400 transition duration-200 ease-out group-hover:text-gray-700"
+            />
+          </a>
+        )
+      }
+      {
+        view.deprecated && (
+          <div class="[&>aside]:my-0">
+            <Callout type="warning">
+              This operation is deprecated. Do not use it in new code.
+            </Callout>
+          </div>
+        )
+      }
+      <div
+        class="not-prose flex min-w-0 items-center gap-2 h-9 rounded-xl bg-gray-100 pl-3 pr-1.25"
+      >
+        <MethodBadge method={view.method} />
+        {/* Long URLs scroll on one line; the badge and the copy button stay in place. */}
+        <ScrollArea
+          client:visible
+          orientation="horizontal"
+          class="min-w-0 flex-1 self-stretch"
+          contentClass="flex h-full items-center"
+          scrollbarClass="h-1.5 px-0"
+          thumbClass="border-0"
+        >
+          <code class="whitespace-nowrap font-mono text-sm text-gray-700">
+            {serverURL && <span class="text-gray-400">{serverURL}</span>}{view.path}
+          </code>
+        </ScrollArea>
+        <div class="flex shrink-0 items-center">
+          <CopyButton client:visible text={`${serverURL}${view.path}`} label="Copy URL" />
+        </div>
+      </div>
+      {view.description && <div class:list={descriptionClass} set:html={view.description} />}
+    </div>
+    {
+      view.security.length > 0 && (
+        <section class="flex flex-col gap-3">
+          <Heading id={`${view.anchor}authentication`} class={headingClass}>
+            Authentication
+          </Heading>
+          <div role="list" class="divide-y divide-gray-200">
+            {view.security.map((requirement) => (
+              <div role="listitem" class="flex flex-col gap-1 py-3 first:pt-0 last:pb-0">
+                {requirement.length === 0 && (
+                  <span class="text-base text-gray-500">No authentication</span>
+                )}
+                {requirement.map((scheme) => (
+                  <div class="flex flex-col gap-1">
+                    <div class="flex flex-wrap items-baseline gap-x-2">
+                      <code class={nameClass}>{scheme.id}</code>
+                      <span class="font-mono text-xs text-gray-500">{scheme.label}</span>
+                    </div>
+                    {scheme.description && (
+                      <div class:list={descriptionClass} set:html={scheme.description} />
+                    )}
+                    {scheme.scopes.length > 0 && (
+                      <p class="not-prose text-sm text-gray-500">
+                        Scopes: {scheme.scopes.join(", ")}
+                      </p>
+                    )}
+                  </div>
+                ))}
+              </div>
+            ))}
+          </div>
+        </section>
+      )
+    }
+    {
+      view.parameters.map((group) => (
+        <section class="flex flex-col gap-3">
+          <Heading id={group.id} class={headingClass}>
+            {group.label}
+          </Heading>
+          <Fields fields={group.fields} />
+        </section>
+      ))
+    }
+    {
+      view.requestBody && (
+        <section class="flex flex-col gap-3">
+          <div class="flex flex-wrap items-baseline justify-between gap-x-2">
+            <Heading id={view.requestBody.id} class={headingClass}>
+              Request body
+              {view.requestBody.required && (
+                <span title="Required" class={requiredClass}>
+                  *
+                </span>
+              )}
+            </Heading>
+            <span class:list={[labelClass, "font-mono"]}>
+              {toMediaTypes(view.requestBody.contents)}
+            </span>
+          </div>
+          {view.requestBody.description && (
+            <div class:list={descriptionClass} set:html={view.requestBody.description} />
+          )}
+          {view.requestBody.contents.map((media, _, contents) => (
+            <div id={media.id} class="flex flex-col gap-3">
+              {contents.length > 1 && <p class:list={[labelClass, "font-mono"]}>{media.type}</p>}
+              <Fields fields={media.schema ? [media.schema] : []} expanded />
+            </div>
+          ))}
+        </section>
+      )
+    }
+    {
+      view.responses.length > 0 && (
+        <section class="flex flex-col gap-3">
+          <Heading id={`${view.anchor}responses`} class={headingClass}>
+            Responses
+          </Heading>
+          <div class="flex flex-col gap-2">
+            {view.responses.map((response) => {
+              const hasBody = response.headers.length + response.contents.length > 0;
+
+              return (
+                <details
+                  id={response.id}
+                  open={response.status === successStatus}
+                  class="scroll-mt-30 overflow-hidden rounded-xl border border-gray-200 bg-white"
+                >
+                  <summary class="flex cursor-pointer list-none items-center gap-2 px-3 py-2 transition duration-200 ease-out @hover:bg-gray-100 focus-visible:bg-gray-100 [&::-webkit-details-marker]:hidden">
+                    <span
+                      aria-hidden="true"
+                      class="i-lucide:chevron-right h-4 w-4 shrink-0 text-gray-400 transition-transform duration-200 [[open]>summary>&]:rotate-90"
+                    />
+                    <span class="font-mono text-sm font-semibold text-gray-900">
+                      {response.status}
+                    </span>
+                    {response.label && (
+                      <span class="text-base text-gray-500">{response.label}</span>
+                    )}
+                    <span class:list={[labelClass, "ml-auto font-mono"]}>
+                      {toMediaTypes(response.contents)}
+                    </span>
+                  </summary>
+                  <div class="flex flex-col gap-3 border-t border-gray-200 px-3 py-3">
+                    {response.description && (
+                      <div class:list={descriptionClass} set:html={response.description} />
+                    )}
+                    {response.headers.length > 0 && (
+                      <div class="flex flex-col gap-2">
+                        <p class={labelClass}>Headers</p>
+                        <Fields fields={response.headers} />
+                      </div>
+                    )}
+                    {response.contents.map((media, _, contents) => (
+                      <div id={media.id} class="flex flex-col gap-3">
+                        {contents.length > 1 && (
+                          <p class:list={[labelClass, "font-mono"]}>{media.type}</p>
+                        )}
+                        <Fields fields={media.schema ? [media.schema] : []} expanded />
+                      </div>
+                    ))}
+                    {!hasBody && !response.description && (
+                      <p class="not-prose text-base text-gray-500">No content.</p>
+                    )}
+                  </div>
+                </details>
+              );
+            })}
+          </div>
+        </section>
+      )
+    }
+  </div>
+  {
+    view.examples.length + view.responseExamples.length > 0 && (
+      <aside aria-label="Examples" class="order-first flex min-w-0 flex-col gap-4 xl:order-none">
+        {view.examples.length > 0 && (
+          <div class="flex flex-col gap-1">
+            <p class={labelClass}>Request</p>
+            <CodeGroup values={toLabels(view.examples)}>
+              {(index: number) => (
+                <CodeBlock data-language={view.examples[index]!.language}>
+                  <Fragment set:html={view.examples[index]!.html} />
+                </CodeBlock>
+              )}
+            </CodeGroup>
+          </div>
+        )}
+        {view.responseExamples.length > 0 && (
+          <div class="flex flex-col gap-1">
+            <p class={labelClass}>Response</p>
+            <CodeGroup values={toLabels(view.responseExamples)}>
+              {(index: number) => (
+                <CodeBlock data-language={view.responseExamples[index]!.language}>
+                  <Fragment set:html={view.responseExamples[index]!.html} />
+                </CodeBlock>
+              )}
+            </CodeGroup>
+          </div>
+        )}
+      </aside>
+    )
+  }
+</div>

package/dist/templates/pages/src/components/reference/styles.ts

@@ -0,0 +1,14 @@
+/** Small section labels, like the group labels of the search palette. */
+const labelClass = "not-prose px-1 py-0.5 text-xs leading-normal text-gray-400";
+
+/** Names of fields and security schemes; unlike values, not styled as inline code. */
+const nameClass = "not-prose font-mono text-sm font-semibold text-gray-900";
+
+/** Markdown descriptions, without the outer margins of their first and last blocks. */
+const descriptionClass =
+  "prose max-w-none text-gray-600 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0";
+
+/** Marks required fields, after their names. */
+const requiredClass = "font-semibold text-tertiary";
+
+export { labelClass, nameClass, descriptionClass, requiredClass };

package/dist/templates/pages/src/components/search/highlighted-text.tsx

@@ -0,0 +1,22 @@
+import { splitMatches } from "@andesine/ui/solid";
+import { type Component, For, Show } from "solid-js";
+
+interface HighlightedTextProps {
+  text: string;
+  query: string;
+}
+
+/** Shows matches of the query with gradient text, as in the Andesine app. */
+const HighlightedText: Component<HighlightedTextProps> = (props) => (
+  <For each={splitMatches(props.text, props.query)}>
+    {(part) => (
+      <Show when={part.match} fallback={part.text}>
+        <mark class="bg-transparent bg-gradient-to-tr from-secondary via-primary to-secondary bg-clip-text font-medium text-transparent">
+          {part.text}
+        </mark>
+      </Show>
+    )}
+  </For>
+);
+
+export { HighlightedText };

package/dist/templates/pages/src/components/search/search-answer.tsx

@@ -0,0 +1,123 @@
+import { type Answer, groupAnswerSources, renderAnswer } from "@andesine/pages/client";
+import type { AnswerTurn } from "@andesine/ui/solid";
+import clsx from "clsx";
+import { type Component, For, Index, Show } from "solid-js";
+import { ResultLink, SearchSkeleton } from "./search-results";
+
+interface SearchAnswerProps {
+  turns: Array<AnswerTurn<Answer>>;
+  /** Called when a link in an answer opens a page. */
+  onOpen(): void;
+}
+
+interface AnswerTurnViewProps {
+  turn: AnswerTurn<Answer>;
+  onOpen(): void;
+}
+
+const lineWidths = ["w-full", "w-3/5", "w-4/5"];
+
+const getErrorMessage = (error: unknown): string => {
+  return error instanceof Error && error.message ? error.message : "Try again later.";
+};
+const TextSkeleton: Component = () => (
+  <div aria-hidden="true" class="flex w-full max-w-9/10 flex-col gap-1.5 pl-1">
+    <For each={lineWidths}>
+      {(width) => <span class={clsx("h-3.5 animate-pulse rounded-sm bg-gray-200", width)} />}
+    </For>
+  </div>
+);
+const AnswerTurnView: Component<AnswerTurnViewProps> = (props) => {
+  const answer = (): Answer | undefined => props.turn.answer;
+  const loading = (): boolean => props.turn.status === "loading";
+  // Pages open with a full navigation, but links to the current page only change the hash.
+  const onClick = (event: MouseEvent): void => {
+    const link = (event.target as Element).closest("a");
+
+    if (link && !link.target) props.onOpen();
+  };
+
+  return (
+    <div class="flex flex-col gap-2" onClick={onClick}>
+      <div class="flex justify-end">
+        <p class="max-w-9/10 whitespace-pre-wrap rounded-lg bg-gray-100 px-2 py-1 text-sm leading-relaxed">
+          {props.turn.question}
+        </p>
+      </div>
+      <Show
+        when={answer()?.text}
+        fallback={
+          <Show when={loading()}>
+            <TextSkeleton />
+          </Show>
+        }
+      >
+        <div
+          class="prose prose-sm max-w-9/10 break-words pl-1 text-sm leading-relaxed [&>*:first-child]:mt-0 [&>*:last-child]:mb-0"
+          innerHTML={renderAnswer(answer()!)}
+        />
+      </Show>
+      <Show when={loading() && !answer()?.sourcesReceived}>
+        <SearchSkeleton compact />
+      </Show>
+      <Show when={answer()?.sources.length}>
+        <ul aria-label="Answer sources" class="m-0 flex list-none flex-col gap-0.5 p-0">
+          <For each={groupAnswerSources(answer()!.sources)}>
+            {(group) => (
+              <li class="flex items-start gap-1">
+                <div class="min-w-0 flex-1">
+                  <ResultLink
+                    href={group.href}
+                    label={group.sources[0]!.title || "Untitled"}
+                    sublabel={group.sources[0]!.collectionPath.join(" › ") || undefined}
+                    onClick={() => props.onOpen()}
+                  />
+                </div>
+                <div class="flex max-w-1/2 shrink-0 flex-wrap justify-end gap-1 py-1 pr-1">
+                  <For each={group.sources}>
+                    {(source) => {
+                      const section = source.headingPath.join(" › ") || source.title;
+
+                      return (
+                        <a
+                          href={source.href}
+                          title={section}
+                          aria-label={`Reference ${source.id}: ${source.title}, ${section}`}
+                          class="font-mono text-xs text-gray-400 focus-visible:(outline outline-2 outline-primary) media-mouse:hover:(text-gray-600 underline)"
+                        >
+                          [{source.id}]
+                        </a>
+                      );
+                    }}
+                  </For>
+                </div>
+              </li>
+            )}
+          </For>
+        </ul>
+      </Show>
+      <Show when={props.turn.status === "error"}>
+        <div
+          role="alert"
+          class="flex min-h-24 flex-col items-center justify-center gap-2 text-center"
+        >
+          <span aria-hidden="true" class="i-lucide:triangle-alert h-6 w-6 text-red-500" />
+          <span class="flex flex-col gap-0.5">
+            <span class="text-sm font-medium">Ask AI failed</span>
+            <span class="max-w-sm text-xs text-gray-400">{getErrorMessage(props.turn.error)}</span>
+          </span>
+        </div>
+      </Show>
+    </div>
+  );
+};
+/** The AI answer conversation, after the Andesine app's search answer. */
+const SearchAnswer: Component<SearchAnswerProps> = (props) => (
+  <div class="flex flex-col gap-4">
+    <Index each={props.turns}>
+      {(turn) => <AnswerTurnView turn={turn()} onOpen={props.onOpen} />}
+    </Index>
+  </div>
+);
+
+export { SearchAnswer };