@askrjs/themes 0.0.25 → 0.0.27

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

@@ -2,22 +2,26 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { JSXElement } from "@askrjs/askr/foundations";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Props shared by both {@link Separator} call signatures. */
 export type SeparatorOwnProps = {
   decorative?: boolean;
   orientation?: "horizontal" | "vertical";
   children?: unknown;
 };
 
+/** Props for {@link Separator} rendered as its default `<div>` element. */
 export type SeparatorNativeProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref"> &
   SeparatorOwnProps & {
     asChild?: false;
     ref?: Ref<HTMLDivElement>;
   };
 
+/** Props for {@link Separator} rendered with `asChild`, merging its attributes onto a single child element. */
 export type SeparatorAsChildProps = SeparatorOwnProps & {
   asChild: true;
   children: JSXElement;
   ref?: Ref<unknown>;
 };
 
+/** Union of all prop shapes accepted by {@link Separator}. */
 export type SeparatorProps = SeparatorNativeProps | SeparatorAsChildProps;

package/src/components/sidebar/sidebar.tsx

@@ -39,6 +39,7 @@ function sidebarPart(
   return intrinsicElement(String(as ?? element), finalProps, children);
 }
 
+/** Root `<aside>` sidebar layout with configurable width, side, collapse behavior, and visual variant, exposed as data attributes for CSS. */
 export function Sidebar(props: SidebarProps): JSX.Element {
   const {
     children,
@@ -70,46 +71,57 @@ export function Sidebar(props: SidebarProps): JSX.Element {
   );
 }
 
+/** Scoping wrapper that establishes the sidebar's CSS/context boundary. */
 export function SidebarScope(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-scope");
 }
 
+/** Renders the `<main>` content area beside the {@link Sidebar}. */
 export function SidebarInset(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-inset", "main");
 }
 
+/** Renders the scrollable content region of a {@link Sidebar}. */
 export function SidebarContent(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-content");
 }
 
+/** Renders the header region of a {@link Sidebar}. */
 export function SidebarHeader(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-header");
 }
 
+/** Renders the footer region of a {@link Sidebar}. */
 export function SidebarFooter(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-footer");
 }
 
+/** Groups related {@link SidebarMenu} items together. */
 export function SidebarGroup(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-group");
 }
 
+/** Renders the label for a {@link SidebarGroup}. */
 export function SidebarGroupLabel(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-group-label");
 }
 
+/** Renders the content region of a {@link SidebarGroup}. */
 export function SidebarGroupContent(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-group-content");
 }
 
+/** Renders a `<ul>` list of {@link SidebarMenuItem}s. */
 export function SidebarMenu(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-menu", "ul");
 }
 
+/** Renders a single `<li>` entry within a {@link SidebarMenu}. */
 export function SidebarMenuItem(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-menu-item", "li");
 }
 
+/** Clickable menu button within a {@link SidebarMenuItem}; supports `active`/`size`/`variant` state and an optional tooltip. */
 export function SidebarMenuButton(props: SidebarButtonProps): JSX.Element {
   const {
     active,
@@ -143,6 +155,7 @@ export function SidebarMenuButton(props: SidebarButtonProps): JSX.Element {
   );
 }
 
+/** Renders a secondary action button attached to a {@link SidebarMenuItem}, with an optional tooltip. */
 export function SidebarMenuAction(props: SidebarButtonProps): JSX.Element {
   const {
     asChild,
@@ -166,10 +179,12 @@ export function SidebarMenuAction(props: SidebarButtonProps): JSX.Element {
   );
 }
 
+/** Renders a status badge attached to a {@link SidebarMenuItem}. */
 export function SidebarMenuBadge(props: SidebarPartProps): JSX.Element {
   return sidebarPart(props, "sidebar-menu-badge", "span");
 }
 
+/** Renders a draggable/clickable rail along the sidebar's edge for resizing or toggling it. */
 export function SidebarRail(props: SidebarButtonProps): JSX.Element {
   const { asChild, children, class: className, type = "button", ...rest } = props;
   const finalProps = mergeProps(normalizeAriaProps(rest), {
@@ -184,6 +199,7 @@ export function SidebarRail(props: SidebarButtonProps): JSX.Element {
   );
 }
 
+/** Icon button that toggles the {@link Sidebar}'s open/collapsed state, with an optional tooltip. */
 export function SidebarTrigger(props: SidebarButtonProps): JSX.Element {
   const {
     asChild,

package/src/components/sidebar/sidebar.types.ts

@@ -1,11 +1,16 @@
 import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { BlockElementProps } from "../block";
 
+/** How a {@link Sidebar} collapses: fully off-canvas, down to icons only, or not at all. */
 export type SidebarCollapsible = "offcanvas" | "icon" | "none";
+/** Which edge of the viewport a {@link Sidebar} is docked to. */
 export type SidebarSide = "left" | "right";
+/** Side a sidebar button's tooltip is positioned on. */
 export type SidebarTooltipSide = "top" | "bottom" | "left" | "right";
+/** Visual style of a {@link Sidebar}. */
 export type SidebarVariant = "sidebar" | "floating" | "inset";
 
+/** Props for the {@link Sidebar} component. */
 export type SidebarProps = Omit<BlockElementProps<"aside">, "as" | "width" | "shrink"> & {
   collapsible?: SidebarCollapsible;
   side?: SidebarSide;
@@ -14,11 +19,13 @@ export type SidebarProps = Omit<BlockElementProps<"aside">, "as" | "width" | "sh
   shrink?: BlockElementProps<"aside">["shrink"];
 };
 
+/** Props shared by the generic {@link Sidebar} structural parts (content, header, footer, group, etc.). */
 export type SidebarPartProps = JSX.IntrinsicElements["div"] & {
   as?: keyof JSX.IntrinsicElements;
   asChild?: boolean;
 };
 
+/** Props shared by the interactive {@link Sidebar} button parts (menu button, action, trigger). */
 export type SidebarButtonProps = JSX.IntrinsicElements["button"] & {
   active?: boolean;
   asChild?: boolean;
@@ -28,4 +35,5 @@ export type SidebarButtonProps = JSX.IntrinsicElements["button"] & {
   variant?: "default" | "outline";
 };
 
+/** Props for the {@link SidebarRail} component. */
 export type SidebarRailProps = SidebarButtonProps;

package/src/components/skeleton/skeleton.tsx

@@ -12,6 +12,7 @@ function resolveSkeletonDimension(value: string | number | undefined): string |
   return value;
 }
 
+/** Loading placeholder block with configurable `width`/`height`, hidden from assistive tech via `aria-hidden`, rendered as a `<div>` or merged onto a child via `asChild`. */
 export function Skeleton(props: SkeletonProps): JSX.Element;
 export function Skeleton(props: SkeletonAsChildProps): JSX.Element;
 export function Skeleton(props: SkeletonProps | SkeletonAsChildProps) {

package/src/components/skeleton/skeleton.types.ts

@@ -2,18 +2,21 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { JSXElement } from "@askrjs/askr/foundations";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Props shared by both {@link Skeleton} call signatures. */
 export type SkeletonOwnProps = {
   children?: unknown;
   height?: string | number;
   width?: string | number;
 };
 
+/** Props for {@link Skeleton} rendered as its default `<div>` element. */
 export type SkeletonProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref"> &
   SkeletonOwnProps & {
     asChild?: false;
     ref?: Ref<HTMLDivElement>;
   };
 
+/** Props for {@link Skeleton} rendered with `asChild`, merging its attributes onto a single child element. */
 export type SkeletonAsChildProps = SkeletonOwnProps & {
   asChild: true;
   children: JSXElement;

package/src/components/spinner/spinner.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { ProgressCircle, ProgressCircleIndicator } from "@askrjs/ui";
 import type { SpinnerProps } from "./spinner.types";
 
+/** Indeterminate loading spinner built on `ProgressCircle`, with an accessible label (defaults to `"Loading"`) and a `size` modifier. */
 export function Spinner(props: SpinnerProps): JSX.Element {
   const {
     label,

package/src/components/spinner/spinner.types.ts

@@ -1,10 +1,13 @@
 import type { ProgressCircleProps } from "@askrjs/ui";
 
+/** Size modifier for {@link Spinner}. */
 export type SpinnerSize = "sm" | "md" | "lg";
 
+/** Props specific to {@link Spinner}, layered on top of `ProgressCircleProps`. */
 export type SpinnerOwnProps = Omit<ProgressCircleProps, "value" | "getValueLabel"> & {
   label?: string;
   size?: SpinnerSize;
 };
 
+/** Props for the {@link Spinner} component. */
 export type SpinnerProps = SpinnerOwnProps;

package/src/components/stat/stat.tsx

@@ -3,6 +3,7 @@ import { classes } from "../_internal/classes";
 import { mergeProps } from "../_internal/merge-props";
 import type { StatDescriptionProps, StatLabelProps, StatProps, StatValueProps } from "./stat.types";
 
+/** Container for a labeled statistic (label, value, description). */
 export function Stat(props: StatProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -14,6 +15,7 @@ export function Stat(props: StatProps): JSX.Element {
   return <div {...finalProps}>{children}</div>;
 }
 
+/** Renders the label of a {@link Stat}. */
 export function StatLabel(props: StatLabelProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -25,6 +27,7 @@ export function StatLabel(props: StatLabelProps): JSX.Element {
   return <p {...finalProps}>{children}</p>;
 }
 
+/** Renders the primary value of a {@link Stat}. */
 export function StatValue(props: StatValueProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {
@@ -36,6 +39,7 @@ export function StatValue(props: StatValueProps): JSX.Element {
   return <p {...finalProps}>{children}</p>;
 }
 
+/** Renders supporting description text for a {@link Stat}. */
 export function StatDescription(props: StatDescriptionProps): JSX.Element {
   const { children, class: className, ref, ...rest } = props;
   const finalProps = mergeProps(rest, {

package/src/components/stat/stat.types.ts

@@ -4,21 +4,25 @@ 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 Stat} component. */
 export type StatProps = DivProps & {
   children?: unknown;
   ref?: Ref<HTMLDivElement>;
 };
 
+/** Props for the {@link StatLabel} component. */
 export type StatLabelProps = ParagraphProps & {
   children?: unknown;
   ref?: Ref<HTMLParagraphElement>;
 };
 
+/** Props for the {@link StatValue} component. */
 export type StatValueProps = ParagraphProps & {
   children?: unknown;
   ref?: Ref<HTMLParagraphElement>;
 };
 
+/** Props for the {@link StatDescription} component. */
 export type StatDescriptionProps = ParagraphProps & {
   children?: unknown;
   ref?: Ref<HTMLParagraphElement>;

package/src/components/text/text.tsx

@@ -6,6 +6,7 @@ import type { TextElement, TextProps } from "./text.types";
 
 const DEFAULT_ELEMENT = "p";
 
+/** Typography primitive: renders any {@link TextElement} (default `<p>`) and turns `size`/`tone`/`weight`/`font`/`numeric`/`wrap`/`truncate` into data attributes for CSS styling. */
 export function Text<TElement extends TextElement = "p">(props: TextProps<TElement>): JSX.Element {
   const {
     as,

package/src/components/text/text.types.ts

@@ -1,8 +1,11 @@
 import type { JSX } from "@askrjs/askr/jsx-runtime";
 import type { Ref } from "@askrjs/askr/foundations/utilities";
 
+/** Element tags {@link Text} can render as via its `as` prop. */
 export type TextElement = "p" | "span" | "div" | "strong";
+/** Font size modifier for {@link Text}. */
 export type TextSize = "sm" | "md" | "lg";
+/** Color tone modifier for {@link Text}. */
 export type TextTone =
   | "default"
   | "muted"
@@ -12,9 +15,13 @@ export type TextTone =
   | "warning"
   | "danger"
   | "info";
+/** Font weight modifier for {@link Text}. */
 export type TextWeight = "normal" | "medium" | "semibold" | "bold";
+/** Font family modifier for {@link Text}. */
 export type TextFont = "body" | "mono";
+/** Numeric glyph variant (e.g. tabular figures) for {@link Text}. */
 export type TextNumeric = "normal" | "tabular";
+/** White-space wrapping behavior for {@link Text}. */
 export type TextWrap = "normal" | "nowrap" | "anywhere";
 
 type TextIntrinsicProps<TElement extends TextElement> = Omit<
@@ -22,6 +29,7 @@ type TextIntrinsicProps<TElement extends TextElement> = Omit<
   "children" | "ref"
 >;
 
+/** Props for the {@link Text} component, specialized for a given {@link TextElement} `TElement`. */
 export type TextProps<TElement extends TextElement = "p"> = TextIntrinsicProps<TElement> & {
   as?: TElement;
   size?: TextSize;

package/src/components/theme/theme.tsx

@@ -4,16 +4,21 @@ import { cloneElement, isElement, type JSXElement } from "@askrjs/askr/foundatio
 import { Button } from "@askrjs/ui";
 import type { ButtonNativeProps, PressEvent } from "@askrjs/ui";
 
+/** Names of the built-in "cat" theme presets. */
 export const CAT_THEME_NAMES = ["tabby", "ginger", "tuxedo", "calico", "torty"] as const;
 
+/** A built-in "cat" theme name, one of {@link CAT_THEME_NAMES}. */
 export type CatThemeName = (typeof CAT_THEME_NAMES)[number];
+/** Any theme identifier accepted by {@link ThemeScope}: `"light"`, `"dark"`, `"system"`, a {@link CatThemeName}, or a custom string. */
 export type ThemeName = "light" | "dark" | "system" | CatThemeName | (string & {});
 
+/** A theme choice offered by {@link ThemePicker}/{@link ThemeToggle}: a `value` paired with a display `label`. */
 export type ThemeOption = {
   value: ThemeName;
   label: string;
 };
 
+/** Value read from {@link theme}: the active theme, its resolved system value, a setter, and the available theme options. */
 export type ThemeScopeValue = {
   theme: () => ThemeName;
   resolvedSystemTheme: () => "light" | "dark";
@@ -22,6 +27,7 @@ export type ThemeScopeValue = {
   storageKey: string;
 };
 
+/** Props for the {@link ThemeScope} component. */
 export type ThemeScopeProps = {
   children?: unknown;
   defaultTheme?: ThemeName;
@@ -29,6 +35,7 @@ export type ThemeScopeProps = {
   storageKey?: string;
 };
 
+/** Props for the {@link ThemePicker} component. */
 export type ThemePickerProps = Omit<
   JSX.IntrinsicElements["select"],
   "children" | "value" | "defaultValue" | "onChange"
@@ -37,11 +44,13 @@ export type ThemePickerProps = Omit<
   label?: string;
 };
 
+/** Render context passed to a function-as-children {@link ThemeToggleProps.children}. */
 export type ThemeToggleRenderContext = {
   theme: ThemeName;
   nextTheme: ThemeName;
 };
 
+/** Props for the {@link ThemeToggle} component. */
 export type ThemeToggleProps = Omit<ButtonNativeProps, "children" | "onPress"> & {
   children?: unknown | ((context: ThemeToggleRenderContext) => unknown);
   lightIcon?: unknown;
@@ -51,12 +60,14 @@ export type ThemeToggleProps = Omit<ButtonNativeProps, "children" | "onPress"> &
   onPress?: (event: PressEvent) => void;
 };
 
+/** Default light/dark/system theme options used by {@link ThemeScope} and {@link ThemePicker}. */
 export const DEFAULT_THEME_OPTIONS: readonly ThemeOption[] = [
   { value: "system", label: "System" },
   { value: "light", label: "Light" },
   { value: "dark", label: "Dark" },
 ];
 
+/** Theme options for the built-in "cat" theme presets, keyed to {@link CAT_THEME_NAMES}. */
 export const CAT_THEME_OPTIONS: readonly ThemeOption[] = [
   { value: "tabby", label: "Tabby" },
   { value: "ginger", label: "Ginger" },
@@ -84,10 +95,18 @@ const ThemeScopeContext = defineScope<InternalThemeScopeValue>({
   depth: -1,
 });
 
+/** Reads the current {@link ThemeScopeValue} from the nearest enclosing {@link ThemeScope}. */
 export function theme(): ThemeScopeValue {
   return readScope(ThemeScopeContext);
 }
 
+/**
+ * Establishes a theme boundary: tracks the active theme (persisted to
+ * `localStorage` under `storageKey` and synced across tabs/scopes), resolves
+ * the OS `"system"` preference, and reflects the choice onto the DOM via
+ * `data-theme`/`data-theme-choice` attributes. Nested scopes cooperate
+ * through a shared coordinator so the deepest explicitly-set scope wins.
+ */
 export function ThemeScope(props: ThemeScopeProps): JSX.Element {
   const {
     children,
@@ -318,6 +337,7 @@ function createThemeCoordinator() {
   });
 }
 
+/** A `<select>` bound to the current {@link theme}, listing `themes` (defaults to the enclosing scope's options). */
 export function ThemePicker(props: ThemePickerProps): JSX.Element {
   const activeTheme = theme();
   const { themes = activeTheme.themes, label = "Theme", ...rest } = props;
@@ -362,6 +382,11 @@ function getThemePickerTarget(event: Event): HTMLSelectElement | null {
   return null;
 }
 
+/**
+ * A button that cycles through `themes` (defaults to `["light", "dark"]`) on
+ * press. Supports icon props per theme, or a function-as-children render
+ * prop receiving {@link ThemeToggleRenderContext}.
+ */
 export function ThemeToggle(props: ThemeToggleProps): JSX.Element {
   const activeTheme = theme();
   const {

package/src/components/toolbar/toolbar.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "@askrjs/askr/jsx-runtime";
 import { Block } from "../block";
 import type { ToolbarProps } from "./toolbar.types";
 
+/** Titled toolbar row with an actions area, wrapping to a new line on small screens. */
 export function Toolbar(props: ToolbarProps): JSX.Element {
   const { title, actions, ...rest } = props;
 

package/src/components/toolbar/toolbar.types.ts

@@ -1,5 +1,6 @@
 import type { BlockDivProps } from "../block";
 
+/** Props for the {@link Toolbar} component. */
 export type ToolbarProps = BlockDivProps & {
   title: unknown;
   actions?: unknown;