@askrjs/themes 0.0.24 → 0.0.27

package/src/components/command-palette/command-palette.tsx

@@ -39,6 +39,11 @@ function readCommandPaletteContext(): CommandPaletteContextValue {
   return context;
 }
 
+/**
+ * Root dialog wrapper for a searchable command palette. Manages open state
+ * (controlled or uncontrolled), tracks the triggering element, and restores
+ * focus to it after the palette closes.
+ */
 export function CommandPalette(props: CommandPaletteProps): JSX.Element {
   const { children, defaultOpen = false, onOpenChange, open, ...rest } = props;
   const openState = controllableState({
@@ -96,6 +101,7 @@ export function CommandPalette(props: CommandPaletteProps): JSX.Element {
   );
 }
 
+/** Trigger that opens the {@link CommandPalette}, registering itself so focus returns here on close. */
 export function CommandPaletteTrigger(props: CommandPaletteTriggerProps): JSX.Element;
 export function CommandPaletteTrigger(props: CommandPaletteTriggerAsChildProps): JSX.Element;
 export function CommandPaletteTrigger(
@@ -119,6 +125,12 @@ function preventDismiss(event: Event, shouldDismiss: boolean): void {
   }
 }
 
+/**
+ * Dialog content for a {@link CommandPalette}: renders the overlay, an
+ * accessible (visually hidden) title/description, and a `Command` list,
+ * moving initial focus to `initialFocus` (defaults to the search input) once
+ * mounted, and optionally suppressing dismiss-on-escape/backdrop.
+ */
 export function CommandPaletteContent(props: CommandPaletteContentProps): JSX.Element {
   const palette = readCommandPaletteContext();
   const {
@@ -208,6 +220,7 @@ function composeBeforeNavigate(
   };
 }
 
+/** A navigable result row that closes the palette on selection (unless `closeOnSelect` is `false`) and supports cancelling navigation via `onBeforeNavigate`. */
 export function CommandPaletteLink(props: CommandPaletteLinkProps): JSX.Element {
   const {
     children,
@@ -232,6 +245,7 @@ export function CommandPaletteLink(props: CommandPaletteLinkProps): JSX.Element
   );
 }
 
+/** Renders the `<ul>` list wrapper for {@link CommandPalette} results. */
 export function CommandPaletteList(props: CommandPaletteListProps): JSX.Element {
   const { children, class: className, ...rest } = props;
   return (

package/src/components/command-palette/command-palette.types.ts

@@ -9,10 +9,14 @@ import type {
   DialogTriggerProps,
 } from "@askrjs/ui";
 
+/** Props for the {@link CommandPalette} component. */
 export type CommandPaletteProps = DialogProps;
+/** Props for the {@link CommandPaletteTrigger} component. */
 export type CommandPaletteTriggerProps = DialogTriggerProps;
+/** Props for {@link CommandPaletteTrigger} rendered with `asChild`. */
 export type CommandPaletteTriggerAsChildProps = DialogTriggerAsChildProps;
 
+/** Props for the {@link CommandPaletteContent} component. */
 export type CommandPaletteContentProps = Omit<
   DialogContentProps,
   "children" | "title" | "onEscapeKeyDown" | "onInteractOutside" | "onPointerDownOutside"
@@ -29,11 +33,13 @@ export type CommandPaletteContentProps = Omit<
   onPointerDownOutside?: (event: PointerEvent) => void;
 };
 
+/** Props for the {@link CommandPaletteLink} component. */
 export type CommandPaletteLinkProps = LinkProps & {
   closeOnSelect?: boolean;
   onBeforeNavigate?: () => void;
 };
 
+/** Props for the {@link CommandPaletteList} component. */
 export type CommandPaletteListProps = Omit<JSX.IntrinsicElements["ul"], "children" | "ref"> & {
   children?: unknown;
   ref?: Ref<HTMLUListElement>;

package/src/components/container/container.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { Block } from "../block";
 import type { ContainerProps } from "./container.types";
 
+/** Centers content in a max-width column with page gutters (defaults to the `"page"` {@link BlockSize}). */
 export function Container(props: ContainerProps): JSX.Element {
   const { children, size = "page", ...rest } = props;
 

package/src/components/container/container.types.ts

@@ -1,5 +1,6 @@
 import type { BlockDivProps, BlockSize } from "../block";
 
+/** Props for the {@link Container} component. */
 export type ContainerProps = Omit<BlockDivProps, "maxWidth"> & {
   size?: BlockSize;
 };

package/src/components/empty-state/empty-state.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { Block } from "../block";
 import type { EmptyStateProps } from "./empty-state.types";
 
+/** Centered placeholder for empty lists/views: an icon, title (default `<h2>`), description, extra content, and an action row. */
 export function EmptyState(props: EmptyStateProps): JSX.Element {
   const { icon, title, titleAs: TitleTag = "h2", description, action, children, ...rest } = props;
 

package/src/components/empty-state/empty-state.types.ts

@@ -1,7 +1,9 @@
 import type { BlockDivProps } from "../block";
 
+/** Heading tag allowed for an empty state's title via `titleAs`. */
 export type EmptyStateHeadingTag = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
 
+/** Props for the {@link EmptyState} component. */
 export type EmptyStateProps = BlockDivProps & {
   icon?: unknown;
   title?: unknown;

package/src/components/field/field.tsx

@@ -3,6 +3,7 @@ import { classes } from "../_internal/classes";
 import { mergeProps } from "../_internal/merge-props";
 import type { FieldErrorProps, FieldHintProps, FieldProps } from "./field.types";
 
+/** Groups a form control with its hint/error text, marking `data-invalid` when `invalid` is set. */
 export function Field(props: FieldProps): JSX.Element {
   const { children, class: className, invalid = false, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -15,6 +16,7 @@ export function Field(props: FieldProps): JSX.Element {
   return <div {...finalProps}>{children}</div>;
 }
 
+/** Renders supporting hint text for a {@link Field}. */
 export function FieldHint(props: FieldHintProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -26,6 +28,7 @@ export function FieldHint(props: FieldHintProps): JSX.Element {
   return <p {...finalProps}>{children}</p>;
 }
 
+/** Renders validation error text for a {@link Field}, exposed with `role="alert"`. */
 export function FieldError(props: FieldErrorProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {

package/src/components/field/field.types.ts

@@ -4,17 +4,20 @@ import type { Ref } from "@askrjs/askr/foundations/utilities";
 type DivProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref">;
 type ParagraphProps = Omit<JSX.IntrinsicElements["p"], "children" | "ref">;
 
+/** Props for the {@link Field} component. */
 export type FieldProps = DivProps & {
   children?: unknown;
   invalid?: boolean;
   ref?: Ref<HTMLDivElement>;
 };
 
+/** Props for the {@link FieldHint} component. */
 export type FieldHintProps = ParagraphProps & {
   children?: unknown;
   ref?: Ref<HTMLParagraphElement>;
 };
 
+/** Props for the {@link FieldError} component. */
 export type FieldErrorProps = ParagraphProps & {
   children?: unknown;
   ref?: Ref<HTMLParagraphElement>;

package/src/components/footer/footer.tsx

@@ -12,6 +12,7 @@ import type {
   FooterTitleProps,
 } from "./footer.types";
 
+/** Renders a `<footer>`-element {@link Block} with a muted background and top border. */
 export function Footer(props: FooterProps): JSX.Element {
   const { children, ...rest } = props;
 
@@ -22,6 +23,7 @@ export function Footer(props: FooterProps): JSX.Element {
   );
 }
 
+/** Renders the main content wrapper of a {@link Footer}. */
 export function FooterContent(props: FooterContentProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -33,6 +35,7 @@ export function FooterContent(props: FooterContentProps): JSX.Element {
   return <div {...finalProps}>{children}</div>;
 }
 
+/** Renders a grouped section within a {@link Footer}. */
 export function FooterSection(props: FooterSectionProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -44,6 +47,7 @@ export function FooterSection(props: FooterSectionProps): JSX.Element {
   return <div {...finalProps}>{children}</div>;
 }
 
+/** Renders a section title (`<h2>`) within a {@link Footer}. */
 export function FooterTitle(props: FooterTitleProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -55,6 +59,7 @@ export function FooterTitle(props: FooterTitleProps): JSX.Element {
   return <h2 {...finalProps}>{children}</h2>;
 }
 
+/** Renders supporting description text within a {@link Footer}. */
 export function FooterDescription(props: FooterDescriptionProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -66,6 +71,7 @@ export function FooterDescription(props: FooterDescriptionProps): JSX.Element {
   return <p {...finalProps}>{children}</p>;
 }
 
+/** Renders a `<nav>` wrapper for a group of {@link FooterLink}s. */
 export function FooterLinks(props: FooterLinksProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -77,6 +83,7 @@ export function FooterLinks(props: FooterLinksProps): JSX.Element {
   return <nav {...finalProps}>{children}</nav>;
 }
 
+/** Renders a single link within a {@link Footer}. */
 export function FooterLink(props: FooterLinkProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {

package/src/components/footer/footer.types.ts

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { BlockElementProps } from "../block";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Props for the {@link Footer} component. */
 export type FooterProps = Omit<BlockElementProps<"footer">, "as">;
 
 type DivProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref">;
@@ -10,31 +11,37 @@ type ParagraphProps = Omit<JSX.IntrinsicElements["p"], "children" | "ref">;
 type NavProps = Omit<JSX.IntrinsicElements["nav"], "children" | "ref">;
 type AnchorProps = Omit<JSX.IntrinsicElements["a"], "children" | "ref">;
 
+/** Props for the {@link FooterContent} component. */
 export type FooterContentProps = DivProps & {
   children?: unknown;
   ref?: Ref<HTMLDivElement>;
 };
 
+/** Props for the {@link FooterSection} component. */
 export type FooterSectionProps = DivProps & {
   children?: unknown;
   ref?: Ref<HTMLDivElement>;
 };
 
+/** Props for the {@link FooterTitle} component. */
 export type FooterTitleProps = HeadingProps & {
   children?: unknown;
   ref?: Ref<HTMLHeadingElement>;
 };
 
+/** Props for the {@link FooterDescription} component. */
 export type FooterDescriptionProps = ParagraphProps & {
   children?: unknown;
   ref?: Ref<HTMLParagraphElement>;
 };
 
+/** Props for the {@link FooterLinks} component. */
 export type FooterLinksProps = NavProps & {
   children?: unknown;
   ref?: Ref<HTMLElement>;
 };
 
+/** Props for the {@link FooterLink} component. */
 export type FooterLinkProps = AnchorProps & {
   children?: unknown;
   ref?: Ref<HTMLAnchorElement>;

package/src/components/grid/grid.tsx

@@ -27,6 +27,7 @@ function resolveAlign(value: GridAlign): string {
   return value;
 }
 
+/** CSS grid layout primitive: turns `columns`/`gap`/`align` (each optionally responsive) into generated grid-template styles, rendering as `<div>` by default. */
 export function Grid<TElement extends GridElement = "div">(
   props: GridProps<TElement>,
 ): JSX.Element {

package/src/components/grid/grid.types.ts

@@ -2,8 +2,11 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 import type { BlockSpace, ResponsiveValue } from "../_internal/block-layout";
 
+/** Element tags {@link Grid} can render as via its `as` prop. */
 export type GridElement = "div" | "section" | "ul";
+/** Column definition for {@link Grid}: a track count or a raw `grid-template-columns` string. */
 export type GridColumns = number | string;
+/** `align-items` value applied to a {@link Grid}. */
 export type GridAlign = "start" | "center" | "end" | "stretch";
 
 type GridIntrinsicProps<TElement extends GridElement> = Omit<
@@ -11,6 +14,7 @@ type GridIntrinsicProps<TElement extends GridElement> = Omit<
   "children" | "ref"
 >;
 
+/** Props for the {@link Grid} component, specialized for a given {@link GridElement} `TElement`. */
 export type GridProps<TElement extends GridElement = "div"> = GridIntrinsicProps<TElement> & {
   as?: TElement;
   columns?: ResponsiveValue<GridColumns>;

package/src/components/header/header.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { Block } from "../block";
 import type { HeaderProps } from "./header.types";
 
+/** Renders a `<header>`-element {@link Block} with a surface background and bottom border, optionally sticky-positioned via `position`/`sticky`. */
 export function Header(props: HeaderProps): JSX.Element {
   const { children, position, sticky = position === "sticky", ...rest } = props;
 

package/src/components/header/header.types.ts

@@ -1,5 +1,6 @@
 import type { BlockElementProps } from "../block";
 
+/** Props for the {@link Header} component. */
 export type HeaderProps = Omit<BlockElementProps<"header">, "as" | "sticky"> & {
   position?: "sticky" | "static";
   sticky?: boolean;

package/src/components/input-group/input-group.tsx

@@ -9,6 +9,7 @@ import type {
   InputGroupTextProps,
 } from "./input-group.types";
 
+/** Groups related inputs/addons together, optionally visually attached, with a horizontal or vertical orientation and `role="group"` by default. */
 export function InputGroup(props: InputGroupProps): JSX.Element {
   const {
     attached = true,
@@ -39,6 +40,7 @@ export function InputGroup(props: InputGroupProps): JSX.Element {
   );
 }
 
+/** Renders static text/label content within an {@link InputGroup}. */
 export function InputGroupText(props: InputGroupTextProps): JSX.Element;
 export function InputGroupText(props: InputGroupTextAsChildProps): JSX.Element;
 export function InputGroupText(

package/src/components/input-group/input-group.types.ts

@@ -2,11 +2,13 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { JSXElement } from "@askrjs/askr/foundations";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Layout direction of an {@link InputGroup}. */
 export type InputGroupOrientation = "horizontal" | "vertical";
 
 type DivProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref">;
 type SpanProps = Omit<JSX.IntrinsicElements["span"], "children" | "ref">;
 
+/** Props for the {@link InputGroup} component. */
 export type InputGroupProps = DivProps & {
   children?: unknown;
   attached?: boolean;
@@ -14,12 +16,14 @@ export type InputGroupProps = DivProps & {
   ref?: Ref<HTMLDivElement>;
 };
 
+/** Props for {@link InputGroupText} rendered as its default `<span>` element. */
 export type InputGroupTextProps = SpanProps & {
   asChild?: false;
   children?: unknown;
   ref?: Ref<HTMLSpanElement>;
 };
 
+/** Props for {@link InputGroupText} rendered with `asChild`, merging its attributes onto a single child element. */
 export type InputGroupTextAsChildProps = SpanProps & {
   asChild: true;
   children: JSXElement;

package/src/components/main/main.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { Block } from "../block";
 import type { MainProps } from "./main.types";
 
+/** Renders a `<main>`-element {@link Block} that grows to fill available space. */
 export function Main(props: MainProps): JSX.Element {
   const { children, ...rest } = props;
 

package/src/components/main/main.types.ts

@@ -1,3 +1,4 @@
 import type { BlockElementProps } from "../block";
 
+/** Props for the {@link Main} component. */
 export type MainProps = Omit<BlockElementProps<"main">, "as">;

package/src/components/nav/nav.tsx

@@ -1,6 +1,6 @@
 import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { Slot } from "@askrjs/askr/foundations";
-import { currentRoute, Link, navigate } from "@askrjs/askr/router";
+import { currentRoute, Link } from "@askrjs/askr/router";
 import { Block } from "../block";
 import { classes } from "../_internal/classes";
 import { mergeProps } from "../_internal/merge-props";
@@ -56,25 +56,6 @@ function isActiveNavLink(
   return currentPathname === targetPathname || currentPathname.startsWith(`${targetPathname}/`);
 }
 
-function shouldHandleClientNavigation(
-  event: MouseEvent,
-  target: string | undefined,
-  targetPathname: string | null,
-): boolean {
-  if (targetPathname === null || target) {
-    return false;
-  }
-
-  return (
-    !event.defaultPrevented &&
-    (event.button ?? 0) === 0 &&
-    !event.altKey &&
-    !event.ctrlKey &&
-    !event.metaKey &&
-    !event.shiftKey
-  );
-}
-
 function renderNavSet(
   props: TabsProps | TabsAsChildProps | PillsProps | PillsAsChildProps,
   slot: "tabs" | "pills",
@@ -145,27 +126,14 @@ function renderRoutedLink(
     : {
         "data-active": undefined,
       };
-  const rendersRouterLink =
-    targetPathname !== null &&
-    !target &&
-    !hasDownload &&
-    typeof onClick !== "function" &&
-    typeof onPress !== "function";
+  const rendersRouterLink = targetPathname !== null && !target && !hasDownload;
   const childProps: NavLinkProps = to
-    ? ({ ...childRest, to, target } as NavLinkProps)
-    : ({ ...childRest, href, target } as NavLinkProps);
+    ? ({ ...childRest, to, target, onPress, onClick } as NavLinkProps)
+    : ({ ...childRest, href, target, onPress, onClick } as NavLinkProps);
   const handleClick = (event: MouseEvent) => {
     onPress?.(event);
     if (event.defaultPrevented) return;
     onClick?.(event);
-    if (hasDownload) return;
-
-    if (!shouldHandleClientNavigation(event, target, targetPathname)) {
-      return;
-    }
-
-    event.preventDefault();
-    navigate(href);
   };
 
   return (
@@ -191,26 +159,31 @@ function renderRoutedLink(
   );
 }
 
+/** Renders a `<nav>` wrapper (or, with `asChild`, merges onto a child) for a set of {@link Tab} links. */
 export function Tabs(props: TabsProps): JSX.Element;
 export function Tabs(props: TabsAsChildProps): JSX.Element;
 export function Tabs(props: TabsProps | TabsAsChildProps): JSX.Element {
   return renderNavSet(props, "tabs");
 }
 
+/** Renders a `<nav>` wrapper (or, with `asChild`, merges onto a child) for a set of {@link Pill} links. */
 export function Pills(props: PillsProps): JSX.Element;
 export function Pills(props: PillsAsChildProps): JSX.Element;
 export function Pills(props: PillsProps | PillsAsChildProps): JSX.Element {
   return renderNavSet(props, "pills");
 }
 
+/** A router-aware link styled as a tab, auto-marked active by matching the current route (see {@link NavLinkProps.match}). */
 export function Tab(props: TabProps): JSX.Element {
   return renderRoutedLink(props, "tab", { className: "tab" });
 }
 
+/** A router-aware link styled as a pill, auto-marked active by matching the current route, with an active background highlight. */
 export function Pill(props: PillProps): JSX.Element {
   return renderRoutedLink(props, "pill", { activeBackground: true, className: "pill" });
 }
 
+/** A generic navigation item, rendered as an `<a>` (or, with `asChild`, merged onto a child), highlighted when `active`. */
 export function NavItem(props: NavItemProps): JSX.Element;
 export function NavItem(props: NavItemAsChildProps): JSX.Element;
 export function NavItem(props: NavItemProps | NavItemAsChildProps): JSX.Element {
@@ -262,6 +235,7 @@ export function NavItem(props: NavItemProps | NavItemAsChildProps): JSX.Element
   );
 }
 
+/** A router-aware navigation link that highlights itself when its route matches the current location. */
 export function NavLink(props: NavLinkProps): JSX.Element {
   return renderRoutedLink(props, "nav-item", { activeBackground: true, inheritSlot: true });
 }

package/src/components/nav/nav.types.ts

@@ -3,18 +3,22 @@ import type { JSXElement } from "@askrjs/askr/foundations";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 import type { LinkProps } from "@askrjs/askr/router";
 
+/** Route-matching strategy for {@link NavLinkProps.match}: `"prefix"` matches sub-routes, `"exact"` requires an identical path. */
 export type NavLinkMatch = "prefix" | "exact";
 
+/** Props shared by both {@link Tabs} call signatures. */
 export type TabsOwnProps = {
   children?: unknown;
 };
 
+/** Props for {@link Tabs} rendered as its default `<nav>` element. */
 export type TabsProps = Omit<JSX.IntrinsicElements["nav"], "children" | "ref"> &
   TabsOwnProps & {
     asChild?: false;
     ref?: Ref<HTMLElement>;
   };
 
+/** Props for {@link Tabs} rendered with `asChild`, merging onto a single child element. */
 export type TabsAsChildProps = Omit<JSX.IntrinsicElements["nav"], "children" | "ref"> &
   TabsOwnProps & {
     asChild: true;
@@ -22,16 +26,19 @@ export type TabsAsChildProps = Omit<JSX.IntrinsicElements["nav"], "children" | "
     ref?: Ref<unknown>;
   };
 
+/** Props shared by both {@link Pills} call signatures. */
 export type PillsOwnProps = {
   children?: unknown;
 };
 
+/** Props for {@link Pills} rendered as its default `<nav>` element. */
 export type PillsProps = Omit<JSX.IntrinsicElements["nav"], "children" | "ref"> &
   PillsOwnProps & {
     asChild?: false;
     ref?: Ref<HTMLElement>;
   };
 
+/** Props for {@link Pills} rendered with `asChild`, merging onto a single child element. */
 export type PillsAsChildProps = Omit<JSX.IntrinsicElements["nav"], "children" | "ref"> &
   PillsOwnProps & {
     asChild: true;
@@ -39,17 +46,20 @@ export type PillsAsChildProps = Omit<JSX.IntrinsicElements["nav"], "children" |
     ref?: Ref<unknown>;
   };
 
+/** Props shared by both {@link NavItem} call signatures. */
 export type NavItemOwnProps = {
   active?: boolean;
   children?: unknown;
 };
 
+/** Props for {@link NavItem} rendered as its default `<a>` element. */
 export type NavItemProps = Omit<JSX.IntrinsicElements["a"], "children" | "ref"> &
   NavItemOwnProps & {
     asChild?: false;
     ref?: Ref<HTMLAnchorElement>;
   };
 
+/** Props for {@link NavItem} rendered with `asChild`, merging onto a single child element. */
 export type NavItemAsChildProps = Omit<JSX.IntrinsicElements["a"], "children" | "ref"> &
   NavItemOwnProps & {
     asChild: true;
@@ -57,13 +67,17 @@ export type NavItemAsChildProps = Omit<JSX.IntrinsicElements["a"], "children" |
     ref?: Ref<unknown>;
   };
 
+/** Props shared by {@link NavLink}, {@link Tab}, and {@link Pill}. */
 export type NavLinkOwnProps = NavItemOwnProps & {
   match?: NavLinkMatch;
   onPress?: (event: Event) => void;
 };
 
+/** Props for the {@link NavLink} component. */
 export type NavLinkProps = LinkProps & NavLinkOwnProps;
 
+/** Props for the {@link Tab} component. */
 export type TabProps = LinkProps & NavLinkOwnProps;
 
+/** Props for the {@link Pill} component. */
 export type PillProps = LinkProps & NavLinkOwnProps;

package/src/components/navbar/navbar.tsx

@@ -41,6 +41,11 @@ function hasRenderableChildren(children: readonly unknown[]): boolean {
   });
 }
 
+/**
+ * Horizontal navigation bar. Below `collapseAt`/`breakpoint`, non-brand
+ * children are grouped behind a collapsible toggle so brand content stays
+ * visible while the rest collapses on small screens.
+ */
 export function Navbar(props: NavbarProps): JSX.Element {
   const {
     breakpoint,
@@ -106,6 +111,7 @@ export function Navbar(props: NavbarProps): JSX.Element {
   );
 }
 
+/** Renders the brand/logo slot of a {@link Navbar}; excluded from the collapsible section. */
 export function NavBrand(props: NavBrandProps): JSX.Element {
   const { children, ...rest } = props;
 
@@ -123,6 +129,7 @@ export function NavBrand(props: NavBrandProps): JSX.Element {
   );
 }
 
+/** Groups related {@link Navbar} items under an optional label. */
 export function NavGroup(props: NavGroupProps): JSX.Element {
   const { align, children, label, title = label, ...rest } = props;
 
@@ -136,6 +143,7 @@ export function NavGroup(props: NavGroupProps): JSX.Element {
   );
 }
 
+/** Renders a dropdown menu triggered from within a {@link Navbar}. */
 export function NavDropdown(props: NavDropdownProps): JSX.Element {
   const { align = "end", children, label, side = "bottom", sideOffset = 6, ...rest } = props;
 

package/src/components/navbar/navbar.types.ts

@@ -1,8 +1,10 @@
 import type { BlockAsChildProps, BlockDivProps, BlockElementProps } from "../block";
 import type { DropdownContentOwnProps, DropdownProps } from "@askrjs/ui";
 
+/** Breakpoint at which a {@link Navbar} collapses non-brand content behind a toggle. */
 export type NavbarCollapseBreakpoint = "sm" | "md" | "lg" | "xl";
 
+/** Props for the {@link Navbar} component. */
 export type NavbarProps = Omit<BlockElementProps<"nav">, "as" | "direction" | "align"> & {
   breakpoint?: NavbarCollapseBreakpoint | false;
   collapseAt?: NavbarCollapseBreakpoint | false;
@@ -10,13 +12,16 @@ export type NavbarProps = Omit<BlockElementProps<"nav">, "as" | "direction" | "a
   collapseIcon?: unknown;
 };
 
+/** Props for the {@link NavBrand} component. */
 export type NavBrandProps = BlockDivProps | BlockElementProps<"a"> | BlockAsChildProps;
 
+/** Props for the {@link NavGroup} component. */
 export type NavGroupProps = Omit<BlockDivProps, "title"> & {
   label?: unknown;
   title?: unknown;
 };
 
+/** Props for the {@link NavDropdown} component. */
 export type NavDropdownProps = Omit<DropdownProps, "children"> &
   Pick<DropdownContentOwnProps, "align" | "side" | "sideOffset"> & {
     label: unknown;

package/src/components/overlays/dropdown-content.tsx

@@ -10,6 +10,11 @@ function DropdownContentBody(props: DropdownContentBodyProps): JSX.Element {
   return <>{props.render()}</>;
 }
 
+/**
+ * Dropdown/context-menu content wrapper around `@askrjs/ui`'s `DropdownContent`.
+ * Non-`asChild` usage lazily evaluates `children` inside a body component so
+ * they're only rendered once the dropdown is actually open.
+ */
 export function DropdownContent(props: DropdownContentProps): JSX.Element | null;
 export function DropdownContent(props: DropdownContentAsChildProps): JSX.Element | null;
 export function DropdownContent(

package/src/components/page/page.tsx

@@ -3,6 +3,7 @@ import { Block } from "../block";
 import { Container } from "../container";
 import type { PageProps } from "./page.types";
 
+/** Top-level page wrapper: a growing `<main>` containing a {@link Container} with vertical page padding and content spacing. */
 export function Page(props: PageProps): JSX.Element {
   const { children, ...rest } = props;
 

package/src/components/page/page.types.ts

@@ -1,3 +1,4 @@
 import type { MainProps } from "../main";
 
+/** Props for the {@link Page} component. */
 export type PageProps = MainProps;

package/src/components/page-header/page-header.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { Block } from "../block";
 import type { PageHeaderProps } from "./page-header.types";
 
+/** Page-level header with a title, optional description, and an actions row that wraps to a new line on small screens. */
 export function PageHeader(props: PageHeaderProps): JSX.Element {
   const { title, description, actions, ...rest } = props;