@apliteni/apliteni-ui 0.121.0 → 0.122.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.121.0",
+  "version": "0.122.0",
   "workspaces": [
     "react"
   ],

package/react/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { InputHTMLAttributes, ReactNode, ButtonHTMLAttributes, RefAttributes, ReactElement, AnchorHTMLAttributes, HTMLAttributes, RefObject, MouseEvent, ElementType, ComponentPropsWithoutRef, SelectHTMLAttributes, TextareaHTMLAttributes, SVGAttributes } from 'react';
+import { FieldsetHTMLAttributes, ReactNode, InputHTMLAttributes, ButtonHTMLAttributes, RefAttributes, ReactElement, AnchorHTMLAttributes, HTMLAttributes, RefObject, MouseEvent, ElementType, ComponentPropsWithoutRef, SelectHTMLAttributes, TextareaHTMLAttributes, SVGAttributes } from 'react';
 import { ACCENTS } from '@apliteni/apliteni-ui';
 
 declare function Icon({ name }: {
@@ -8,12 +8,22 @@ declare function Icon({ name }: {
 
 type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'children'> & {
     label: ReactNode;
+    /** Shown under the label words and described to assistive technology. */
+    hint?: ReactNode;
     type?: 'checkbox' | 'radio';
 };
 declare const Checkbox: react.ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "children"> & {
     label: ReactNode;
+    /** Shown under the label words and described to assistive technology. */
+    hint?: ReactNode;
     type?: "checkbox" | "radio";
 } & react.RefAttributes<HTMLInputElement>>;
+type CheckListProps = Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, 'children'> & {
+    legend: ReactNode;
+    children: ReactNode;
+};
+/** A group of `Checkbox` children under a legend. */
+declare function CheckList({ legend, children, className, ...props }: CheckListProps): react.JSX.Element;
 
 type SwitchProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'children'> & {
     label: string;
@@ -1060,4 +1070,4 @@ declare const AccentPicker: react.ForwardRefExoticComponent<Omit<HTMLAttributes<
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { type Accent, AccentPicker, type AccentPickerProps, type AddFilter, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Chart, type ChartBridgeStep, type ChartBridgeTones, type ChartPeriod, type ChartProps, type ChartSeries, type ChartTone, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };
+export { type Accent, AccentPicker, type AccentPickerProps, type AddFilter, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Chart, type ChartBridgeStep, type ChartBridgeTones, type ChartPeriod, type ChartProps, type ChartSeries, type ChartTone, CheckList, type CheckListProps, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };

package/react/dist/index.js

@@ -15,18 +15,33 @@ function Icon({ name }) {
 }
 
 // src/Checkbox.tsx
-import { forwardRef } from "react";
+import { forwardRef, useId } from "react";
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 var Checkbox = forwardRef(function Checkbox2({
   label,
+  hint,
   type = "checkbox",
+  "aria-describedby": describedBy,
   ...props
 }, ref) {
-  return /* @__PURE__ */ jsxs("label", { className: "ui-check", children: [
-    /* @__PURE__ */ jsx2("input", { ...props, ref, type }),
+  const hintId = useId();
+  const described = [describedBy, hint ? hintId : void 0].filter(Boolean).join(" ") || void 0;
+  const check = /* @__PURE__ */ jsxs("label", { className: "ui-check", children: [
+    /* @__PURE__ */ jsx2("input", { ...props, ref, type, "aria-describedby": described }),
     /* @__PURE__ */ jsx2("span", { children: label })
   ] });
+  if (!hint) return check;
+  return /* @__PURE__ */ jsxs("div", { className: "ui-check-item", children: [
+    check,
+    /* @__PURE__ */ jsx2("div", { id: hintId, className: "ui-check__hint", children: hint })
+  ] });
 });
+function CheckList({ legend, children, className = "", ...props }) {
+  return /* @__PURE__ */ jsxs("fieldset", { ...props, className: `ui-check-list ${className}`.trim(), children: [
+    /* @__PURE__ */ jsx2("legend", { className: "ui-field__label", children: legend }),
+    children
+  ] });
+}
 
 // src/Switch.tsx
 import { forwardRef as forwardRef2 } from "react";
@@ -269,7 +284,7 @@ function Callout({ variant, icon: icon6 = calloutIcons[variant ?? "neutral"], ch
 }
 
 // src/primitives/StatBand.tsx
-import { useId as useId2 } from "react";
+import { useId as useId3 } from "react";
 
 // src/tip.ts
 var TIP_GAP = 8;
@@ -311,7 +326,7 @@ function placeTip(host, mark, tip, bound, placement = "top") {
 }
 
 // src/Tooltip.tsx
-import { useEffect, useId, useLayoutEffect as useLayoutEffect2, useRef as useRef2, useState } from "react";
+import { useEffect, useId as useId2, useLayoutEffect as useLayoutEffect2, useRef as useRef2, useState } from "react";
 import { Fragment, jsx as jsx10, jsxs as jsxs6 } from "react/jsx-runtime";
 var DOC_EVENTS = ["pointerdown", "pointercancel", "click", "keydown", "touchend"];
 var CAPTURED = /* @__PURE__ */ new Set(["pointerdown", "pointercancel"]);
@@ -345,7 +360,7 @@ var Text = ({ label = "", value = "", detail: detail2 = "" }) => /* @__PURE__ */
   /* @__PURE__ */ jsx10("span", { className: "ui-tip__detail", hidden: !detail2, children: detail2 })
 ] });
 function Tooltip({ text: text2, label = text2, value, detail: detail2, placement = "top", children }) {
-  const id = useId();
+  const id = useId2();
   const host = useRef2(null);
   const trigger = useRef2(null);
   const tip = useRef2(null);
@@ -526,7 +541,7 @@ function ContextRow({ caption, delta, basisId }) {
   ] });
 }
 function StatBand({ stats, variant = "tiles", basis, basisId: sharedBasisId, label, id }) {
-  const auto = useId2();
+  const auto = useId3();
   const v = ["band", "tiles", "open"].includes(variant) ? variant : "tiles";
   const basisId = basis ? `${id || auto}-basis` : sharedBasisId;
   const root = ["ui-stats", `ui-stats--${v}`, v === "band" && "ui-card"].filter(Boolean).join(" ");
@@ -549,7 +564,7 @@ function StatBand({ stats, variant = "tiles", basis, basisId: sharedBasisId, lab
 import { useRef as useRef5 } from "react";
 
 // src/Modal.tsx
-import { useId as useId3, useRef as useRef4 } from "react";
+import { useId as useId4, useRef as useRef4 } from "react";
 import { createPortal } from "react-dom";
 
 // src/dialog.ts
@@ -755,7 +770,7 @@ function useDialog(active, { root, panel, body, initialFocus }, onClose) {
 // src/Modal.tsx
 import { jsx as jsx12, jsxs as jsxs8 } from "react/jsx-runtime";
 function Modal({ open, title, onClose, footer, children, initialFocusRef, role = "dialog" }) {
-  const id = useId3();
+  const id = useId4();
   const titleId = `${id}-title`;
   const bodyId = `${id}-body`;
   const root = useRef4(null);
@@ -821,7 +836,7 @@ function Confirm({
 }
 
 // src/Drawer.tsx
-import { useId as useId4, useRef as useRef6 } from "react";
+import { useId as useId5, useRef as useRef6 } from "react";
 import { createPortal as createPortal2 } from "react-dom";
 import { jsx as jsx14, jsxs as jsxs10 } from "react/jsx-runtime";
 function Drawer({
@@ -837,7 +852,7 @@ function Drawer({
   const root = useRef6(null);
   const panel = useRef6(null);
   const body = useRef6(null);
-  const titleId = useId4();
+  const titleId = useId5();
   const { mounted, shown } = usePresence(open, root, panel);
   const scope = useDialog(shown, { root, panel, body }, onClose);
   if (!mounted) return null;
@@ -870,7 +885,7 @@ function Drawer({
 }
 
 // src/CommandPalette.tsx
-import { useCallback, useEffect as useEffect3, useId as useId5, useMemo, useRef as useRef7, useState as useState3 } from "react";
+import { useCallback, useEffect as useEffect3, useId as useId6, useMemo, useRef as useRef7, useState as useState3 } from "react";
 import { createPortal as createPortal3 } from "react-dom";
 import { rankGroups, icon as icon2 } from "@apliteni/apliteni-ui";
 import { jsx as jsx15, jsxs as jsxs11 } from "react/jsx-runtime";
@@ -890,7 +905,7 @@ function CommandPalette({
   rank = true,
   onQueryChange
 }) {
-  const uid = useId5().replace(/:/g, "");
+  const uid = useId6().replace(/:/g, "");
   const root = useRef7(null);
   const panel = useRef7(null);
   const search = useRef7(null);
@@ -1067,7 +1082,7 @@ import { useCallback as useCallback2, useEffect as useEffect5, useMemo as useMem
 import { DEFAULT_PAGE_SIZE as DEFAULT_PAGE_SIZE2 } from "@apliteni/apliteni-ui";
 
 // src/Pagination.tsx
-import { useEffect as useEffect4, useId as useId6, useRef as useRef8, useState as useState4 } from "react";
+import { useEffect as useEffect4, useId as useId7, useRef as useRef8, useState as useState4 } from "react";
 import { DEFAULT_PAGE_SIZE } from "@apliteni/apliteni-ui";
 import { jsx as jsx16, jsxs as jsxs12 } from "react/jsx-runtime";
 var GHOST_SM = "ui-btn ui-btn--ghost ui-btn--sm";
@@ -1111,7 +1126,7 @@ function Pagination({
   onPageChange,
   onPageSizeChange
 }) {
-  const auto = useId6();
+  const auto = useId7();
   const [draft, setDraft] = useState4("");
   const [drafting, setDrafting] = useState4(false);
   const nav = useRef8(null);
@@ -2058,7 +2073,7 @@ import {
   Fragment as Fragment5,
   useCallback as useCallback4,
   useEffect as useEffect7,
-  useId as useId7,
+  useId as useId8,
   useRef as useRef11,
   useState as useState7
 } from "react";
@@ -2142,7 +2157,7 @@ function Dropdown({
   const field = useRef11(null);
   const landOn = useRef11(null);
   const at = useRef11("");
-  const auto = useId7().replace(/:/g, "");
+  const auto = useId8().replace(/:/g, "");
   const uid = id ?? auto;
   const setOpen = useCallback4((next) => {
     if (openProp === void 0) setSelfOpen(next);
@@ -2936,11 +2951,11 @@ function Snippet({ label = "shell", code = "", children, copy = true, reveal = f
 }
 
 // src/Tabs.tsx
-import { useEffect as useEffect9, useId as useId8, useRef as useRef14 } from "react";
+import { useEffect as useEffect9, useId as useId9, useRef as useRef14 } from "react";
 import { playEntrance } from "@apliteni/apliteni-ui/motion";
 import { Fragment as Fragment9, jsx as jsx27, jsxs as jsxs22 } from "react/jsx-runtime";
 function Tabs({ items, value, onChange, label }) {
-  const id = useId8();
+  const id = useId9();
   const previous = useRef14(value);
   const activePanel = useRef14(null);
   const buttons = useRef14([]);
@@ -3063,7 +3078,7 @@ function Timeline({ events, className, ...rest }) {
 }
 
 // src/Field.tsx
-import { forwardRef as forwardRef6, useEffect as useEffect11, useId as useId9, useRef as useRef16, useState as useState10 } from "react";
+import { forwardRef as forwardRef6, useEffect as useEffect11, useId as useId10, useRef as useRef16, useState as useState10 } from "react";
 import { esc, icon as icon4 } from "@apliteni/apliteni-ui";
 import { jsx as jsx29, jsxs as jsxs24 } from "react/jsx-runtime";
 function messages(id, hint, error) {
@@ -3092,12 +3107,12 @@ function wiring(id, hint, error) {
   return { id, "aria-describedby": messages(id, hint, error), "aria-invalid": error ? true : void 0 };
 }
 function Field({ id: suppliedId, label, hint, error, required, children }) {
-  const generatedId = useId9();
+  const generatedId = useId10();
   const id = suppliedId ?? generatedId;
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: children({ ...wiring(id, hint, error), required }) });
 }
 var TextField = forwardRef6(function TextField2({ label, hint, error, required, type = "text", unit, icon: glyph, className = "", ...props }, ref) {
-  const id = useId9();
+  const id = useId10();
   const hasUnit = type === "number" && !!unit;
   const describedBy = [messages(id, hint, error), hasUnit ? `${id}-unit` : ""].filter(Boolean).join(" ") || void 0;
   const control = /* @__PURE__ */ jsx29(
@@ -3124,7 +3139,7 @@ var TextField = forwardRef6(function TextField2({ label, hint, error, required,
   ] }) : control });
 });
 function TextArea({ label, hint, error, required, className = "", ...props }) {
-  const id = useId9();
+  const id = useId10();
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: /* @__PURE__ */ jsx29(
     "textarea",
     {
@@ -3137,7 +3152,7 @@ function TextArea({ label, hint, error, required, className = "", ...props }) {
   ) });
 }
 function SelectField({ label, hint, error, required, className = "", children, ...props }) {
-  const id = useId9();
+  const id = useId10();
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: /* @__PURE__ */ jsx29(
     "select",
     {
@@ -3150,7 +3165,7 @@ function SelectField({ label, hint, error, required, className = "", children, .
   ) });
 }
 function FileField({ label, hint, error, required, disabled, onFileChange, className = "", ...props }) {
-  const id = useId9();
+  const id = useId10();
   const input = useRef16(null);
   const [file, setFile] = useState10(null);
   const [dragging, setDragging] = useState10(false);
@@ -3517,16 +3532,16 @@ function Toast({ children }) {
 }
 
 // src/AppShell.tsx
-import { useEffect as useEffect14, useId as useId11, useState as useState14 } from "react";
+import { useEffect as useEffect14, useId as useId12, useState as useState14 } from "react";
 import { paletteHotkey, prism, railCollapsed } from "@apliteni/apliteni-ui";
 
 // src/SidebarNav.tsx
-import { forwardRef as forwardRef8, useEffect as useEffect13, useId as useId10, useState as useState13 } from "react";
+import { forwardRef as forwardRef8, useEffect as useEffect13, useId as useId11, useState as useState13 } from "react";
 import { ENTRANCE_FALLBACK_MS } from "@apliteni/apliteni-ui/motion";
 import { Fragment as Fragment11, jsx as jsx33, jsxs as jsxs28 } from "react/jsx-runtime";
 var badgeText = (badge) => typeof badge === "object" ? badge.text : badge;
 function Row({ item, active, activeIs, collapsed, renderLink, sub }) {
-  const uid = useId10();
+  const uid = useId11();
   const group = !sub && !!item.items?.length;
   const childActive = group && item.items.some((child) => child.id === active);
   const [expanded, setExpanded] = useState13();
@@ -3583,7 +3598,7 @@ function Row({ item, active, activeIs, collapsed, renderLink, sub }) {
   return /* @__PURE__ */ jsx33("li", { children: renderLink ? renderLink(item, props) : /* @__PURE__ */ jsx33("a", { ...props }) });
 }
 function Section({ section, ...props }) {
-  const uid = useId10();
+  const uid = useId11();
   return /* @__PURE__ */ jsxs28("div", { className: "ui-nav__section", children: [
     section.label && /* @__PURE__ */ jsx33("div", { className: "ui-nav__cap", id: uid, "aria-hidden": props.collapsed || void 0, children: section.label }),
     /* @__PURE__ */ jsx33("ul", { className: "ui-nav__list", "aria-labelledby": section.label ? uid : void 0, children: section.items.map((item) => /* @__PURE__ */ jsx33(Row, { item, ...props }, item.id)) })
@@ -3712,7 +3727,7 @@ function AppShell({
   palette,
   renderLink
 }) {
-  const uid = useId11();
+  const uid = useId12();
   const [collapsed, setCollapsed] = useState14(defaultCollapsed);
   const [search, setSearch] = useState14(false);
   const [more, setMore] = useState14(false);
@@ -4011,7 +4026,7 @@ var Success = forwardRef9(function Success2({
 import {
   useCallback as useCallback6,
   useEffect as useEffect16,
-  useId as useId12,
+  useId as useId13,
   useLayoutEffect as useLayoutEffect5,
   useMemo as useMemo4,
   useRef as useRef20,
@@ -4179,7 +4194,7 @@ function Chart(props) {
   const spark = variant === "spark";
   const plotHeight = height ?? HEIGHT[variant];
   const showTable = table ?? !spark;
-  const uid = useId12().replace(/[^\w-]/g, "");
+  const uid = useId13().replace(/[^\w-]/g, "");
   const frameEl = useRef20(null);
   const scroller = useRef20(null);
   const plot = useRef20(null);
@@ -4741,6 +4756,7 @@ export {
   Callout,
   Card,
   Chart,
+  CheckList,
   Checkbox,
   CommandPalette,
   Confirm,

package/src/styles/input.css

@@ -211,6 +211,32 @@
    holds go quiet with the box beside them. */
 .ui-check:has(input:disabled) { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: not-allowed; }
 
+/* A hint under a box. It sits outside the label, so the label's name stays the label
+   words and the hint is read as a description (aria-describedby), and it takes the
+   field hint's type and ink. The left edge is the label words': the 19px box and the
+   11px gap, a sum that lies between two grid steps for that reason alone. */
+.ui-check-item { display: flex; flex-direction: column; align-items: flex-start; }
+.ui-check__hint {
+  color: var(--text);
+  font-size: var(--text-sm);
+  line-height: 1.5;
+  margin-top: var(--space-1);
+  margin-left: 30px;
+}
+.ui-check-item:has(input:disabled) .ui-check__hint { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); }
+
+/* A group of boxes under a legend, the legend in the field label's type. */
+.ui-check-list {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--space-4);
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+
 /* Toggle switch */
 .ui-switch {
   --sw-w: 44px;