@api7/ui-components 0.6.0 → 0.8.0

package/dist/components/calendar/calendar.js

@@ -1,13 +1,28 @@
 "use client";
+import { buttonVariants } from "../button/button.js";
 import { useLocale } from "../../config/config-provider.js";
 import { cn } from "../../lib/cn.js";
-import { buttonVariants } from "../button/button.js";
 import { createContext, useContext, useEffect, useMemo, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 import { ChevronDown, ChevronLeft, ChevronRight } from "lucide-react";
-import { DayPicker, getDefaultClassNames } from "react-day-picker";
+import { DayPicker, getDefaultClassNames, labelDayButton } from "react-day-picker";
 import { enUS, zhCN } from "react-day-picker/locale";
 // src/components/calendar/calendar.tsx
+/**
+* Wraps a day button label so the day number reads as a word of its own. The default full date
+* format spells the day as an ordinal ("September 1st, 2026"), so the visible text "1" is not part
+* of the accessible name, which WCAG 2.5.3 (Label in Name) and axe's label-content-name-mismatch
+* require. The locale still supplies the weekday, month and the today and selected wording.
+*/
+function withPlainDayNumber(labelDayButton, locale) {
+	const pattern = locale.formatLong?.date({ width: "full" }).replace(/\bdo\b/g, "d");
+	return (date, modifiers, options, dateLib) => {
+		if (!pattern || !dateLib) return labelDayButton(date, modifiers, options, dateLib);
+		const plain = Object.create(dateLib);
+		plain.format = (value, formatStr, formatOptions) => dateLib.format(value, formatStr === "PPPP" ? pattern : formatStr, formatOptions);
+		return labelDayButton(date, modifiers, options, plain);
+	};
+}
 /** Merges a consumer's `classNames` prop with ours key by key. Consumer classes are appended to the
 * key's own classes (the cell's fixed size, range-band fillers and state looks), which they cannot
 * replace: only `` utilities take part in `cn`'s conflict resolution. */
@@ -82,6 +97,11 @@ function Calendar({ className, classNames, locale, navLayout, components, ...pro
 	const configLocale = useLocale();
 	const resolvedLocale = locale ?? (configLocale === "zh-CN" ? zhCN : enUS);
 	const defaultClassNames = getDefaultClassNames();
+	const localeLabel = resolvedLocale.labels?.labelDayButton;
+	const labels = props.labels?.labelDayButton ? props.labels : {
+		...props.labels,
+		labelDayButton: withPlainDayNumber(typeof localeLabel === "function" ? localeLabel : labelDayButton, resolvedLocale)
+	};
 	const resolvedWeekStartsOn = props.ISOWeek ? 1 : props.weekStartsOn ?? resolvedLocale.options?.weekStartsOn ?? 0;
 	const dayContextValue = useMemo(() => ({
 		weekStartsOn: resolvedWeekStartsOn,
@@ -130,7 +150,8 @@ function Calendar({ className, classNames, locale, navLayout, components, ...pro
 			classNames: mergeClassNames(ownClassNames, classNames),
 			components: mergedComponents,
 			...props.mode === "range" ? { resetOnSelect: true } : {},
-			...props
+			...props,
+			labels
 		})
 	});
 }

package/dist/components/cascader/cascader-data.d.ts

@@ -0,0 +1,26 @@
+/** One segment of a selected path. */
+export type CascaderValue = string | number;
+/** One node in the hierarchy. */
+export interface CascaderOption {
+  /** Values must be unique among siblings, but may repeat under different parents. */
+  value: CascaderValue;
+  /** Display label, also used for local search and keyboard typeahead. */
+  label: string;
+  /** Prevents selecting this option or any of its descendants. */
+  disabled?: boolean;
+  /** Immediate children. Undefined allows lazy loading, while an empty array is already loaded. */
+  children?: readonly CascaderOption[];
+  /** Marks a branch, even when loading returns no children. Omit children until they are available. */
+  hasChildren?: boolean;
+}
+/** Context for loading the immediate children of a branch. */
+export interface CascaderLoadRequest {
+  /** Complete parent path from the root to the expanded or unresolved branch. */
+  path: readonly CascaderValue[];
+  /** Option objects corresponding to the parent path. */
+  options: readonly CascaderOption[];
+  /** Aborted when the request becomes obsolete or the component unmounts. */
+  signal: AbortSignal;
+}
+/** Returns immediate children. Rejections show a generic error and an explicit retry action. */
+export type CascaderLoader = (request: CascaderLoadRequest) => Promise<readonly CascaderOption[]>;

package/dist/components/cascader/cascader-data.js

@@ -0,0 +1,110 @@
+"use client";
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
+// src/components/cascader/cascader-data.ts
+const pathKey = (path) => JSON.stringify(path);
+const isBranch = (option) => !!(option.hasChildren || option.children?.length);
+function useCascaderData(options, loadChildren, resetKey, enabled) {
+	const optionsKey = useMemo(() => JSON.stringify(options, [
+		"value",
+		"label",
+		"disabled",
+		"children",
+		"hasChildren"
+	]), [options]);
+	const [cache, setCache] = useState({
+		optionsKey,
+		resetKey,
+		enabled,
+		entries: /* @__PURE__ */ new Map()
+	});
+	const requests = useRef(/* @__PURE__ */ new Map());
+	const loader = useRef(loadChildren);
+	const source = useRef({
+		optionsKey,
+		resetKey,
+		enabled
+	});
+	const entries = cache.optionsKey === optionsKey && Object.is(cache.resetKey, resetKey) ? cache.entries : /* @__PURE__ */ new Map();
+	if (cache.optionsKey !== optionsKey || !Object.is(cache.resetKey, resetKey) || cache.enabled !== enabled) setCache({
+		optionsKey,
+		resetKey,
+		enabled,
+		entries: new Map([...entries].filter(([, entry]) => entry.status !== "loading"))
+	});
+	useLayoutEffect(() => {
+		loader.current = loadChildren;
+	}, [loadChildren]);
+	useLayoutEffect(() => {
+		source.current = {
+			optionsKey,
+			resetKey,
+			enabled
+		};
+		const pending = requests.current;
+		return () => {
+			for (const controller of pending.values()) controller.abort();
+			pending.clear();
+		};
+	}, [
+		optionsKey,
+		resetKey,
+		enabled
+	]);
+	const load = useCallback(async (pathOptions) => {
+		const { optionsKey: root, resetKey: key, enabled: active } = source.current;
+		if (!active || !loader.current) return;
+		const path = pathOptions.map((item) => item.value);
+		const id = pathKey(path);
+		if (requests.current.has(id)) return;
+		const controller = new AbortController();
+		requests.current.set(id, controller);
+		const update = (entry) => {
+			setCache((prev) => ({
+				optionsKey: root,
+				resetKey: key,
+				enabled: active,
+				entries: new Map(prev.optionsKey === root && Object.is(prev.resetKey, key) ? prev.entries : []).set(id, entry)
+			}));
+		};
+		update({ status: "loading" });
+		try {
+			const items = await loader.current({
+				path,
+				options: pathOptions,
+				signal: controller.signal
+			});
+			if (!Array.isArray(items)) throw new TypeError("Cascader loadChildren must resolve to an array.");
+			if (!controller.signal.aborted) update({
+				status: "ready",
+				items
+			});
+		} catch {
+			if (!controller.signal.aborted) update({ status: "error" });
+		} finally {
+			if (requests.current.get(id) === controller) requests.current.delete(id);
+		}
+	}, []);
+	const children = (option, path) => {
+		const entry = entries.get(pathKey(path));
+		return option.children ?? (entry?.status === "ready" ? entry.items : void 0);
+	};
+	const resolve = (path) => {
+		const result = [];
+		let items = options;
+		for (const value of path) {
+			const option = items?.find((item) => item.value === value);
+			if (!option) break;
+			result.push(option);
+			items = children(option, result.map((item) => item.value));
+		}
+		return result;
+	};
+	return {
+		optionsKey,
+		entries,
+		children,
+		resolve,
+		load
+	};
+}
+export { isBranch, pathKey, useCascaderData };

package/dist/components/cascader/cascader.d.ts

@@ -0,0 +1,41 @@
+import { CascaderLoadRequest, CascaderLoader, CascaderOption, CascaderValue } from "./cascader-data.js";
+import { PopoverContentProps } from "../popover/popover.js";
+import { ComponentProps } from "react";
+export type CascaderProps = Omit<ComponentProps<'input'>, 'children' | 'value' | 'defaultValue' | 'onChange' | 'type'> & {
+  /** Root options. Changing their contents invalidates loaded children and restores the selected path. */
+  options: readonly CascaderOption[];
+  /** Selected path. Passing the value key, including undefined, makes selection controlled. */
+  value?: readonly CascaderValue[] | null;
+  /** Initial uncontrolled path, also restored on a native form reset. */
+  defaultValue?: readonly CascaderValue[];
+  /** Receives the path and its option objects on every selection, including reselection. Clearing supplies null and []. */
+  onValueChange?: (value: CascaderValue[] | null, options: readonly CascaderOption[]) => void;
+  /** Allows selecting a branch while keeping its children open. */
+  changeOnSelect?: boolean;
+  /** Loads immediate children on expansion or while resolving a selected path. */
+  loadChildren?: CascaderLoader;
+  /** Invalidates loaded children. The caller owns clearing an obsolete selected value. */
+  resetKey?: unknown;
+  /** Filters supplied and already loaded paths, without fetching unknown descendants. */
+  searchable?: boolean;
+  /** Shows the root loading state and temporarily hides root options. */
+  loading?: boolean;
+  /** Shows a clear button when a value is selected and the control is editable. */
+  clearable?: boolean;
+  /** Preserves the value while preventing opening, editing, and clearing. */
+  readOnly?: boolean;
+  /** Text shown without a selection. Defaults to the configured locale message. */
+  placeholder?: string;
+  /** Controlled popup visibility. Disabled and read-only controls remain closed. */
+  open?: boolean;
+  /** Initial uncontrolled popup visibility. */
+  defaultOpen?: boolean;
+  /** Called when an interaction requests opening or closing, with the requested visibility. */
+  onOpenChange?: (open: boolean) => void;
+  /** Formats the complete path and its resolved option prefix, including empty or unresolved paths. */
+  displayValue?: (value: readonly CascaderValue[], options: readonly CascaderOption[]) => string;
+  /** Customizes the popup's placement, styling, focus behavior, and accessible attributes. */
+  popupProps?: Omit<PopoverContentProps, 'children'>;
+};
+declare function Cascader(props: CascaderProps): import("react").JSX.Element;
+export { Cascader, type CascaderLoadRequest, type CascaderLoader, type CascaderOption, type CascaderValue };