wiki-formant 0.4.0 → 0.7.0

package/dist/react.d.ts

@@ -0,0 +1,216 @@
+import { type CSSProperties, type KeyboardEvent, type ReactNode } from 'react';
+export interface SidebarOptions {
+    /**
+     * Where the reader's choice is remembered, in `localStorage`. Give each wiki
+     * its own key; they are different sites and may deserve different answers.
+     */
+    storageKey?: string;
+    /** Below this width (px) the rail defaults to closed. */
+    breakpoint?: number;
+}
+export interface SidebarState {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    /** True below `breakpoint`. Drives "close the rail after following a link". */
+    isMobile: boolean;
+    /**
+     * False until the effect has read storage and matchMedia. Render the rail
+     * without its open/closed transition while this is false, so a remembered
+     * closed rail does not animate shut on every load.
+     */
+    ready: boolean;
+}
+/**
+ * Collapse state for a wiki rail: remembered across loads, defaulted from the
+ * viewport only when the reader has never chosen.
+ *
+ * The reader's choice outranks the breakpoint. Someone who collapses the rail
+ * on a laptop and then narrows the window has still collapsed the rail.
+ */
+export declare function useCollapsibleSidebar(options?: SidebarOptions): SidebarState;
+export interface SidebarProviderProps extends SidebarOptions {
+    children: ReactNode;
+}
+/** Wrap the layout that contains both the rail and its toggle. */
+export declare function SidebarProvider({ children, ...options }: SidebarProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SidebarState | null>>;
+/**
+ * The rail's collapse state. Throws outside a provider rather than silently
+ * handing back a second, unconnected copy — two sources of truth for one rail
+ * is the failure this context exists to prevent.
+ */
+export declare function useSidebar(): SidebarState;
+export interface TocHeading {
+    id: string;
+    text: string;
+    /** 1 for `<h1>`, 2 for `<h2>`, and so on. */
+    level: number;
+}
+export interface TocClassNames {
+    root?: string;
+    button?: string;
+    label?: string;
+    list?: string;
+    item?: string;
+    /** Applied alongside `item` on the section currently under the viewport top. */
+    itemActive?: string;
+}
+export interface TableOfContentsProps {
+    /**
+     * The element holding the article. A wiki whose content streams in as blocks
+     * has to read the DOM, which is why a selector is the default route — by the
+     * time the rail mounts, the article may not be there yet.
+     *
+     * Optional when `headings` is given: a wiki that renders its article on the
+     * server already knows them and should not pay for a MutationObserver to
+     * rediscover what it just wrote.
+     */
+    containerSelector?: string;
+    /**
+     * Headings known ahead of time. Supplying these skips the DOM scan entirely;
+     * scroll-spy still runs, since that needs the rendered elements either way.
+     */
+    headings?: TocHeading[];
+    /** Re-query and re-observe when this changes. Pass the pathname. */
+    resetKey?: string;
+    classNames?: TocClassNames;
+    /** Rendered before the label. Receives the current expanded state. */
+    icon?: (expanded: boolean) => ReactNode;
+    label?: string;
+    /**
+     * Mint an id for a heading that lacks one. Wikis that inject ids server-side
+     * (see `wiki-formant/headings`) should leave this off — an id is a URL, and
+     * one minted in the browser is not the one the server published.
+     */
+    slug?: (text: string) => string;
+    /**
+     * CSS custom property holding the sticky header's height, used to place the
+     * scroll-spy line. e.g. `'--header-height'`.
+     */
+    offsetVar?: string;
+    /** Fallback offset in px when `offsetVar` is unset or unparseable. */
+    offsetFallback?: number;
+    /** Indent per heading level, in rem. Set 0 for a flat list. */
+    indentRem?: number;
+    /** Rendered instead of nothing when the article has no headings. */
+    empty?: ReactNode;
+}
+/**
+ * An "on this page" rail with scroll-spy, read from the rendered article.
+ *
+ * Both wikis this came from had written the same thing: a debounced
+ * MutationObserver to survive content arriving late, an IntersectionObserver to
+ * track the section under the viewport top, and the same reference-stability
+ * trick so an unrelated DOM mutation (a price ticker, an RSS feed) does not tear
+ * the observer down.
+ */
+export declare function TableOfContents({ containerSelector, headings: providedHeadings, resetKey, classNames, icon, label, slug, offsetVar, offsetFallback, indentRem, empty, }: TableOfContentsProps): import("react").JSX.Element;
+/**
+ * Calls `onClose` on any mousedown outside the returned ref's element.
+ *
+ * The `offsetParent` check is the whole reason this is shared. All three wikis
+ * had written this hook; only one had that line, and without it a container
+ * that is `display: none` at the current breakpoint still claims outside-clicks
+ * — so a tap anywhere on a phone dismisses a popover the reader is looking at,
+ * because the hidden desktop copy of it answered first.
+ *
+ * `onClose` is an effect dependency: wrap it in `useCallback` or hoist it, or
+ * the listener is torn down and rebuilt on every render.
+ */
+export declare function useClickOutside<T extends HTMLElement>(onClose: () => void): import("react").RefObject<T | null>;
+export interface TypeaheadOptions<T> {
+    /**
+     * Runs the search. MUST be referentially stable — a module function, a server
+     * action, or something wrapped in `useCallback` — because it is an effect
+     * dependency and an inline arrow re-runs the search on every render.
+     *
+     * The `signal` is optional to implement: a REST fetcher should forward it, a
+     * server action simply declares one parameter and ignores it.
+     */
+    fetch: (query: string, signal: AbortSignal) => Promise<T[]>;
+    onPick: (item: T) => void;
+    /** Runs after Escape has cleared the list, for surface-level dismissal. */
+    onEscape?: () => void;
+    /** Debounce, in ms. */
+    delay?: number;
+    /** Queries shorter than this never reach `fetch`. */
+    minLength?: number;
+    /** Remember results per query for this mount. */
+    cache?: boolean;
+}
+export interface TypeaheadState<T> {
+    query: string;
+    setQuery: (query: string) => void;
+    debouncedQuery: string;
+    items: T[];
+    highlight: number;
+    setHighlight: (index: number) => void;
+    isSearching: boolean;
+    onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void;
+    /** Drop the results, keep the query. For an outside click. */
+    clearItems: () => void;
+    /** Drop everything. For a pick, or a closing popover. */
+    reset: () => void;
+}
+/**
+ * The debounced-search state machine behind every typeahead on these sites.
+ *
+ * Five surfaces across the three wikis had three implementations, and no two
+ * agreed on what a search field does. This is their union, because each had a
+ * piece the others were missing:
+ *
+ *   - a **request-id guard**, so a slow response cannot paint over a newer one.
+ *     Two of the five surfaces had no guard at all: type fast enough and the
+ *     results you are reading are for a query you have already replaced.
+ *   - **keyboard navigation**. Two surfaces had none — the header dropdown of a
+ *     wiki whose search is its primary navigation was mouse-only.
+ *   - **abort and a per-query cache**, which only the third had. The cache is
+ *     per mount, not module-level, so a stale result cannot outlive the page.
+ *
+ * The debounce is inlined rather than pulled from a package: this one is nine
+ * lines, and the point of the package is to have no runtime dependencies.
+ */
+export declare function useTypeahead<T>({ fetch, onPick, onEscape, delay, minLength, cache, }: TypeaheadOptions<T>): TypeaheadState<T>;
+export interface LinkPreviewOptions<T> {
+    /**
+     * Which anchors get a card. Both wikis scope this to the article container
+     * (`a.closest('.prose-content')`) as well as testing the href, and the scope
+     * is exactly the part that differs — so the whole predicate is yours.
+     */
+    eligible: (anchor: HTMLAnchorElement) => boolean;
+    /** Resolve a preview for a href, or null for "no card". REST or server action. */
+    fetch: (href: string) => Promise<T | null>;
+    /** Must match the class on the element you spread `cardProps` onto. */
+    cardClassName?: string;
+    cardWidth?: number;
+    /** Used to decide whether the card flips above the link. */
+    cardHeight?: number;
+    /** Hover this long before fetching, in ms. */
+    showDelay?: number;
+    /** Grace period for the cursor to travel from link to card, in ms. */
+    hideDelay?: number;
+    /** Minimum gap from the viewport edge, in px. */
+    margin?: number;
+}
+export interface LinkPreviewState<T> {
+    /** The resolved preview, or null when no card should render. */
+    preview: T | null;
+    /** Spread onto your card element: position, and the keep-open handlers. */
+    cardProps: {
+        style: CSSProperties;
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+    };
+}
+/**
+ * Wikipedia-style hover cards over a rendered article.
+ *
+ * One delegated listener on `document` rather than a component per link, which
+ * is what makes this viable over an article holding hundreds of anchors. Two
+ * wikis had written the same ~90 lines: the same 350ms intent delay, the same
+ * 200ms grace so the cursor can cross the gap into the card, the same
+ * viewport-clamp arithmetic, the same per-href cache. They differed in exactly
+ * three things, and those three are the options above.
+ */
+export declare function useLinkPreview<T>({ eligible, fetch, cardClassName, cardWidth, cardHeight, showDelay, hideDelay, margin, }: LinkPreviewOptions<T>): LinkPreviewState<T>;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}