@minidocs/astro 0.0.0-stage → 0.2.0

package/src/components/callout/Root.astro

@@ -0,0 +1,14 @@
+---
+import type { CalloutType } from '@minidocs/astro';
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Decides the color in the default styles. */
+  type?: CalloutType;
+}
+
+// Same markup as the :::type and > [!TYPE] syntax renders, so both share the default styles
+const { type = 'note', class: className, ...attrs } = Astro.props;
+---
+
+<div class:list={['md-callout', className]} data-type={type} role="note" {...attrs}><slot /></div>

package/src/components/callout/Title.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'p'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<p class:list={['md-callout-title', className]} {...attrs}><slot /></p>

package/src/components/callout/index.ts

@@ -0,0 +1,2 @@
+export { default as Root } from './Root.astro';
+export { default as Title } from './Title.astro';

package/src/components/index.ts

@@ -0,0 +1,7 @@
+export * as Callout from './callout';
+export * as Layout from './layout';
+export { default as Prose } from './Prose.astro';
+export * as Pager from './pager';
+export * as Search from './search';
+export * as Sidebar from './sidebar';
+export * as Toc from './toc';

package/src/components/layout/Aside.astro

@@ -0,0 +1,29 @@
+---
+import { restoreAside } from '@minidocs/astro/behaviors';
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'details'> {
+  /** Heading of the column, and the toggle when the aside collapses above the content. */
+  title: string;
+}
+
+const { title, class: className, ...attrs } = Astro.props;
+// The empty span is filled by attachAside with the heading being read, from md:toc-change events
+// Runs before the first paint, so a collapsible aside starts closed without a flash of its contents
+const restore = `(${restoreAside})(document.currentScript.parentElement)`;
+---
+
+<details class:list={['md-layout-aside', className]} open {...attrs}>
+  <summary class="md-layout-aside-title">
+    <span class="md-layout-aside-label">{title}</span>
+    <span class="md-layout-aside-current" data-md-aside-current></span>
+  </summary>
+  <slot />
+  <script is:inline set:html={restore} />
+</details>
+
+<script>
+import { attachAside } from '@minidocs/astro/behaviors';
+
+for (const aside of document.querySelectorAll<HTMLDetailsElement>('.md-layout-aside')) attachAside(aside);
+</script>

package/src/components/layout/Header.astro

@@ -0,0 +1,18 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'header'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<header class:list={['md-layout-header', className]} {...attrs}>
+  <div class="md-layout-header-inner">
+    <slot />
+    {Astro.slots.has('end') && (
+      <div class="md-layout-header-end">
+        <slot name="end" />
+      </div>
+    )}
+  </div>
+</header>

package/src/components/layout/Main.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'main'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<main class:list={['md-layout-main', className]} {...attrs}><slot /></main>

package/src/components/layout/Root.astro

@@ -0,0 +1,15 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'div'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<div class:list={['md-layout', className]} data-md-layout {...attrs}><slot /></div>
+
+<script>
+import { attachLayout } from '@minidocs/astro/behaviors';
+
+for (const root of document.querySelectorAll<HTMLElement>('[data-md-layout]')) attachLayout(root);
+</script>

package/src/components/layout/Sidebar.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'aside'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<aside class:list={['md-layout-sidebar', className]} {...attrs}><slot /></aside>

package/src/components/layout/Title.astro

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'a'>;
+
+// Site name or logo in Layout.Header, linking home
+const { href, class: className, ...attrs } = Astro.props;
+---
+
+<a class:list={['md-layout-title', className]} href={href} {...attrs}><slot /></a>

package/src/components/layout/index.ts

@@ -0,0 +1,6 @@
+export { default as Aside } from './Aside.astro';
+export { default as Header } from './Header.astro';
+export { default as Main } from './Main.astro';
+export { default as Root } from './Root.astro';
+export { default as Sidebar } from './Sidebar.astro';
+export { default as Title } from './Title.astro';

package/src/components/pager/Label.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'span'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<span class:list={['md-pager-label', className]} {...attrs}><slot /></span>

package/src/components/pager/Link.astro

@@ -0,0 +1,12 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'a'> {
+  /** Direction of the linked page, which also decides which side the link sits on. */
+  rel: 'prev' | 'next';
+}
+
+const { href, rel, class: className, ...attrs } = Astro.props;
+---
+
+<a class:list={['md-pager-link', className]} href={href} rel={rel} {...attrs}><slot /></a>

package/src/components/pager/Root.astro

@@ -0,0 +1,12 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'nav'> {
+  /** Accessible name of the navigation, e.g. "Pagination". */
+  label?: string;
+}
+
+const { label, class: className, ...attrs } = Astro.props;
+---
+
+<nav class:list={['md-pager', className]} aria-label={label} {...attrs}><slot /></nav>

package/src/components/pager/Title.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'span'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<span class:list={['md-pager-title', className]} {...attrs}><slot /></span>

package/src/components/pager/index.ts

@@ -0,0 +1,4 @@
+export { default as Label } from './Label.astro';
+export { default as Link } from './Link.astro';
+export { default as Root } from './Root.astro';
+export { default as Title } from './Title.astro';

package/src/components/search/Count.astro

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'span'>;
+
+const { class: className, ...attrs } = Astro.props;
+// How many results the latest query found
+---
+
+<span class:list={['md-search-count', className]} data-md-search-count {...attrs}></span>

package/src/components/search/Dialog.astro

@@ -0,0 +1,14 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'dialog'> {
+  /** Accessible name of the dialog, e.g. "Search docs". */
+  label?: string;
+}
+
+const { label, class: className, ...attrs } = Astro.props;
+---
+
+<dialog class:list={['md-search-dialog', className]} aria-label={label} data-md-search-dialog {...attrs}>
+  <slot />
+</dialog>

package/src/components/search/Empty.astro

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'div'>;
+
+const { class: className, ...attrs } = Astro.props;
+// Shown when the latest query found nothing
+---
+
+<div class:list={['md-search-empty', className]} data-md-search-state="empty" hidden {...attrs}><slot /></div>

package/src/components/search/Error.astro

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'div'>;
+
+const { class: className, ...attrs } = Astro.props;
+// Shown when the source failed, e.g. in the dev server where Pagefind has no index
+---
+
+<div class:list={['md-search-error', className]} data-md-search-state="error" hidden {...attrs}><slot /></div>

package/src/components/search/Found.astro

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'div'>;
+
+const { class: className, ...attrs } = Astro.props;
+// Shown when the latest query found results, e.g. to say how many with Search.Count
+---
+
+<div class:list={['md-search-found', className]} data-md-search-state="found" hidden {...attrs}><slot /></div>

package/src/components/search/Idle.astro

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'div'>;
+
+const { class: className, ...attrs } = Astro.props;
+// Shown while nothing is typed
+---
+
+<div class:list={['md-search-idle', className]} data-md-search-state="idle" {...attrs}><slot /></div>

package/src/components/search/Input.astro

@@ -0,0 +1,26 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'input'> {
+  /** Accessible name of the input, e.g. "Search". */
+  label?: string;
+}
+
+const { label, class: className, ...attrs } = Astro.props;
+// Not type="search": in Chrome, Escape would clear it first instead of closing the dialog
+---
+
+<input
+  type="text"
+  class:list={['md-search-input', className]}
+  role="combobox"
+  aria-label={label}
+  aria-autocomplete="list"
+  aria-expanded="false"
+  autocomplete="off"
+  autocapitalize="off"
+  spellcheck="false"
+  enterkeyhint="search"
+  data-md-search-input
+  {...attrs}
+>

package/src/components/search/Loading.astro

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'div'>;
+
+const { class: className, ...attrs } = Astro.props;
+// Shown while a query is on its way, over whatever the last one left
+---
+
+<div class:list={['md-search-loading', className]} data-md-search-state="loading" hidden {...attrs}><slot /></div>

package/src/components/search/Query.astro

@@ -0,0 +1,10 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'span'>;
+
+const { class: className, ...attrs } = Astro.props;
+// The query whose outcome is shown
+---
+
+<span class:list={['md-search-query', className]} data-md-search-query {...attrs}></span>

package/src/components/search/Results.astro

@@ -0,0 +1,20 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Accessible name of the list, e.g. "Results". */
+  label?: string;
+}
+
+const { label, class: className, ...attrs } = Astro.props;
+// Filled by the render function given to attachSearch
+---
+
+<div
+  class:list={['md-search-results', className]}
+  role="listbox"
+  aria-label={label}
+  data-md-search-results
+  hidden
+  {...attrs}
+></div>

package/src/components/search/Root.astro

@@ -0,0 +1,15 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'search'> {
+  /** Lets Search.Trigger point to it, and the script that attaches the search find it. */
+  id: string;
+}
+
+const { class: className, ...attrs } = Astro.props;
+// attachSearch takes the user's source and renderer, so it is not attached here
+---
+
+<search class:list={['md-search', className]} data-md-search data-status="idle" {...attrs}>
+  <slot />
+</search>

package/src/components/search/Shortcut.astro

@@ -0,0 +1,14 @@
+---
+import { restoreShortcut } from '@minidocs/astro/behaviors';
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'kbd'>;
+
+const { class: className, ...attrs } = Astro.props;
+// Hidden from screen readers, since the trigger announces the shortcut through aria-keyshortcuts
+// Filled while the page is parsed from the shortcut of the trigger around it, so nothing flashes
+const restore = `(${restoreShortcut})(document.currentScript.previousElementSibling)`;
+---
+
+<kbd class:list={['md-search-shortcut', className]} aria-hidden="true" {...attrs}></kbd>
+<script is:inline set:html={restore} />

package/src/components/search/Trigger.astro

@@ -0,0 +1,28 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'button'> {
+  /** Id of the Search.Root to open, so the trigger can sit anywhere on the page. */
+  target: string;
+  /**
+   * Keys that press the trigger, written as in aria-keyshortcuts, e.g. "Mod+K" or "/".
+   * Mod is ⌘ on Apple platforms and Ctrl elsewhere, spaces separate alternatives, and false turns it off.
+   */
+  shortcut?: string | false;
+}
+
+const { target, shortcut = 'Mod+K', class: className, ...attrs } = Astro.props;
+// attachSearch resolves Mod for the platform and writes aria-keyshortcuts
+---
+
+<button
+  type="button"
+  class:list={['md-search-trigger', className]}
+  aria-controls={target}
+  aria-haspopup="dialog"
+  data-md-search-trigger
+  data-md-search-keys={shortcut || undefined}
+  {...attrs}
+>
+  <slot />
+</button>

package/src/components/search/index.ts

@@ -0,0 +1,13 @@
+export { default as Count } from './Count.astro';
+export { default as Dialog } from './Dialog.astro';
+export { default as Empty } from './Empty.astro';
+export { default as Error } from './Error.astro';
+export { default as Found } from './Found.astro';
+export { default as Idle } from './Idle.astro';
+export { default as Input } from './Input.astro';
+export { default as Loading } from './Loading.astro';
+export { default as Query } from './Query.astro';
+export { default as Results } from './Results.astro';
+export { default as Root } from './Root.astro';
+export { default as Shortcut } from './Shortcut.astro';
+export { default as Trigger } from './Trigger.astro';

package/src/components/sidebar/Group.astro

@@ -0,0 +1,45 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Whether the group starts expanded. */
+  open?: boolean;
+  /** Groups sharing a name form an accordion: opening one closes the others. Only for groups without `href`. */
+  name?: string;
+  /** Page of the group itself. Its title becomes a link, or a toggle while on that page. */
+  href?: string | undefined;
+  /** Whether the group's own page is the current page. */
+  current?: boolean;
+}
+
+const { open = false, name, href, current = false, class: className, ...attrs } = Astro.props;
+const classes = ['md-sidebar-group', className];
+// On its own page the title would link to itself, so it toggles instead
+const collapsible = href === undefined || current;
+const expanded = open || current;
+---
+
+{collapsible ? (
+  <details
+    class:list={classes}
+    name={href === undefined ? name : undefined}
+    open={expanded}
+    data-state={expanded ? 'open' : 'closed'}
+    data-md-sidebar-group
+    {...attrs}
+  >
+    <summary class="md-sidebar-group-title" aria-current={current ? 'page' : undefined}>
+      <slot name="label" />
+    </summary>
+    <slot />
+  </details>
+) : (
+  <div class:list={classes} data-state={expanded ? 'open' : 'closed'} data-md-sidebar-group {...attrs}>
+    <a class="md-sidebar-group-title" href={href}>
+      <slot name="label" />
+    </a>
+    <div class="md-sidebar-group-content" hidden={!expanded} data-md-sidebar-group-content>
+      <slot />
+    </div>
+  </div>
+)}

package/src/components/sidebar/Item.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'li'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<li class:list={['md-sidebar-item', className]} {...attrs}><slot /></li>

package/src/components/sidebar/Label.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'span'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<span class:list={['md-sidebar-label', className]} {...attrs}><slot /></span>

package/src/components/sidebar/Link.astro

@@ -0,0 +1,23 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'a'> {
+  /** Marks the link as the current page. */
+  current?: boolean;
+  /** Ignored. Accepted so that `nav.of(node)` can be spread onto any navigation part. */
+  open?: boolean;
+}
+
+const { href, current = false, open: _, class: className, ...attrs } = Astro.props;
+// Absolute URLs, including protocol-relative ones, leave the site
+const external = /^([a-z][a-z\d+.-]*:|\/\/)/i.test(String(href ?? ''));
+---
+
+<a
+  class:list={['md-sidebar-link', className]}
+  href={href}
+  aria-current={current ? 'page' : undefined}
+  data-external={external ? '' : undefined}
+  {...attrs}
+  ><slot /></a
+>

package/src/components/sidebar/List.astro

@@ -0,0 +1,11 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'ul'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<ul class:list={['md-sidebar-list', className]} {...attrs}>
+  <slot />
+</ul>

package/src/components/sidebar/Root.astro

@@ -0,0 +1,24 @@
+---
+import { restoreSidebar } from '@minidocs/astro/behaviors';
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'nav'> {
+  /** Accessible name of the navigation, e.g. "Docs". */
+  label?: string;
+}
+
+const { label, class: className, ...attrs } = Astro.props;
+// Runs while the page is parsed, before the first paint, so navigating does not visibly change the sidebar
+const restore = `(${restoreSidebar})(document.currentScript.closest('[data-md-sidebar]'))`;
+---
+
+<nav class:list={['md-sidebar', className]} aria-label={label} data-md-sidebar data-state="closed" {...attrs}>
+  <slot />
+  <script is:inline set:html={restore} />
+</nav>
+
+<script>
+import { attachSidebar } from '@minidocs/astro/behaviors';
+
+for (const root of document.querySelectorAll<HTMLElement>('[data-md-sidebar]')) attachSidebar(root);
+</script>

package/src/components/sidebar/Trigger.astro

@@ -0,0 +1,29 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'button'> {
+  /** Id of the sidebar to open and close. */
+  target: string;
+}
+
+const { target, class: className, ...attrs } = Astro.props;
+---
+
+<button
+  type="button"
+  class:list={['md-sidebar-trigger', className]}
+  aria-controls={target}
+  aria-expanded="false"
+  data-md-sidebar-trigger
+  {...attrs}
+>
+  <slot />
+</button>
+
+<script>
+import { attachTrigger } from '@minidocs/astro/behaviors';
+
+for (const button of document.querySelectorAll<HTMLButtonElement>('[data-md-sidebar-trigger]')) {
+  attachTrigger(button);
+}
+</script>

package/src/components/sidebar/index.ts

@@ -0,0 +1,7 @@
+export { default as Group } from './Group.astro';
+export { default as Item } from './Item.astro';
+export { default as Label } from './Label.astro';
+export { default as Link } from './Link.astro';
+export { default as List } from './List.astro';
+export { default as Root } from './Root.astro';
+export { default as Trigger } from './Trigger.astro';

package/src/components/toc/Item.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'li'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<li class:list={['md-toc-item', className]} {...attrs}><slot /></li>

package/src/components/toc/Link.astro

@@ -0,0 +1,12 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends Omit<HTMLAttributes<'a'>, 'href'> {
+  /** Id of the heading to link to. */
+  slug: string;
+}
+
+const { slug, class: className, ...attrs } = Astro.props;
+---
+
+<a class:list={['md-toc-link', className]} href={`#${slug}`} {...attrs}><slot /></a>

package/src/components/toc/List.astro

@@ -0,0 +1,11 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'ul'>;
+
+const { class: className, ...attrs } = Astro.props;
+---
+
+<ul class:list={['md-toc-list', className]} {...attrs}>
+  <slot />
+</ul>

package/src/components/toc/Root.astro

@@ -0,0 +1,20 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'nav'> {
+  /** Accessible name of the navigation, e.g. "On this page". */
+  label?: string;
+}
+
+const { label, class: className, ...attrs } = Astro.props;
+---
+
+<nav class:list={['md-toc', className]} aria-label={label} data-md-toc {...attrs}>
+  <slot />
+</nav>
+
+<script>
+import { attachToc } from '@minidocs/astro/behaviors';
+
+for (const root of document.querySelectorAll<HTMLElement>('[data-md-toc]')) attachToc(root);
+</script>