@andesine/ui 0.4.0

package/dist/solid/types/index.d.ts

@@ -0,0 +1,432 @@
+import { Accessor, ComponentProps, JSX as JSX$1, ParentComponent } from "solid-js";
+import { Tabs as Tabs$1 } from "@ark-ui/solid/tabs";
+//#region src/solid/navigation-tree/create-navigation-tree.d.ts
+interface NavigationTreeItem {
+  id: string;
+  label: string;
+  href?: string;
+  current?: boolean;
+  /** The item contains the current page. Active groups are always expanded on load. */
+  active?: boolean;
+  children?: NavigationTreeItem[];
+}
+interface NavigationTreeOptions {
+  items: Accessor<NavigationTreeItem[]>;
+  /**
+   * Keeps expanded groups in session storage, shared by trees with the same key, so the tree
+   * stays the same between pages.
+   */
+  storageKey?: string;
+  /** Groups up to this depth start expanded, e.g. `2` for the first two levels. */
+  defaultDepth?: number;
+}
+interface NavigationTree$1 {
+  isExpanded(id: string): boolean;
+  setExpanded(id: string, expanded: boolean): void;
+}
+declare const createNavigationTree: (options: NavigationTreeOptions) => NavigationTree$1;
+//#endregion
+//#region src/solid/navigation-tree/navigation-tree.d.ts
+interface RootProps$3 extends JSX$1.HTMLAttributes<HTMLElement> {
+  items: NavigationTreeItem[];
+  storageKey?: string;
+  /** Groups up to this depth start expanded. */
+  defaultDepth?: number;
+}
+interface ItemProps extends JSX$1.LiHTMLAttributes<HTMLLIElement> {
+  item: NavigationTreeItem;
+}
+declare const NavigationTree: {
+  Root: ParentComponent<RootProps$3>;
+  List: ParentComponent<JSX$1.HTMLAttributes<HTMLUListElement>>;
+  Item: ParentComponent<ItemProps>;
+  Link: ParentComponent<JSX$1.AnchorHTMLAttributes<HTMLAnchorElement>>;
+  GroupTrigger: ParentComponent<JSX$1.ButtonHTMLAttributes<HTMLButtonElement>>;
+  GroupContent: ParentComponent<JSX$1.HTMLAttributes<HTMLDivElement>>;
+};
+//#endregion
+//#region src/solid/table-of-contents/create-table-of-contents.d.ts
+interface TableOfContentsOptions {
+  headingIDs: Accessor<string[]>;
+}
+interface TableOfContents$1 {
+  activeID: Accessor<string | undefined>;
+  /** Headings whose sections are in the viewport, below the sticky headers. */
+  visibleIDs: Accessor<string[]>;
+  /** Marks a heading as current until the user scrolls, e.g. after a link click. */
+  select(id: string): void;
+}
+declare const createTableOfContents: (options: TableOfContentsOptions) => TableOfContents$1;
+//#endregion
+//#region src/solid/table-of-contents/table-of-contents.d.ts
+interface RootProps$2 extends JSX$1.HTMLAttributes<HTMLElement> {
+  headingIDs: string[];
+}
+interface LinkProps$1 extends Omit<JSX$1.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  headingID: string;
+}
+declare const useTableOfContents: () => TableOfContents$1;
+declare const TableOfContents: {
+  Root: ParentComponent<RootProps$2>;
+  List: ParentComponent<JSX$1.HTMLAttributes<HTMLUListElement>>;
+  Item: ParentComponent<JSX$1.LiHTMLAttributes<HTMLLIElement>>;
+  Link: ParentComponent<LinkProps$1>;
+};
+//#endregion
+//#region src/solid/table-of-contents/create-table-of-contents-guide.d.ts
+interface TableOfContentsGuideOptions {
+  ids: Accessor<string[]>;
+  /** The links to highlight, in outline order. */
+  highlightedIDs: Accessor<string[]>;
+  /** The x position of the guide line for each link. */
+  position(id: string): number;
+  /** Scrolled to keep the highlighted links in view, e.g. the viewport of a long outline. */
+  viewport?: Accessor<HTMLElement | undefined>;
+  /** Space between the guide's ends and each link's top and bottom, in pixels. */
+  inset?: number;
+  /** Corner radius of the backdrop, in pixels. */
+  radius?: number;
+  /** Points on the guide line along the backdrop's left edge. */
+  edgePoints?: number;
+}
+interface TableOfContentsGuide {
+  stroke: Accessor<TableOfContentsGuideStroke | undefined>;
+  trackRef(element: HTMLElement): void;
+  linkRef(id: string, element: HTMLElement): void;
+  pathRef(element: SVGPathElement): void;
+}
+interface TableOfContentsGuideShape {
+  path: string;
+  width: number;
+  /** The highlighted links, relative to the track; undefined when no link is highlighted. */
+  range?: TableOfContentsGuideRange;
+}
+interface TableOfContentsGuideStroke extends TableOfContentsGuideShape {
+  /** Dash offset and length that draw the highlighted part of the path. */
+  offset: number;
+  length: number;
+  total: number;
+  /**
+   * The highlighted area right of the guide line, with rounded corners. It always has the same
+   * commands, so CSS can animate it.
+   */
+  backdrop?: string;
+}
+interface TableOfContentsGuideRange {
+  top: number;
+  height: number;
+}
+/**
+ * Measures one guide path through all table of contents links, with curves between depths, the
+ * dash that highlights a range of links, and a backdrop for that range.
+ */
+declare const createTableOfContentsGuide: (options: TableOfContentsGuideOptions) => TableOfContentsGuide;
+//#endregion
+//#region src/solid/mobile-navigation/enhance-mobile-navigation.d.ts
+interface MobileNavigationOptions {
+  /** The menu works only while this media query matches, e.g. `(max-width: 767.9px)`. */
+  mediaQuery?: string;
+  /** Receives focus after a link to the current page closes the menu. */
+  navigationTarget?: () => HTMLElement | null;
+  onOpenChange?(open: boolean): void;
+}
+/**
+ * Makes a server-rendered `<details>` menu modal: it traps focus, makes the rest of the page
+ * inert, locks scrolling, closes on Escape and on navigation, and restores focus.
+ * Returns a cleanup function.
+ */
+declare const enhanceMobileNavigation: (root: HTMLDetailsElement, options?: MobileNavigationOptions) => (() => void);
+//#endregion
+//#region src/solid/mobile-navigation/mobile-navigation.d.ts
+interface RootProps extends Omit<JSX$1.DetailsHtmlAttributes<HTMLDetailsElement>, "open">, MobileNavigationOptions {}
+declare const MobileNavigation: {
+  Root: ParentComponent<RootProps>;
+  Trigger: ParentComponent<JSX$1.HTMLAttributes<HTMLElement>>;
+  Content: ParentComponent<JSX$1.HTMLAttributes<HTMLDivElement>>;
+};
+//#endregion
+//#region src/solid/breadcrumbs/index.d.ts
+declare const Breadcrumbs: {
+  Root: ParentComponent<JSX$1.HTMLAttributes<HTMLElement>>;
+  List: ParentComponent<JSX$1.OlHTMLAttributes<HTMLOListElement>>;
+  Item: ParentComponent<JSX$1.LiHTMLAttributes<HTMLLIElement>>;
+  Link: ParentComponent<JSX$1.AnchorHTMLAttributes<HTMLAnchorElement>>;
+  Label: ParentComponent<JSX$1.HTMLAttributes<HTMLSpanElement>>;
+  Separator: ParentComponent<JSX$1.HTMLAttributes<HTMLSpanElement>>;
+};
+//#endregion
+//#region src/solid/pagination/index.d.ts
+interface LinkProps extends JSX$1.AnchorHTMLAttributes<HTMLAnchorElement> {
+  direction: "previous" | "next";
+}
+declare const Pagination: {
+  Root: ParentComponent<JSX$1.HTMLAttributes<HTMLElement>>;
+  Link: ParentComponent<LinkProps>;
+};
+//#endregion
+//#region src/solid/tabs/tabs.d.ts
+interface RootProps$1 extends Omit<ComponentProps<typeof Tabs$1.Root>, "value" | "defaultValue"> {
+  values: string[];
+  defaultValue?: string;
+  /**
+   * Tabs with the same key share their selection, in this page and later pages. A group
+   * without the selected value keeps its own selection.
+   */
+  syncKey?: string;
+}
+declare const Tabs: {
+  Root: ParentComponent<RootProps$1>;
+  List: (props: Tabs$1.ListProps) => import("solid-js").JSX.Element;
+  Trigger: (props: Tabs$1.TriggerProps) => import("solid-js").JSX.Element;
+  Content: (props: Tabs$1.ContentProps) => import("solid-js").JSX.Element;
+  Indicator: (props: Tabs$1.IndicatorProps) => import("solid-js").JSX.Element;
+};
+//#endregion
+//#region src/solid/clipboard/index.d.ts
+interface Clipboard {
+  /** `true` after a copy, `false` after a failure, and `undefined` otherwise. */
+  status: Accessor<boolean | undefined>;
+  /** Copies text; pending text is still written during the click, e.g. text to fetch. */
+  copy(text: string | Promise<string>): Promise<void>;
+}
+/** Copies text, and reports the result for a short time. */
+declare const createClipboard: (timeout?: number) => Clipboard;
+//#endregion
+//#region src/solid/search/create-search.d.ts
+interface SearchOptions<T> {
+  search(query: string, signal: AbortSignal): Promise<T>;
+  /** Wait after the last input change, in milliseconds. */
+  delay?: number;
+}
+interface Search<T> {
+  query: Accessor<string>;
+  results: Accessor<T | undefined>;
+  status: Accessor<SearchStatus>;
+  error: Accessor<unknown>;
+  setQuery(query: string): void;
+  /** Stops the pending search; the last results stay. */
+  cancel(): void;
+}
+type SearchStatus = "idle" | "loading" | "done" | "error";
+/**
+ * Runs a search after input stops. A new query cancels the previous request, and only the
+ * latest response updates the results.
+ */
+declare const createSearch: <T>(options: SearchOptions<T>) => Search<T>;
+//#endregion
+//#region src/solid/search/create-list-navigation.d.ts
+interface ListNavigationOptions {
+  count: Accessor<number>;
+  /** Called on Enter with the active index. */
+  onSelect(index: number): void;
+}
+interface ListNavigation {
+  active: Accessor<number>;
+  setActive(index: number): void;
+  /** Handles arrow, Home, End, and Enter keys, e.g. on a combobox input. */
+  onKeyDown(event: KeyboardEvent): void;
+}
+/** Keyboard navigation for a list whose focus stays on another element. */
+declare const createListNavigation: (options: ListNavigationOptions) => ListNavigation;
+//#endregion
+//#region src/solid/search/create-answer.d.ts
+interface AnswerTurn<T> {
+  question: string;
+  answer?: T;
+  status: AnswerStatus;
+  error?: unknown;
+}
+interface AnswerOptions<T> {
+  /**
+   * Gets the answer to a question. `turns` has the completed earlier turns, for follow-up
+   * history. Call `update` with each partial answer.
+   */
+  ask(question: string, turns: Array<AnswerTurn<T>>, signal: AbortSignal, update: (answer: T) => void): Promise<T>;
+}
+interface Answer<T> {
+  /** The conversation, oldest first. */
+  turns: Accessor<Array<AnswerTurn<T>>>;
+  pending: Accessor<boolean>;
+  /** Asks a question; earlier completed turns are the history. */
+  ask(question: string): void;
+  /** Stops the pending answer and removes its turn. */
+  cancel(): void;
+  /** Stops the pending answer and clears the conversation. */
+  reset(): void;
+}
+type AnswerStatus = "loading" | "done" | "error";
+/** A conversation of streamed answers, with cancellation and follow-up questions. */
+declare const createAnswer: <T>(options: AnswerOptions<T>) => Answer<T>;
+//#endregion
+//#region src/solid/search/create-search-palette.d.ts
+interface SearchPaletteItem {
+  href: string;
+}
+interface SearchPaletteOptions<TResults, TItem extends SearchPaletteItem, TAnswer> {
+  search(query: string, signal: AbortSignal): Promise<TResults>;
+  /** The results' items that open with Enter, in order. */
+  items(results: TResults): TItem[];
+  /** Answers the query as a question. Without it, the palette only searches. */
+  ask?: AnswerOptions<TAnswer>["ask"];
+  /** Wait after the last input change, in milliseconds. */
+  delay?: number;
+  /** Elements that open the palette on click. */
+  triggerSelector?: string;
+  /** URL parameter that opens the palette with a query, e.g. `?q=install`. */
+  queryParam?: string;
+  /** Maximum length of a query from the URL. */
+  maxLength?: number;
+}
+interface SearchPalette<TResults, TItem extends SearchPaletteItem, TAnswer> {
+  open: Accessor<boolean>;
+  setOpen(open: boolean): void;
+  search: Search<TResults>;
+  /** Undefined without the `ask` option. */
+  answer?: Answer<TAnswer>;
+  items: Accessor<TItem[]>;
+  /** The query can be asked as a question; the ask row is the list item after the items. */
+  canAsk: Accessor<boolean>;
+  /** The conversation shows in place of results: the input is empty and there are answers. */
+  showingAnswer: Accessor<boolean>;
+  navigation: ListNavigation;
+  /** Shortcuts use Command, not Ctrl. */
+  isApple: Accessor<boolean>;
+  /** Asks the query as a question, and clears the input. */
+  askQuery(): void;
+  /** Goes to an item's page. */
+  openItem(item: TItem): void;
+  onInputKeyDown(event: KeyboardEvent): void;
+  input: Accessor<HTMLInputElement | undefined>;
+  inputRef(element: HTMLInputElement): void;
+  /**
+   * The scrolling element of the results. The active result, marked with a
+   * `data-search-result` attribute that holds its index, and new answer text stay in view.
+   */
+  resultsRef(element: HTMLElement): void;
+}
+/**
+ * The state of a search dialog: search as you type, AI answers with follow-ups, keyboard
+ * navigation, the ⌘K or Ctrl+K shortcut, trigger elements, and a query in the URL.
+ */
+declare const createSearchPalette: <TResults, TItem extends SearchPaletteItem, TAnswer = never>(options: SearchPaletteOptions<TResults, TItem, TAnswer>) => SearchPalette<TResults, TItem, TAnswer>;
+//#endregion
+//#region src/solid/search/highlight.d.ts
+interface MatchPart {
+  text: string;
+  /** The part matches the query. */
+  match: boolean;
+}
+interface MatchPreviewOptions {
+  /** Maximum length of the preview, in characters. */
+  length?: number;
+  /** Characters to keep before the first match. */
+  prefix?: number;
+}
+/** The whole query and its words of two or more characters, longest first. */
+declare const getMatchTerms: (query: string) => string[];
+declare const matchesQuery: (text: string, query: string) => boolean;
+/** Splits text into parts that match the query and parts that do not, for highlighting. */
+declare const splitMatches: (text: string, query: string) => MatchPart[];
+/** Cuts the text to start just before the first match of the query. */
+declare const getMatchPreview: (text: string, query: string, options?: MatchPreviewOptions) => string;
+//#endregion
+//#region src/solid/page-actions/create-page-actions.d.ts
+interface PageActionsOptions {
+  /** URL of the page's Markdown alternative. */
+  markdown: string;
+  /** Time that a copy result shows, in milliseconds. */
+  timeout?: number;
+}
+interface PageActions {
+  /** The last copy result, for a short time. */
+  result: Accessor<CopyResult | undefined>;
+  copyLink(): Promise<void>;
+  copyMarkdown(): Promise<void>;
+}
+interface CopyResult {
+  item: "link" | "markdown";
+  success: boolean;
+}
+/** Copies the page URL or its Markdown alternative. */
+declare const createPageActions: (options: PageActionsOptions) => PageActions;
+//#endregion
+//#region src/solid/scroll/create-scroll-memory.d.ts
+interface ScrollMemoryOptions {
+  container: () => HTMLElement | undefined;
+  /** Session storage key of the scroll position. */
+  key: string;
+  /** Kept in view after the position is restored. */
+  current?: () => Element | null | undefined;
+}
+/** Keeps the scroll position of a container between pages, and shows the current item. */
+declare const createScrollMemory: (options: ScrollMemoryOptions) => void;
+//#endregion
+//#region src/solid/scroll/create-scroll-edges.d.ts
+interface ScrollEdges {
+  /** The page is scrolled away from its top. */
+  start: Accessor<boolean>;
+  /** More of the page is below the viewport. */
+  end: Accessor<boolean>;
+}
+/** Tracks whether the page has content past the top and bottom of the viewport, e.g. for fades. */
+declare const createScrollEdges: () => ScrollEdges;
+//#endregion
+//#region src/solid/scroll/create-page-scrollbar.d.ts
+interface PageScrollbarOptions {
+  /** Space between the track ends and the viewport edges, in pixels. */
+  inset?: number;
+  /** Width of the zone at the right edge where the pointer shows the scrollbar, in pixels. */
+  edgeZone?: number;
+  minThumbHeight?: number;
+  /** Time that the scrollbar stays after scrolling stops, in milliseconds. */
+  hideDelay?: number;
+}
+interface PageScrollbar {
+  /** The thumb position; undefined when the page does not scroll, or scrolling is locked. */
+  thumb: Accessor<PageScrollbarThumb | undefined>;
+  /** The page scrolls, or the pointer is near the scrollbar or drags it. */
+  visible: Accessor<boolean>;
+  /** The pointer is near the scrollbar or drags it, so the scrollbar takes pointer input. */
+  interactive: Accessor<boolean>;
+  /** Scrolls the page to a click on the track. */
+  onTrackPointerDown(event: PointerEvent): void;
+  thumbHandlers: PageScrollbarThumbHandlers;
+}
+interface PageScrollbarThumb {
+  top: number;
+  height: number;
+}
+interface PageScrollbarThumbHandlers {
+  onPointerDown(event: PointerEvent): void;
+  onPointerMove(event: PointerEvent): void;
+  onPointerUp(): void;
+  onPointerCancel(): void;
+  onLostPointerCapture(): void;
+}
+/**
+ * An overlay scrollbar for the page, for layouts that hide the native one so pages with and
+ * without overflow have the same width. It shows while the page scrolls, or when the pointer is
+ * near the right edge, and supports dragging and track clicks.
+ */
+declare const createPageScrollbar: (options?: PageScrollbarOptions) => PageScrollbar;
+//#endregion
+//#region src/solid/tab-indicator/create-tab-indicator.d.ts
+interface TabIndicatorOptions {
+  /** Index of the current tab, or -1. */
+  current: Accessor<number>;
+}
+interface TabIndicator {
+  position: Accessor<TabIndicatorPosition | undefined>;
+  /** The positioned wrapper of the indicator; it does not scroll. */
+  rootRef(element: HTMLElement): void;
+  scrollRef(element: HTMLElement): void;
+  tabRef(index: number, element: HTMLElement): void;
+}
+interface TabIndicatorPosition {
+  left: number;
+  width: number;
+}
+/** Measures an underline for the current tab of a scrollable row, and keeps that tab in view. */
+declare const createTabIndicator: (options: TabIndicatorOptions) => TabIndicator;
+//#endregion
+export { type Answer, type AnswerOptions, type AnswerStatus, type AnswerTurn, Breadcrumbs, type Clipboard, type CopyResult, type ListNavigation, type ListNavigationOptions, type MatchPart, type MatchPreviewOptions, MobileNavigation, type MobileNavigationOptions, type RootProps as MobileNavigationRootProps, NavigationTree, type NavigationTreeItem, type NavigationTreeOptions, type NavigationTree$1 as NavigationTreeState, type PageActions, type PageActionsOptions, type PageScrollbar, type PageScrollbarOptions, type PageScrollbarThumb, type PageScrollbarThumbHandlers, Pagination, type ScrollEdges, type ScrollMemoryOptions, type Search, type SearchOptions, type SearchPalette, type SearchPaletteItem, type SearchPaletteOptions, type SearchStatus, type TabIndicator, type TabIndicatorOptions, type TabIndicatorPosition, TableOfContents, type TableOfContentsGuide, type TableOfContentsGuideOptions, type TableOfContentsGuideRange, type TableOfContentsGuideStroke, type TableOfContentsOptions, type TableOfContents$1 as TableOfContentsState, Tabs, type RootProps$1 as TabsRootProps, createAnswer, createClipboard, createListNavigation, createNavigationTree, createPageActions, createPageScrollbar, createScrollEdges, createScrollMemory, createSearch, createSearchPalette, createTabIndicator, createTableOfContents, createTableOfContentsGuide, enhanceMobileNavigation, getMatchPreview, getMatchTerms, matchesQuery, splitMatches, useTableOfContents };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@andesine/ui",
+  "version": "0.4.0",
+  "description": "Headless documentation components for Andesine Pages",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./solid": {
+      "types": "./dist/solid/types/index.d.ts",
+      "solid": "./dist/solid/source/index.jsx",
+      "browser": "./dist/solid/client/index.js",
+      "node": "./dist/solid/server/index.js",
+      "default": "./dist/solid/server/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.14"
+  },
+  "devDependencies": {
+    "@babel/core": "7.29.7",
+    "babel-preset-solid": "1.9.12",
+    "publint": "0.3.24",
+    "rolldown": "^1.2.2",
+    "rolldown-plugin-dts": "^0.28.6",
+    "solid-js": "1.9.14",
+    "typescript": "6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vriteio/andesine.git",
+    "directory": "packages/public/ui"
+  },
+  "homepage": "https://github.com/vriteio/andesine/tree/andesine/packages/public/ui#readme",
+  "bugs": {
+    "url": "https://github.com/vriteio/andesine/issues"
+  },
+  "keywords": [
+    "andesine",
+    "documentation",
+    "headless",
+    "solid"
+  ],
+  "dependencies": {
+    "@ark-ui/solid": "5.38.0"
+  },
+  "scripts": {
+    "build": "rolldown -c rolldown.config.ts",
+    "typecheck": "tsc --noEmit",
+    "lint:package": "publint --strict"
+  }
+}