@minidocs/astro 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan1F
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @minidocs/astro
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Astro integration for building documentation sites from composable primitives.
+
+> [!WARNING]
+> minidocs is experimental. Until 1.0, minor versions may include breaking changes.
+
+```sh
+pnpm add @minidocs/astro @astrojs/mdx
+```
+
+```js
+// astro.config.mjs
+import mdx from '@astrojs/mdx';
+import { defineConfig } from 'astro/config';
+import minidocs from '@minidocs/astro';
+
+export default defineConfig({
+  integrations: [mdx(), minidocs({ prefix: 'docs' })],
+});
+```
+
+Requires Astro 7 and Node.js 22.22 or later. See [Getting Started](https://github.com/Ivan-1F/minidocs/blob/main/docs/src/content/docs/en/getting-started.mdx) for the rest of the setup.
+
+## License
+
+[MIT](./LICENSE)

package/dist/behaviors.d.mts

@@ -0,0 +1,114 @@
+//#region src/behaviors.d.ts
+/** Framework-agnostic behaviors for minidocs markup. Each one returns a function that undoes it. */
+/** What a sidebar remembers across page loads within a tab. */
+export interface SidebarSnapshot {
+  /** Open state of every group, keyed by `data-md-key`. */
+  open: Record<string, boolean>;
+  scroll: number;
+}
+/**
+ * Restores a sidebar to how the reader left it on the previous page, so navigating changes nothing they can see.
+ * Groups containing the current page are always open. Without a snapshot, the current page is scrolled into view.
+ *
+ * Runs inline right after the sidebar markup, before the first paint, so it must not reference anything outside itself.
+ */
+export declare function restoreSidebar(root: HTMLElement): void;
+/** Mirrors native collapsing into `data-state`, and remembers group and scroll state when the reader leaves the page. */
+export declare function attachSidebar(root: HTMLElement): () => void;
+export interface SidebarToggleDetail {
+  open: boolean;
+}
+/** Turns a button into a toggle for the element named by its `aria-controls`. */
+export declare function attachTrigger(button: HTMLButtonElement): () => void;
+export interface TocChangeDetail {
+  /** The link of the heading now being read. */
+  link: HTMLAnchorElement;
+}
+/**
+ * Marks the link of the heading being read with `aria-current="true"`. One link is always current.
+ * Each change dispatches a bubbling `md:toc-change` event with the link.
+ * A heading is passed once its top crosses its own `scroll-margin-top`, so anchor jumps and highlighting line up.
+ */
+export declare function attachToc(root: HTMLElement): () => void;
+/**
+ * Marks a Layout.Root with `data-md-resizing` while the viewport is resized.
+ * Crossing a breakpoint changes the layout, not the state, so styles turn off transitions meant for opening and closing, e.g. the drawer sliding out.
+ */
+export declare function attachLayout(root: HTMLElement): () => void;
+/**
+ * Collapses a Layout.Aside that the styles show in its collapsible form, so it starts closed above the content.
+ * Runs inline right after the aside, before the first paint, so it must not reference anything outside itself.
+ */
+export declare function restoreAside(aside: HTMLDetailsElement): void;
+/**
+ * Keeps a Layout.Aside open while the styles show it as a column, and closes it after a link inside is followed.
+ * The styles decide which form applies through --md-layout-aside-collapsible, so breakpoints live only in CSS.
+ * Its title shows the heading being read, taken from md:toc-change events.
+ */
+export declare function attachAside(aside: HTMLDetailsElement): () => void;
+/**
+ * Fills a Search.Shortcut with the shortcut of the trigger around it, one nested `<kbd>` per key as HTML suggests for key combinations.
+ * Keys follow the platform: ⌘ and other symbols on Apple platforms, Ctrl and other names elsewhere. Each carries `data-key` for styling.
+ * Without a shortcut it hides. Runs inline right after it, before the first paint, so it must not reference anything outside itself.
+ */
+export declare function restoreShortcut(kbd: HTMLElement): void;
+/** What a search panel shows: nothing typed, a first query on its way, or the outcome of the latest one. */
+export type SearchStatus = 'idle' | 'loading' | 'found' | 'empty' | 'error';
+export interface SearchContext {
+  /** Aborted once a newer query starts. */
+  signal: AbortSignal;
+  /** Values of the named controls inside the root, e.g. filters. */
+  params: URLSearchParams;
+}
+/**
+ * Runs a query on any engine. Results can have any shape, since only `render` reads them.
+ * It also runs with an empty query, e.g. to suggest recent pages; returning nothing then leaves Search.Idle on show.
+ */
+export type SearchSource<T> = (query: string, context: SearchContext) => T[] | Promise<T[]>;
+/** Renders results into the container with any renderer. Options are the elements with `role="option"`. */
+export type SearchRender<T> = (results: T[], container: HTMLElement, context: {
+  query: string;
+}) => void;
+export interface SearchOptions<T> {
+  source: SearchSource<T>;
+  render: SearchRender<T>;
+  /** Milliseconds to wait after the last keystroke before searching. */
+  debounce?: number;
+}
+export interface SearchSelectDetail {
+  /** The option that was followed, by click or Enter. */
+  option: HTMLElement;
+  query: string;
+}
+export interface SearchErrorDetail {
+  /** What the source threw. */
+  error: unknown;
+  query: string;
+}
+/**
+ * Runs the search inside a Search.Root: queries, states, keyboard navigation, the dialog and the triggers that point to it.
+ * It never changes what `render` puts in the results container; it only reads the options there.
+ * The root dispatches bubbling `md:search-open`, `md:search-close`, `md:search-select` and `md:search-error` events.
+ */
+export declare function attachSearch<T>(root: HTMLElement, { source, render, debounce }: SearchOptions<T>): () => void;
+/** A piece of highlighted text from a search engine, marked when it matched the query. */
+export interface MarkedText {
+  text: string;
+  marked: boolean;
+}
+/**
+ * Splits HTML such as an excerpt from Pagefind into plain and `<mark>`ed pieces, so any renderer can show it safely.
+ * Every other tag is dropped and only its text is kept.
+ */
+export declare function splitMarks(html: string): MarkedText[];
+declare global {
+  interface HTMLElementEventMap {
+    'md:sidebar-toggle': CustomEvent<SidebarToggleDetail>;
+    'md:toc-change': CustomEvent<TocChangeDetail>;
+    'md:search-open': CustomEvent<null>;
+    'md:search-close': CustomEvent<null>;
+    'md:search-select': CustomEvent<SearchSelectDetail>;
+    'md:search-error': CustomEvent<SearchErrorDetail>;
+  }
+}
+//#endregion