andesine 0.1.0 → 0.4.0

package/dist/templates/pages/src/components/content/card-grid.astro

@@ -0,0 +1 @@
+<div class="my-2 grid gap-4 sm:grid-cols-2"><slot /></div>

package/dist/templates/pages/src/components/content/card.astro

@@ -0,0 +1,31 @@
+---
+interface Props {
+  title: string;
+  /** Card text; the slot content can be used instead. */
+  description?: string;
+  icon?: string;
+  /** Makes the whole card a link. */
+  href?: string;
+}
+
+const { title, description, icon, href } = Astro.props;
+const Element = href ? "a" : "div";
+---
+
+<Element
+  href={href}
+  class:list={[
+    "not-prose flex flex-col gap-2 rounded-xl border border-gray-200 bg-white p-4 shadow-[0_0_12px_0px] shadow-gray-200",
+    href && "transition duration-200 ease-out @hover:bg-gray-100 focus-visible:bg-gray-100"
+  ]}
+>
+  {icon && <span aria-hidden="true" class:list={["h-6 w-6 bg-gradient-to-tr", icon]} />}
+  <span class="flex items-center gap-1 font-semibold text-gray-900">
+    {title}
+    {href && <span aria-hidden="true" class="i-lucide:arrow-right h-4 w-4 text-gray-400" />}
+  </span>
+  <div class="text-sm text-gray-500 [&>p]:m-0">
+    {description && <p>{description}</p>}
+    <slot />
+  </div>
+</Element>

package/dist/templates/pages/src/components/content/code-block.astro

@@ -0,0 +1,34 @@
+---
+import { ScrollArea } from "../primitives/scroll-area";
+import { CopyButton } from "./copy-button";
+
+interface Props {
+  "data-language"?: string;
+  "data-title"?: string;
+  [attribute: string]: unknown;
+}
+
+// Shiki's inline background and class are replaced by the card styles.
+const {
+  "data-language": language,
+  "data-title": title,
+  "class": _class,
+  "style": _style,
+  ...rest
+} = Astro.props;
+---
+
+<figure
+  data-code
+  class="not-prose my-2 overflow-hidden rounded-xl border border-gray-200 bg-white shadow-[0_0_12px_0px] shadow-gray-200 [[data-code-group]_&]:(my-0 rounded-none border-none shadow-none)"
+>
+  <figcaption
+    class="flex h-9 items-center justify-between gap-2 border-b border-gray-200 pl-3 pr-1 [[data-code-group]_&]:hidden"
+  >
+    <span class="truncate font-mono text-xs text-gray-500">{title ?? language}</span>
+    <CopyButton client:visible />
+  </figcaption>
+  <ScrollArea client:visible orientation="horizontal">
+    <pre {...rest} class="p-4 font-mono text-sm leading-6 text-gray-700"><slot /></pre>
+  </ScrollArea>
+</figure>

package/dist/templates/pages/src/components/content/code-group.astro

@@ -0,0 +1,13 @@
+---
+import { renderTabs } from "@andesine/pages/astro";
+import { ContentTabs } from "./tabs";
+
+interface Props {
+  /** Code labels, added by the Andesine MDX plugin or content renderer. */
+  values: string;
+}
+
+const { values, panels } = await renderTabs(Astro.props.values, Astro.slots);
+---
+
+<ContentTabs client:visible values={values} panels={panels} syncKey="code" variant="code" />

package/dist/templates/pages/src/components/content/copy-button.tsx

@@ -0,0 +1,53 @@
+import { createClipboard } from "@andesine/ui/solid";
+import type { Component } from "solid-js";
+import { IconButton } from "../primitives/button";
+
+interface CopyButtonProps {
+  /** Copied in place of the closest code block. */
+  text?: string;
+  label?: string;
+}
+
+/** Copies `text`, or the visible code block inside the closest `[data-code]` element. */
+const CopyButton: Component<CopyButtonProps> = (props) => {
+  const clipboard = createClipboard();
+  const icon = (): string => {
+    if (clipboard.status() === true) return "i-lucide:check";
+    if (clipboard.status() === false) return "i-lucide:x";
+
+    return "i-lucide:copy";
+  };
+  const copy = (event: MouseEvent): void => {
+    if (props.text !== undefined) {
+      void clipboard.copy(props.text);
+
+      return;
+    }
+
+    const root = (event.currentTarget as HTMLElement).closest("[data-code], [data-code-group]");
+    const pre = Array.from(root?.querySelectorAll("pre") ?? []).find((element) => {
+      return element.getClientRects().length > 0;
+    });
+
+    if (pre) void clipboard.copy(pre.textContent ?? "");
+  };
+
+  return (
+    <>
+      <IconButton
+        icon={icon()}
+        variant="text"
+        size="xs"
+        text="softer"
+        aria-label={props.label ?? "Copy code"}
+        onClick={copy}
+      />
+      <span role="status" class="sr-only">
+        {clipboard.status() === true ? "Copied" : ""}
+        {clipboard.status() === false ? "Copy failed" : ""}
+      </span>
+    </>
+  );
+};
+
+export { CopyButton };

package/dist/templates/pages/src/components/content/disclosure.astro

@@ -0,0 +1,26 @@
+---
+interface Props {
+  title: string;
+  open?: boolean;
+}
+
+const { title, open } = Astro.props;
+---
+
+<details
+  open={open}
+  class="my-2 overflow-hidden rounded-xl border border-gray-200 bg-white shadow-[0_0_12px_0px] shadow-gray-200"
+>
+  <summary
+    class="not-prose flex cursor-pointer list-none items-center justify-between gap-2 min-h-9 px-4 py-1.5 font-semibold text-gray-900 transition duration-200 ease-out @hover:bg-gray-100 focus-visible:bg-gray-100 [[open]>&]:bg-gray-100 [&::-webkit-details-marker]:hidden"
+  >
+    {title}
+    <span
+      aria-hidden="true"
+      class="i-lucide:chevron-right h-4.5 w-4.5 shrink-0 text-gray-400 transition-transform duration-200 [[open]>summary>&]:rotate-90"
+    ></span>
+  </summary>
+  <div class="border-t border-gray-200 px-4 py-3 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0">
+    <slot />
+  </div>
+</details>

package/dist/templates/pages/src/components/content/figure.astro

@@ -0,0 +1,10 @@
+---
+interface Props {
+  caption: string;
+}
+---
+
+<figure class="my-2">
+  <slot />
+  <figcaption class="mt-2 text-center text-sm text-gray-500">{Astro.props.caption}</figcaption>
+</figure>

package/dist/templates/pages/src/components/content/file-tree.astro

@@ -0,0 +1,47 @@
+---
+import type { FileTreeItem } from "@andesine/pages";
+import { readFileTreeItems } from "@andesine/pages/astro";
+
+interface Props {
+  /** Items, added by the Andesine MDX plugin; nested levels get their items. */
+  items: string | FileTreeItem[];
+  nested?: boolean;
+}
+
+// Matches the app's explorer: 1.75rem rows, 24px gray icons, and a guide line per level.
+const { nested } = Astro.props;
+const items = readFileTreeItems(Astro.props.items);
+---
+
+<ul class:list={["not-prose flex flex-col gap-0.5 font-medium text-gray-700", !nested && "my-2"]}>
+  {
+    items.map((item) => (
+      <li class="flex flex-col">
+        <div class="flex min-h-7 items-center gap-1 pl-0.5">
+          <span class="flex h-6 w-6 shrink-0 items-center justify-center">
+            <span
+              aria-hidden="true"
+              class:list={[
+                "h-6 w-6 text-gray-400",
+                item.type === "folder"
+                  ? "i-material-symbols:folder-open-rounded"
+                  : "i-lucide:file-text"
+              ]}
+            />
+          </span>
+          <span class="line-clamp-1 flex-1">{item.name}</span>
+        </div>
+        {item.children.length > 0 && (
+          <div class="mt-0.5 flex">
+            <div class="flex min-w-3.5 justify-end pl-0.5">
+              <div class="h-full w-px rounded-full bg-gray-300" />
+            </div>
+            <div class="min-w-0 flex-1">
+              <Astro.self items={item.children} nested />
+            </div>
+          </div>
+        )}
+      </li>
+    ))
+  }
+</ul>

package/dist/templates/pages/src/components/content/index.ts

@@ -0,0 +1,30 @@
+import Callout from "./callout.astro";
+import Card from "./card.astro";
+import CardGrid from "./card-grid.astro";
+import CodeBlock from "./code-block.astro";
+import CodeGroup from "./code-group.astro";
+import Disclosure from "./disclosure.astro";
+import FileTree from "./file-tree.astro";
+import Figure from "./figure.astro";
+import Steps from "./steps.astro";
+import Tab from "./tab.astro";
+import Tabs from "./tabs.astro";
+import Operation from "../reference/operation.astro";
+
+/** Components for MDX content: custom elements, `pre` for code blocks, and API operations. */
+const components = {
+  Callout,
+  Card,
+  CardGrid,
+  CodeGroup,
+  Disclosure,
+  FileTree,
+  Figure,
+  Operation,
+  Steps,
+  Tab,
+  Tabs,
+  pre: CodeBlock
+};
+
+export { components };

package/dist/templates/pages/src/components/content/steps.astro

@@ -0,0 +1,16 @@
+---
+// Wraps an ordered list; each item is one step, and its first paragraph is the step title.
+---
+
+<div
+  class:list={[
+    "my-2 [&>ol]:(list-none p-0 [counter-reset:step])",
+    "[&>ol>li]:(relative m-0 pl-11 [counter-increment:step]) [&>ol>li:not(:last-child)]:pb-4",
+    "[&>ol>li]:before:(absolute left-0 top-0 flex h-7 w-7 items-center justify-center rounded-lg bg-white text-sm font-medium text-gray-700 shadow-md shadow-gray-200 outline outline-1 -outline-offset-1 outline-gray-200 content-[counter(step)])",
+    "[&>ol>li]:after:(absolute bottom-0 left-3.5 top-9 w-px rounded-full bg-gray-200 content-[''])",
+    "[&>ol>li>p:first-child]:(mb-0 mt-0.5 font-semibold text-gray-900)",
+    "[&>ol>li>*+*]:mt-1 [&>ol>li>*:last-child]:mb-0"
+  ]}
+>
+  <slot />
+</div>

package/dist/templates/pages/src/components/content/tab.astro

@@ -0,0 +1,7 @@
+---
+interface Props {
+  label: string;
+}
+---
+
+<slot />

package/dist/templates/pages/src/components/content/tabs.astro

@@ -0,0 +1,15 @@
+---
+import { renderTabs } from "@andesine/pages/astro";
+import { ContentTabs } from "./tabs";
+
+interface Props {
+  /** Tab labels, added by the Andesine MDX plugin or content renderer. */
+  values: string;
+  /** Tabs with the same key share their selection. */
+  syncKey?: string;
+}
+
+const { values, panels } = await renderTabs(Astro.props.values, Astro.slots);
+---
+
+<ContentTabs client:visible values={values} panels={panels} syncKey={Astro.props.syncKey} />

package/dist/templates/pages/src/components/content/tabs.tsx

@@ -0,0 +1,99 @@
+import { Tabs } from "@andesine/ui/solid";
+import clsx from "clsx";
+import { type Component, For, Show } from "solid-js";
+import { ScrollArea } from "../primitives/scroll-area";
+import { CopyButton } from "./copy-button";
+
+interface TabsProps {
+  values: string[];
+  syncKey?: string;
+  variant?: "content" | "code";
+  /** Rendered HTML of each tab panel. */
+  panels: string[];
+}
+
+const triggerClasses = {
+  content:
+    "cursor-pointer rounded-md px-2 py-0.5 transition duration-200 ease-out @hover:text-gray-700 focus-visible:text-gray-700 data-[selected]:(bg-white text-gray-700 shadow-md outline outline-1 outline-gray-200)",
+  // Matches the section tabs: gradient text for the current tab, a gray line on hover.
+  code: clsx(
+    "relative flex h-full cursor-pointer items-center px-1.5 font-mono transition duration-200 ease-out",
+    "@hover:text-gray-700 focus-visible:text-gray-700",
+    "after:(absolute inset-x-1.5 bottom-0 h-px bg-gray-400 opacity-0 transition-opacity duration-200 content-[''])",
+    "@hover:after:opacity-100 focus-visible:after:opacity-100",
+    "data-[selected]:(bg-gradient-to-tr bg-[length:125%_auto] bg-clip-text text-transparent! after:hidden)"
+  )
+};
+
+/** Tabs in a card: a segmented control for content, or a code header with a copy button. */
+const ContentTabs: Component<TabsProps> = (props) => {
+  const variant = (): "content" | "code" => props.variant ?? "content";
+
+  return (
+    <Tabs.Root
+      values={props.values}
+      syncKey={props.syncKey}
+      data-code-group={variant() === "code" || undefined}
+      class="not-prose my-2 overflow-hidden rounded-xl border border-gray-200 bg-white shadow-[0_0_12px_0px] shadow-gray-200"
+    >
+      <div
+        class={clsx(
+          // The standard card header: 2.25rem high, with a bottom line. The line is drawn over the
+          // header, so the tabs can scroll across the full height and their indicator sits on it.
+          "relative flex h-9 items-center gap-2",
+          "after:(pointer-events-none absolute inset-x-0 bottom-0 h-px bg-gray-200 content-[''])",
+          variant() === "code" && "pl-1.5 pr-1"
+        )}
+      >
+        {/* Many tabs scroll sideways, with a hover-only scrollbar on the bottom line. */}
+        <ScrollArea
+          orientation="horizontal"
+          class="z-1 min-w-0 flex-1 self-stretch"
+          contentClass="h-full"
+          scrollbarClass="h-1.5 px-0"
+          thumbClass="border-0"
+        >
+          <Tabs.List
+            class={clsx(
+              "relative flex h-full text-gray-500",
+              variant() === "code"
+                ? "gap-1 text-xs"
+                : "min-w-full items-center gap-1 bg-gray-100 px-1 pb-px text-sm"
+            )}
+          >
+            <For each={props.values}>
+              {(value) => (
+                <Tabs.Trigger value={value} class={clsx("shrink-0", triggerClasses[variant()])}>
+                  {value}
+                </Tabs.Trigger>
+              )}
+            </For>
+            <Show when={variant() === "code"}>
+              {/* On the header's bottom line, like the section tabs indicator. */}
+              <Tabs.Indicator class="pointer-events-none bottom-0 h-0.5 w-[var(--width)] rounded-full bg-gradient-to-r [--transition-duration:200ms] [--transition-timing-function:ease-out]" />
+            </Show>
+          </Tabs.List>
+        </ScrollArea>
+        <Show when={variant() === "code"}>
+          <div class="ml-auto flex shrink-0 items-center">
+            <CopyButton />
+          </div>
+        </Show>
+      </div>
+      <For each={props.values}>
+        {(value, index) => (
+          <Tabs.Content
+            value={value}
+            class={clsx(
+              variant() === "content" &&
+                "prose max-w-none px-4 py-3 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0"
+            )}
+            innerHTML={props.panels[index()]}
+          />
+        )}
+      </For>
+    </Tabs.Root>
+  );
+};
+
+export { ContentTabs };

package/dist/templates/pages/src/components/effects/page-scroll-shadow.tsx

@@ -0,0 +1,27 @@
+import { createScrollEdges } from "@andesine/ui/solid";
+import clsx from "clsx";
+import type { Component } from "solid-js";
+
+interface PageScrollShadowProps {
+  /** Positions the top fade below the sticky header. */
+  topClass: string;
+}
+
+const shadowClass =
+  "absolute inset-x-0 h-16 from-gray-50 to-gray-50/0 transition-opacity duration-150";
+
+/** Fades the page content at the viewport edges while it scrolls past them. */
+const PageScrollShadow: Component<PageScrollShadowProps> = (props) => {
+  const edges = createScrollEdges();
+
+  return (
+    <div aria-hidden="true" class="pointer-events-none sticky top-0 h-dvh">
+      <div
+        class={clsx(shadowClass, "bg-gradient-to-b", props.topClass, !edges.start() && "opacity-0")}
+      />
+      <div class={clsx(shadowClass, "bottom-0 bg-gradient-to-t", !edges.end() && "opacity-0")} />
+    </div>
+  );
+};
+
+export { PageScrollShadow };

package/dist/templates/pages/src/components/effects/page-scrollbar.tsx

@@ -0,0 +1,35 @@
+import { createPageScrollbar } from "@andesine/ui/solid";
+import clsx from "clsx";
+import type { Component } from "solid-js";
+
+/**
+ * The overlay page scrollbar. The native one is hidden, so pages with and without overflow have
+ * the same width. Touch screens keep their native scrollbar.
+ */
+const PageScrollbar: Component = () => {
+  const scrollbar = createPageScrollbar();
+
+  return (
+    <div
+      aria-hidden="true"
+      class={clsx(
+        "fixed inset-y-0 right-0.5 z-40 w-3 transition-opacity duration-200 media-touch:hidden",
+        scrollbar.visible() ? "opacity-100" : "opacity-0",
+        !scrollbar.thumb() && "hidden",
+        !scrollbar.interactive() && "pointer-events-none"
+      )}
+      onPointerDown={scrollbar.onTrackPointerDown}
+    >
+      <div
+        {...scrollbar.thumbHandlers}
+        class="absolute inset-x-0 cursor-default rounded-lg border-2 border-solid border-transparent bg-gray-200 bg-clip-padding shadow-inner"
+        style={{
+          top: `${scrollbar.thumb()?.top ?? 0}px`,
+          height: `${scrollbar.thumb()?.height ?? 0}px`
+        }}
+      />
+    </div>
+  );
+};
+
+export { PageScrollbar };

package/dist/templates/pages/src/components/layout/call-to-action.tsx

@@ -0,0 +1,28 @@
+import type { LinkConfig } from "@andesine/pages";
+import type { Component } from "solid-js";
+import { Button, IconButton } from "../primitives/button";
+
+interface CallToActionProps {
+  link: LinkConfig;
+}
+
+/** The main action link, after the Andesine landing page: the label, then an optional icon. */
+const CallToAction: Component<CallToActionProps> = (props) =>
+  props.link.icon ? (
+    <IconButton
+      link={props.link.href}
+      icon={props.link.icon}
+      label={props.link.label}
+      color="primary"
+      variant="outlined"
+      size="small"
+      class="flex-row-reverse gap-1 pr-1.5"
+      iconClass="opacity-50 h-4.5 w-4.5"
+    />
+  ) : (
+    <Button link={props.link.href} color="primary" variant="outlined" size="small">
+      {props.link.label}
+    </Button>
+  );
+
+export { CallToAction };

package/dist/templates/pages/src/components/layout/footer.astro

@@ -0,0 +1,44 @@
+---
+import type { PageContext } from "@andesine/pages";
+import { IconButton } from "../primitives/button";
+
+interface Props {
+  page: PageContext;
+}
+
+const { page } = Astro.props;
+const { site } = page;
+const updated =
+  page.updatedAt &&
+  new Intl.DateTimeFormat(site.language, { dateStyle: "long", timeZone: "UTC" }).format(
+    new Date(page.updatedAt)
+  );
+---
+
+<!-- A line with one item keeps it at the start: icons go left when they wrap or have no date. -->
+<footer class="flex min-h-8 flex-wrap items-center justify-between gap-4">
+  {
+    updated && (
+      <p class="text-sm text-gray-400">
+        Last updated <time datetime={page.updatedAt}>{updated}</time>
+      </p>
+    )
+  }
+  {
+    site.socialLinks.length > 0 && (
+      <div class="flex items-center gap-1">
+        {site.socialLinks.map((link) => (
+          <IconButton
+            link={link.href}
+            icon={link.icon}
+            variant="text"
+            text="softer"
+            size="small"
+            aria-label={link.label}
+            title={link.label}
+          />
+        ))}
+      </div>
+    )
+  }
+</footer>

package/dist/templates/pages/src/components/layout/group-label.tsx

@@ -0,0 +1,34 @@
+import type { BreadcrumbItem } from "@andesine/pages";
+import { Breadcrumbs } from "@andesine/ui/solid";
+import { type Component, Show } from "solid-js";
+
+interface GroupLabelProps {
+  group: BreadcrumbItem;
+}
+
+const labelClass = "bg-gradient-to-tr bg-[length:125%_auto] bg-clip-text text-transparent";
+
+/** The direct parent group of the page. */
+const GroupLabel: Component<GroupLabelProps> = (props) => (
+  <Breadcrumbs.Root>
+    <Breadcrumbs.List class="flex text-sm font-semibold">
+      <Breadcrumbs.Item class="min-w-0 truncate">
+        <Show
+          when={props.group.href}
+          fallback={<Breadcrumbs.Label class={labelClass}>{props.group.label}</Breadcrumbs.Label>}
+        >
+          {(href) => (
+            <Breadcrumbs.Link
+              href={href()}
+              class={`${labelClass} decoration-tertiary underline-offset-4 @hover:underline focus-visible:underline`}
+            >
+              {props.group.label}
+            </Breadcrumbs.Link>
+          )}
+        </Show>
+      </Breadcrumbs.Item>
+    </Breadcrumbs.List>
+  </Breadcrumbs.Root>
+);
+
+export { GroupLabel };

package/dist/templates/pages/src/components/layout/header.astro

@@ -0,0 +1,53 @@
+---
+import type { PageContext } from "@andesine/pages";
+import { IconButton } from "../primitives/button";
+import { Logo } from "../primitives/logo";
+import { SearchPalette } from "../search/search-palette";
+import { CallToAction } from "./call-to-action";
+import { SectionTabs } from "./section-tabs";
+
+interface Props {
+  page: PageContext;
+}
+
+const { page } = Astro.props;
+const { site } = page;
+---
+
+<header class="sticky top-0 z-30 col-span-full bg-gray-50">
+  <div
+    class="grid h-16 grid-cols-[minmax(0,1fr)_auto] items-center gap-4 px-4 md:(grid-cols-[17rem_minmax(0,1fr)_auto] gap-0 px-0) xl:grid-cols-[17rem_minmax(0,1fr)_17rem]"
+  >
+    <a
+      href={site.href}
+      class="min-w-0 rounded-lg text-gray-900 focus-visible:(outline outline-2 outline-offset-2 outline-tertiary) md:px-4"
+    >
+      <Logo site={site} />
+    </a>
+    <div class="hidden md:(block w-full max-w-screen-md justify-self-center px-8)">
+      {site.search && <SearchPalette client:idle search={site.search} />}
+    </div>
+    <div class="flex min-w-0 items-center justify-end gap-2 md:px-4">
+      {
+        site.search && (
+          <IconButton
+            data-search-trigger
+            icon="i-tabler:search"
+            color="contrast"
+            variant="outlined"
+            size="small"
+            text="softer"
+            class="md:hidden"
+            aria-label="Search"
+          />
+        )
+      }
+      {site.cta && <CallToAction link={site.cta} />}
+    </div>
+  </div>
+  {
+    page.sections.length > 0 && site.sectionsDisplay === "tabs" && (
+      <SectionTabs client:load sections={page.sections} />
+    )
+  }
+</header>