@askrjs/themes 0.0.2 → 0.0.4

package/src/components/navbar/navbar.tsx

@@ -1,31 +1,230 @@
-import { Link } from "@askrjs/askr/router";
-import { Slot } from "@askrjs/askr/foundations";
-import { mergeProps } from "../_internal/merge-props";
-import type {
-  NavBrandProps,
-  NavGroupProps,
-  NavItemAsChildProps,
-  NavItemProps,
-  NavItemVariant,
-  NavLinkProps,
-  NavbarProps,
-} from "./navbar.types";
+import { state } from "@askrjs/askr";
 import { classes } from "../_internal/classes";
+import { isJsxElement, toChildArray } from "../_internal/jsx";
+import { mergeProps } from "../_internal/merge-props";
+import {
+  renderKeyedShellChildren,
+  ShellPanelWatcher,
+  ShellResponsiveWatcher,
+} from "../shell/shell-responsive";
+import { renderNavbarCollapseContents } from "./navbar.render";
+import { NavbarPanel } from "./navbar-panel";
+import { NavbarResponsiveContext } from "./navbar.context";
+import { isNavbarCollapsed, resolveNavGroupAlign } from "./navbar.shared";
+import type { NavBrandProps, NavGroupProps, NavToggleProps, NavbarProps } from "./navbar.types";
 
-function navItemClasses(variant: NavItemVariant, className: unknown): string | undefined {
-  return classes("navbar-item", variant === "icon" && "navbar-item-icon", className);
+/**
+ * Extracts the first NavBrand child to display in the mobile panel.
+ * NavBrand should be the first child of Navbar for it to appear in the mobile menu.
+ */
+function findNavbarBrand(children: unknown): unknown {
+  return toChildArray(children).find((child) => isJsxElement(child) && child.type === NavBrand);
 }
 
+function withoutNavbarBrand(children: unknown): unknown[] {
+  return toChildArray(children).filter(
+    (child) => !(isJsxElement(child) && child.type === NavBrand),
+  );
+}
+
+/**
+ * Responsive mobile-first navbar component.
+ *
+ * Composition: Navbar should contain NavBrand (extracted to mobile panel), NavGroup items with optional align,
+ * and NavLink children. Brand must be first child to appear in mobile menu.
+ *
+ * @example
+ * <Navbar breakpoint="md" aria-label="Main navigation">
+ *   <NavBrand><a href="/">Logo</a></NavBrand>
+ *   <NavGroup align="center">
+ *     <NavLink href="/docs">Docs</NavLink>
+ *   </NavGroup>
+ *   <NavGroup align="end">
+ *     <NavLink href="/settings">Settings</NavLink>
+ *   </NavGroup>
+ * </Navbar>
+ */
 export function Navbar(props: NavbarProps): JSX.Element {
-  const { children, ref, class: className, ...rest } = props;
+  const {
+    children,
+    breakpoint,
+    collapseIcon,
+    collapseIconPlacement = "start",
+    collapseLabel,
+    ref,
+    class: className,
+    id,
+    "aria-label": ariaLabel,
+    ...rest
+  } = props;
+  const effectiveCollapseLabel = collapseLabel ?? "Menu";
+  const responsiveChildren = toChildArray(children);
+  const desktopChildren = renderKeyedShellChildren(responsiveChildren, "navbar-desktop");
+  const panelChildren = renderKeyedShellChildren(
+    withoutNavbarBrand(responsiveChildren),
+    "navbar-panel",
+  );
+  // Extract brand to display in mobile panel header
+  const responsiveCollapsedState =
+    breakpoint !== undefined ? state(isNavbarCollapsed(breakpoint)) : undefined;
+  const mobileMenuState = state(false);
+  const mobileMenuOpen = mobileMenuState();
+  const panelId = typeof id === "string" ? `${id}-panel` : undefined;
+  const responsiveCollapsed = breakpoint !== undefined ? responsiveCollapsedState?.() : false;
+  const panelOpen = Boolean(responsiveCollapsed && mobileMenuOpen);
+  const closePanel = () => mobileMenuState.set(false);
+  const closePanelOnNavActivation = (event: MouseEvent) => {
+    const target = event.target;
+
+    if (!(target instanceof Element)) {
+      return;
+    }
+
+    if (target.closest('a[data-slot="nav-link"], a[data-slot="nav-item"], a.navbar-item')) {
+      closePanel();
+    }
+  };
+  const togglePanel = () => {
+    mobileMenuState.set(!mobileMenuState());
+  };
+  const contextValue = {
+    active: () => breakpoint !== undefined,
+    collapseLabel: () => effectiveCollapseLabel,
+    closePanel,
+    panelId: () => panelId,
+    panelOpen: () => Boolean(responsiveCollapsedState?.() && mobileMenuOpen),
+    togglePanel,
+  };
+  const panelBrand = findNavbarBrand(responsiveChildren);
+  const finalProps = mergeProps(rest, {
+    "aria-label": ariaLabel,
+    ref,
+    class: classes("navbar", className),
+    "data-collapse-below": breakpoint,
+    "data-responsive-collapsed": responsiveCollapsed ? "true" : "false",
+    "data-slot": "navbar",
+  });
 
   return (
-    <nav {...rest} ref={ref} class={classes("navbar", className)} data-slot="navbar">
-      {children}
-    </nav>
+    <NavbarResponsiveContext.Scope value={contextValue}>
+      <nav {...finalProps}>
+        {breakpoint !== undefined ? (
+          <div class="navbar-mobile" data-slot="navbar-mobile">
+            <NavToggle
+              active={breakpoint !== undefined}
+              aria-controls={panelId}
+              aria-label={effectiveCollapseLabel}
+              icon={collapseIcon}
+              iconPlacement={collapseIconPlacement}
+              label={effectiveCollapseLabel}
+              onToggle={togglePanel}
+              open={panelOpen}
+              panelId={panelId}
+            />
+          </div>
+        ) : null}
+
+        <div class="navbar-shell" data-slot="navbar-shell">
+          {desktopChildren}
+        </div>
+
+        {breakpoint !== undefined ? (
+          <NavbarPanel
+            active={breakpoint !== undefined}
+            brand={panelBrand}
+            collapseLabel={effectiveCollapseLabel}
+            onClose={closePanel}
+            onClick={closePanelOnNavActivation}
+            open={panelOpen}
+            panelId={panelId}
+          >
+            {panelChildren}
+          </NavbarPanel>
+        ) : null}
+
+        {responsiveCollapsed && mobileMenuOpen ? (
+          <button
+            aria-label={`Close ${effectiveCollapseLabel}`}
+            class="navbar-backdrop"
+            data-slot="navbar-backdrop"
+            data-state="open"
+            tabIndex={-1}
+            type="button"
+            onClick={closePanel}
+          />
+        ) : null}
+
+        {breakpoint !== undefined ? (
+          <ShellResponsiveWatcher
+            breakpoint={breakpoint}
+            isCollapsed={isNavbarCollapsed}
+            onResize={(nextCollapsed) => {
+              responsiveCollapsedState?.set(nextCollapsed);
+            }}
+            onExpand={() => {
+              mobileMenuState?.set(false);
+            }}
+          />
+        ) : null}
+
+        <ShellPanelWatcher
+          contentId={panelId}
+          open={panelOpen}
+          panelSlot="navbar-panel"
+          onClose={closePanel}
+        />
+      </nav>
+    </NavbarResponsiveContext.Scope>
+  );
+}
+
+/**
+ * Menu toggle button for responsive navbar collapse.
+ * Auto-renders when navbar is responsive (collapseBelow set).
+ */
+export function NavToggle(props: NavToggleProps): JSX.Element | null {
+  const {
+    children,
+    class: className,
+    active,
+    icon,
+    iconPlacement = "start",
+    label = "Menu",
+    ref,
+    onToggle,
+    open,
+    panelId,
+    ...rest
+  } = props;
+
+  if (active === false) {
+    return null;
+  }
+
+  const isOpen = open === true;
+
+  const finalProps = mergeProps(rest, {
+    ref,
+    class: classes("navbar-toggle", className),
+    "aria-controls": panelId,
+    "aria-expanded": isOpen ? "true" : "false",
+    "aria-label": label,
+    "data-slot": "navbar-toggle",
+    "data-state": isOpen ? "open" : "closed",
+    type: "button",
+    onClick: () => onToggle?.(),
+  });
+
+  return (
+    <button {...finalProps}>
+      {children ?? renderNavbarCollapseContents(label, icon, iconPlacement)}
+    </button>
   );
 }
 
+/**
+ * Brand/logo container displayed in navbar and mobile panel header.
+ */
 export function NavBrand(props: NavBrandProps): JSX.Element {
   const { children, ref, class: className, ...rest } = props;
 
@@ -36,44 +235,54 @@ export function NavBrand(props: NavBrandProps): JSX.Element {
   );
 }
 
+/**
+ * Navigation group for organizing related nav items.
+ *
+ * @param align - Alignment: "start" (default), "center", or "end". Using align="end" automatically right-aligns the group.
+ * @param label - Optional accessible label for grouped items.
+ *
+ * @example
+ * <NavGroup align="center">
+ *   <NavLink href="/docs">Docs</NavLink>
+ * </NavGroup>
+ */
 export function NavGroup(props: NavGroupProps): JSX.Element {
-  const { children, ref, class: className, ...rest } = props;
+  const { children, id, ref, class: className, label, ...rest } = props;
+  const rawAlign = (rest as Record<string, unknown>)["data-align"];
+  const align =
+    props.align ??
+    (rawAlign === "start" || rawAlign === "center" || rawAlign === "end"
+      ? (rawAlign as NavGroupProps["align"])
+      : undefined);
+  const hasLabel = label !== undefined && label !== null;
+  const labelId = hasLabel && id ? `${id}-label` : undefined;
+  const accessibleLabel = typeof label === "string" ? label : undefined;
 
   return (
-    <div {...rest} ref={ref} class={classes("navbar-group", className)} data-slot="navbar-group">
-      {children}
+    <div
+      {...rest}
+      id={id}
+      ref={ref}
+      class={classes("navbar-group", className)}
+      aria-label={labelId ? undefined : accessibleLabel}
+      aria-labelledby={labelId}
+      role={hasLabel ? "group" : rest.role}
+      data-align={resolveNavGroupAlign(align)}
+      data-has-label={hasLabel ? "true" : undefined}
+      data-slot="navbar-group"
+    >
+      {hasLabel ? (
+        <>
+          <div id={labelId} class="navbar-group-label" data-slot="navbar-group-label">
+            {label}
+          </div>
+          <div class="navbar-group-body" data-slot="navbar-group-body">
+            {children}
+          </div>
+        </>
+      ) : (
+        children
+      )}
     </div>
   );
 }
-
-export function NavItem(props: NavItemProps): JSX.Element;
-export function NavItem(props: NavItemAsChildProps): JSX.Element;
-export function NavItem(props: NavItemProps | NavItemAsChildProps): JSX.Element {
-  const { asChild, children, ref, class: className, variant = "default", ...rest } = props;
-
-  const finalProps = mergeProps(rest, {
-    ref,
-    class: navItemClasses(variant, className),
-    "data-slot": "nav-item",
-    "data-variant": variant,
-  });
-
-  if (asChild) {
-    return <Slot asChild {...finalProps} children={children} />;
-  }
-
-  return <a {...finalProps}>{children}</a>;
-}
-
-export function NavLink(props: NavLinkProps): JSX.Element {
-  const { children, ref, class: className, variant = "default", ...rest } = props;
-
-  const finalProps = mergeProps(rest, {
-    ref,
-    class: navItemClasses(variant, className),
-    "data-slot": "nav-link",
-    "data-variant": variant,
-  });
-
-  return <Link {...finalProps}>{children}</Link>;
-}

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

@@ -1,36 +1,50 @@
-import type { JSXElement, Ref } from "@askrjs/askr/foundations";
-import type { LinkProps } from "@askrjs/askr/router";
+export type {
+  NavItemAsChildProps,
+  NavItemProps,
+  NavItemVariant,
+  NavLinkProps,
+} from "../nav/nav.types";
+import type { CollapseBreakpoint, CollapseIconPlacement } from "../shell/shell-nav.types";
+
+export type NavGroupAlign = "start" | "center" | "end";
 
 export type NavbarProps = Omit<JSX.IntrinsicElements["nav"], "children"> & {
   children?: unknown;
+  breakpoint?: CollapseBreakpoint;
+  collapseIcon?: unknown;
+  collapseIconPlacement?: CollapseIconPlacement;
+  collapseLabel?: string;
 };
-
 export type NavBrandProps = Omit<JSX.IntrinsicElements["div"], "children"> & {
   children?: unknown;
 };
 
-export type NavGroupProps = Omit<JSX.IntrinsicElements["div"], "children"> & {
+export type NavToggleProps = Omit<
+  JSX.IntrinsicElements["button"],
+  "children" | "type" | "onClick"
+> & {
   children?: unknown;
+  active?: boolean;
+  icon?: unknown;
+  iconPlacement?: CollapseIconPlacement;
+  label?: string;
+  onToggle?: () => void;
+  open?: boolean;
+  panelId?: string;
 };
 
-export type NavItemVariant = "default" | "icon";
-
-export type NavItemOwnProps = {
+export type NavbarPanelProps = Omit<JSX.IntrinsicElements["div"], "children"> & {
+  active?: boolean;
+  brand?: unknown;
   children?: unknown;
-  variant?: NavItemVariant;
+  collapseLabel?: string;
+  onClose?: () => void;
+  open?: boolean;
+  panelId?: string;
 };
 
-export type NavItemProps = Omit<JSX.IntrinsicElements["a"], "children" | "ref"> &
-  NavItemOwnProps & {
-    asChild?: false;
-    ref?: Ref<HTMLAnchorElement>;
-  };
-
-export type NavItemAsChildProps = Omit<JSX.IntrinsicElements["a"], "children" | "ref"> &
-  NavItemOwnProps & {
-    asChild: true;
-    children: JSXElement;
-    ref?: Ref<unknown>;
-  };
-
-export type NavLinkProps = LinkProps & NavItemOwnProps;
+export type NavGroupProps = Omit<JSX.IntrinsicElements["div"], "children"> & {
+  align?: NavGroupAlign;
+  children?: unknown;
+  label?: unknown;
+};

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

@@ -0,0 +1,28 @@
+import { DropdownContent as UiDropdownContent } from "@askrjs/ui";
+import type { DropdownContentAsChildProps, DropdownContentProps } from "@askrjs/ui";
+
+type DropdownContentBodyProps = {
+  render: () => unknown;
+};
+
+function DropdownContentBody(props: DropdownContentBodyProps): JSX.Element {
+  return <>{props.render()}</>;
+}
+
+export function DropdownContent(props: DropdownContentProps): JSX.Element | null;
+export function DropdownContent(props: DropdownContentAsChildProps): JSX.Element | null;
+export function DropdownContent(
+  props: DropdownContentProps | DropdownContentAsChildProps,
+): JSX.Element | null {
+  if ("asChild" in props && props.asChild) {
+    return <UiDropdownContent {...props} />;
+  }
+
+  const { children, ...rest } = props as DropdownContentProps;
+
+  return (
+    <UiDropdownContent {...rest}>
+      <DropdownContentBody render={() => children} />
+    </UiDropdownContent>
+  );
+}

package/src/components/pagination/index.ts

@@ -0,0 +1,8 @@
+export { Pagination, PaginationEllipsis, PaginationItem, PaginationLink } from "./pagination";
+export type {
+  PaginationEllipsisProps,
+  PaginationItemAsChildProps,
+  PaginationItemProps,
+  PaginationLinkProps,
+  PaginationProps,
+} from "./pagination.types";

package/src/components/pagination/pagination.tsx

@@ -0,0 +1,158 @@
+import { navigate } from "@askrjs/askr/router";
+import { Slot } from "@askrjs/askr/foundations";
+import { mergeProps } from "@askrjs/askr/foundations/utilities";
+import { classes } from "../_internal/classes";
+import { resolvePathname } from "../_internal/pathname";
+import type {
+  PaginationEllipsisProps,
+  PaginationItemAsChildProps,
+  PaginationItemProps,
+  PaginationLinkProps,
+  PaginationProps,
+} from "./pagination.types";
+
+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
+  );
+}
+
+export function Pagination(props: PaginationProps): JSX.Element {
+  const { children, class: className, label = "Pagination", ref, ...rest } = props;
+
+  return (
+    <nav
+      {...rest}
+      ref={ref}
+      class={classes("pagination", className)}
+      aria-label={label}
+      data-slot="pagination"
+    >
+      <ul class="pagination-list" data-slot="pagination-list">
+        {children}
+      </ul>
+    </nav>
+  );
+}
+
+export function PaginationItem(props: PaginationItemProps): JSX.Element;
+export function PaginationItem(props: PaginationItemAsChildProps): JSX.Element;
+export function PaginationItem(
+  props: PaginationItemProps | PaginationItemAsChildProps,
+): JSX.Element {
+  const {
+    active = false,
+    asChild,
+    children,
+    disabled = false,
+    ref,
+    class: className,
+    ...rest
+  } = props;
+  const finalProps = mergeProps(rest, {
+    class: classes(
+      "page-item",
+      active ? "active" : undefined,
+      disabled ? "disabled" : undefined,
+      className,
+    ),
+    ref,
+    "aria-current": active ? "page" : undefined,
+    "aria-disabled": disabled ? "true" : undefined,
+    "data-active": active ? "true" : undefined,
+    "data-disabled": disabled ? "true" : undefined,
+    "data-slot": "pagination-item",
+  });
+
+  if (asChild) {
+    return <Slot asChild {...finalProps} children={children} />;
+  }
+
+  return <li {...finalProps}>{children}</li>;
+}
+
+export function PaginationLink(props: PaginationLinkProps): JSX.Element {
+  const {
+    active = false,
+    children,
+    class: className,
+    disabled = false,
+    href,
+    onClick,
+    ref,
+    target,
+    ...rest
+  } = props as PaginationLinkProps & { onClick?: (event: MouseEvent) => void };
+  const hrefValue = href as string;
+  const targetValue = target as string | undefined;
+  const targetPathname = resolvePathname(hrefValue);
+  const isActive = active;
+
+  const linkProps = mergeProps(rest, {
+    href,
+    target: targetValue,
+    ref,
+    class: classes(
+      "page-link",
+      active ? "active" : undefined,
+      disabled ? "disabled" : undefined,
+      className,
+    ),
+    "aria-current": isActive ? "page" : undefined,
+    "aria-disabled": disabled ? "true" : undefined,
+    "data-active": isActive ? "true" : undefined,
+    "data-disabled": disabled ? "true" : undefined,
+    "data-slot": "pagination-link",
+    tabIndex: disabled ? -1 : undefined,
+  });
+
+  const handleClick = (event: MouseEvent) => {
+    onClick?.(event);
+
+    if (disabled || !shouldHandleClientNavigation(event, targetValue, targetPathname)) {
+      if (disabled) {
+        event.preventDefault();
+      }
+
+      return;
+    }
+
+    event.preventDefault();
+    navigate(hrefValue);
+  };
+
+  return (
+    <a {...linkProps} onClick={handleClick}>
+      {children}
+    </a>
+  );
+}
+
+export function PaginationEllipsis(props: PaginationEllipsisProps): JSX.Element {
+  const { children, class: className, ref, ...rest } = props;
+
+  return (
+    <span
+      {...rest}
+      ref={ref}
+      class={classes("pagination-ellipsis", className)}
+      aria-hidden="true"
+      data-slot="pagination-ellipsis"
+    >
+      {children ?? "..."}
+    </span>
+  );
+}

package/src/components/pagination/pagination.types.ts

@@ -0,0 +1,41 @@
+import type { JSXElement } from "@askrjs/askr/foundations";
+import type { Ref } from "@askrjs/askr/foundations/utilities";
+
+type NavProps = Omit<JSX.IntrinsicElements["nav"], "children" | "ref" | "aria-label">;
+type LiProps = Omit<JSX.IntrinsicElements["li"], "children" | "ref">;
+type AnchorProps = Omit<JSX.IntrinsicElements["a"], "children" | "ref">;
+
+export type PaginationProps = NavProps & {
+  children?: unknown;
+  label?: string;
+  ref?: Ref<HTMLElement>;
+};
+
+export type PaginationItemProps = LiProps & {
+  active?: boolean;
+  asChild?: false;
+  children?: unknown;
+  disabled?: boolean;
+  ref?: Ref<HTMLLIElement>;
+};
+
+export type PaginationItemAsChildProps = LiProps & {
+  active?: boolean;
+  asChild: true;
+  children: JSXElement;
+  disabled?: boolean;
+  ref?: Ref<unknown>;
+};
+
+export type PaginationLinkProps = AnchorProps & {
+  active?: boolean;
+  children?: unknown;
+  disabled?: boolean;
+  href: string;
+  ref?: Ref<HTMLAnchorElement>;
+};
+
+export type PaginationEllipsisProps = Omit<JSX.IntrinsicElements["span"], "children" | "ref"> & {
+  children?: unknown;
+  ref?: Ref<HTMLSpanElement>;
+};

package/src/components/section/section.tsx

@@ -3,7 +3,7 @@ import { mergeProps } from "../_internal/merge-props";
 import {
   applyBoxLayoutStyles,
   splitBoxLayoutProps,
-  withBoxLayoutStyle,
+  withBoxLayoutClass,
 } from "../_internal/box-layout";
 import { serializeResponsiveValueIf } from "../_internal/layout";
 import type { SectionAsChildProps, SectionElementProps } from "./section.types";
@@ -20,13 +20,14 @@ export function Section(props: SectionElementProps | SectionAsChildProps) {
   const { boxProps, rest: passthroughProps } = splitBoxLayoutProps(rest);
   const layoutStyle: Record<string, string | number> = {};
   applyBoxLayoutStyles(layoutStyle, boxProps);
+  const layoutClass = withBoxLayoutClass(layoutStyle, userStyle);
 
   const finalProps = mergeProps(passthroughProps, {
     ref,
     "data-slot": "section",
     "data-ak-layout": "true",
     "data-size": serializeResponsiveValueIf(size, isSectionSizeToken),
-    style: withBoxLayoutStyle(layoutStyle, userStyle),
+    ...(layoutClass ? { class: layoutClass } : {}),
   });
 
   if (asChild) {

package/src/components/section/section.types.ts

@@ -1,4 +1,5 @@
-import type { JSXElement, Ref } from "@askrjs/askr/foundations";
+import type { JSXElement } from "@askrjs/askr/foundations";
+import type { Ref } from "@askrjs/askr/foundations/utilities";
 import type { BoxLayoutOwnProps, LayoutResponsive } from "../box/box.types";
 
 export type SectionOwnProps = BoxLayoutOwnProps & {

package/src/components/separator/separator.types.ts

@@ -1,4 +1,5 @@
-import type { JSXElement, Ref } from "@askrjs/askr/foundations";
+import type { JSXElement } from "@askrjs/askr/foundations";
+import type { Ref } from "@askrjs/askr/foundations/utilities";
 
 export type SeparatorOwnProps = {
   decorative?: boolean;