@astryxdesign/core 0.7.8-canary.d3ec2ef → 0.7.8-canary.e4c81f3

package/dist/CheckboxList/CheckboxList.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file CheckboxList.tsx
- * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext
+ * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext, requiredGroup
  * @output Exports CheckboxList component, CheckboxListProps
  * @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
  *
@@ -39,6 +39,17 @@ export interface CheckboxListProps extends Omit<FieldInputBaseProps<HTMLDivEleme
      * @default false
      */
     isOptional?: boolean;
+    /**
+     * Whether the group needs at least one checked box. Shows the required
+     * indicator after the group label by the same rules as every input field.
+     * While no box is checked, the browser blocks submit and moves focus to
+     * the first box that is neither disabled nor read-only. A disabled or
+     * read-only group requires nothing. Show your own error text through
+     * `status`.
+     * Mutually exclusive with isOptional.
+     * @default false
+     */
+    isRequired?: boolean;
     /**
      * Status indicator for the checkbox group.
      * When set with a message, displays a colored message box below the group.
@@ -122,7 +133,7 @@ export interface CheckboxListProps extends Omit<FieldInputBaseProps<HTMLDivEleme
  * </CheckboxList>
  * ```
  */
-export declare function CheckboxList({ label, isLabelHidden, description, isOptional, status, value, onChange, changeAction, density, hasDividers, isDisabled, disabledMessage, isReadOnly, children, ref, width, containerXstyle, containerClassName, containerStyle, controlXstyle, controlClassName, controlStyle, 'aria-labelledby': ariaLabelledByProp, 'aria-describedby': ariaDescribedByProp, ...restProps }: CheckboxListProps): import("react").JSX.Element;
+export declare function CheckboxList({ label, isLabelHidden, description, isOptional, isRequired, status, value, onChange, changeAction, density, hasDividers, isDisabled, disabledMessage, isReadOnly, children, ref, width, containerXstyle, containerClassName, containerStyle, controlXstyle, controlClassName, controlStyle, 'aria-labelledby': ariaLabelledByProp, 'aria-describedby': ariaDescribedByProp, ...restProps }: CheckboxListProps): import("react").JSX.Element;
 export declare namespace CheckboxList {
     var displayName: string;
 }

package/dist/CheckboxList/CheckboxList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CheckboxList.d.ts","sourceRoot":"","sources":["../../src/CheckboxList/CheckboxList.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAE9C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAarD,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAC7C,mBAAmB,CAAC,cAAc,CAAC,EACnC,UAAU,CACX;IACC,mDAAmD;IACnD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACtC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,UAAkB,EAClB,MAAM,EACN,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,OAAoB,EACpB,WAAmB,EACnB,UAAkB,EAClB,eAAe,EACf,UAAkB,EAClB,QAAQ,EACR,GAAG,EACH,KAAK,EACL,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EAAE,kBAAkB,EACrC,kBAAkB,EAAE,mBAAmB,EACvC,GAAG,SAAS,EACb,EAAE,iBAAiB,+BAwJnB;yBAlLe,YAAY"}
+{"version":3,"file":"CheckboxList.d.ts","sourceRoot":"","sources":["../../src/CheckboxList/CheckboxList.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAE9C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAcrD,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAC7C,mBAAmB,CAAC,cAAc,CAAC,EACnC,UAAU,CACX;IACC,mDAAmD;IACnD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACtC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,OAAoB,EACpB,WAAmB,EACnB,UAAkB,EAClB,eAAe,EACf,UAAkB,EAClB,QAAQ,EACR,GAAG,EACH,KAAK,EACL,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EAAE,kBAAkB,EACrC,kBAAkB,EAAE,mBAAmB,EACvC,GAAG,SAAS,EACb,EAAE,iBAAiB,+BA2KnB;yBAtMe,YAAY"}

package/dist/CheckboxList/CheckboxList.js

@@ -4,7 +4,7 @@
 
 /**
  * @file CheckboxList.tsx
- * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext
+ * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext, requiredGroup
  * @output Exports CheckboxList component, CheckboxListProps
  * @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
  *
@@ -26,6 +26,7 @@ import { mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { joinAriaIDs } from "../utils/inputAria.js";
 import { CheckboxListContext } from "./CheckboxListContext.js";
+import { createRequiredGroup } from "./requiredGroup.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const EMPTY_ARRAY = [];
 /**
@@ -51,6 +52,7 @@ export function CheckboxList({
   isLabelHidden = false,
   description,
   isOptional = false,
+  isRequired = false,
   status,
   value,
   onChange,
@@ -85,6 +87,8 @@ export function CheckboxList({
   const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
+  const requiredGroup = useMemo(() => isRequired ? createRequiredGroup() : undefined, [isRequired]);
+  const observeRequiredGroup = useCallback(container => container != null && requiredGroup != null ? requiredGroup.observe(container) : undefined, [requiredGroup]);
   const [, startTransition] = useTransition();
   const isCollectionMode = value !== undefined;
   const effectiveValue = value ?? EMPTY_ARRAY;
@@ -128,8 +132,9 @@ export function CheckboxList({
     disabledMessageID: showsDisabledMessage ? disabledMessageTooltip.describedBy : undefined,
     isReadOnly,
     isInvalid: status?.type === 'error',
-    loadingValues
-  }), [isCollectionMode, optimisticValue, handleChange, isDisabled, showsDisabledMessage, disabledMessageTooltip.describedBy, isReadOnly, status?.type, loadingValues]);
+    loadingValues,
+    requiredGroup
+  }), [isCollectionMode, optimisticValue, handleChange, isDisabled, showsDisabledMessage, disabledMessageTooltip.describedBy, isReadOnly, status?.type, loadingValues, requiredGroup]);
   return /*#__PURE__*/_jsxs(Field, {
     label: label,
     isLabelHidden: isLabelHidden,
@@ -138,6 +143,7 @@ export function CheckboxList({
     labelID: labelID,
     isGroupLabel: true,
     isOptional: isOptional,
+    isRequired: isRequired,
     descriptionID: description ? descriptionID : undefined,
     isDisabled: isDisabled,
     status: status ? {
@@ -158,7 +164,7 @@ export function CheckboxList({
         ...rest,
         // The disabled-message tooltip anchors here; its handlers are gated
         // internally by isEnabled, so attaching unconditionally is safe.
-        ref: useMergedRefs(ref, disabledMessageTooltip.ref),
+        ref: useMergedRefs(ref, disabledMessageTooltip.ref, observeRequiredGroup),
         ...mergeProps(stylex.props(controlXstyle), controlClassName, controlStyle),
         role: "group"
         // Screen readers announce the whole group as unavailable. Its dimmed

package/dist/CheckboxList/CheckboxListContext.d.ts

@@ -1,3 +1,4 @@
+import type { RequiredGroup } from './requiredGroup.js';
 export interface CheckboxListContextValue {
     value?: string[];
     /**
@@ -36,6 +37,12 @@ export interface CheckboxListContextValue {
      * when idle.
      */
     loadingValues?: ReadonlyArray<string>;
+    /**
+     * Present when the list is `isRequired`. Each item registers its checkbox,
+     * so that while no box is checked the first enabled box carries native
+     * `required`.
+     */
+    requiredGroup?: RequiredGroup;
 }
 export declare const CheckboxListContext: import("react").Context<CheckboxListContextValue | null>;
 //# sourceMappingURL=CheckboxListContext.d.ts.map

package/dist/CheckboxList/CheckboxListContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CheckboxListContext.d.ts","sourceRoot":"","sources":["../../src/CheckboxList/CheckboxListContext.tsx"],"names":[],"mappings":"AAaA,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACvC;AAED,eAAO,MAAM,mBAAmB,0DACiC,CAAC"}
+{"version":3,"file":"CheckboxListContext.d.ts","sourceRoot":"","sources":["../../src/CheckboxList/CheckboxListContext.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAEnD,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,eAAO,MAAM,mBAAmB,0DACiC,CAAC"}

package/dist/CheckboxList/CheckboxListContext.js

@@ -4,7 +4,8 @@
 
 /**
  * @file CheckboxListContext.tsx
- * @input Uses the private layer-scoped context factory
+ * @input Uses the private layer-scoped context factory and the RequiredGroup
+ *   type
  * @output Exports CheckboxListContext for parent-child communication
  * @position Internal context; consumed by CheckboxList.tsx and CheckboxListItem.tsx
  */

package/dist/CheckboxList/CheckboxListItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CheckboxListItem.d.ts","sourceRoot":"","sources":["../../src/CheckboxList/CheckboxListItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAIzD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAS5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAuBvC,MAAM,WAAW,qBAAsB,SAAQ,SAAS,CAAC,aAAa,CAAC;IACrE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;CAChC;AAyCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,YAAY,EAAE,SAAS,EACvB,KAAK,EACL,WAAW,EACX,UAAU,EACV,UAAU,EAAE,cAAsB,EAClC,SAAS,EAAE,aAAqB,EAChC,SAAS,EACT,OAAO,EACP,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EAAE,WAAW,EACpB,KAAK,EACL,GAAG,SAAS,EACb,EAAE,qBAAqB,+BA6IvB;yBA9Je,gBAAgB"}
+{"version":3,"file":"CheckboxListItem.d.ts","sourceRoot":"","sources":["../../src/CheckboxList/CheckboxListItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAkC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAItE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAU5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAuBvC,MAAM,WAAW,qBAAsB,SAAQ,SAAS,CAAC,aAAa,CAAC;IACrE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;CAChC;AAyCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,YAAY,EAAE,SAAS,EACvB,KAAK,EACL,WAAW,EACX,UAAU,EACV,UAAU,EAAE,cAAsB,EAClC,SAAS,EAAE,aAAqB,EAChC,SAAS,EACT,OAAO,EACP,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EAAE,WAAW,EACpB,KAAK,EACL,GAAG,SAAS,EACb,EAAE,qBAAqB,+BAiKvB;yBAlLe,gBAAgB"}

package/dist/CheckboxList/CheckboxListItem.js

@@ -16,7 +16,7 @@
  * - /apps/storybook/stories/CheckboxList.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
-import { use, useId, useRef } from 'react';
+import { use, useCallback, useId, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars } from "../theme/tokens.stylex.js";
@@ -26,6 +26,7 @@ import { ListContext } from "../List/ListContext.js";
 import { CheckboxListContext } from "./CheckboxListContext.js";
 import { ItemDescriptionContext } from "../Item/ItemDescriptionContext.js";
 import { joinAriaIDs } from "../utils/inputAria.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
 import english from "../i18n/generated-english/CheckboxList/CheckboxListItem.generated.js";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -172,6 +173,17 @@ export function CheckboxListItem({
   const checkboxRef = useRef(null);
   const hasRowInteraction = isInteractive || onClickProp != null;
 
+  // A required group decides which box carries native `required` from the
+  // state of every box. A change to this box's state registers it again.
+  const requiredGroup = ctx?.requiredGroup;
+  const isBoxChecked = resolvedChecked === true;
+  const isBoxEnabled = !effectiveDisabled && !effectiveReadOnly;
+  const registerWithRequiredGroup = useCallback(input => input != null && requiredGroup != null ? requiredGroup.register(input, {
+    isChecked: isBoxChecked,
+    isEnabled: isBoxEnabled
+  }) : undefined, [requiredGroup, isBoxChecked, isBoxEnabled]);
+  const checkboxInputRef = useMergedRefs(checkboxRef, registerWithRequiredGroup);
+
   // A read-only checkbox carries aria-readonly, which the row's clickable
   // container treats as a non-interactive target, so a click on it would be
   // delegated straight back to the checkbox without end. Stop that click at
@@ -222,7 +234,7 @@ export function CheckboxListItem({
     className: className,
     style: style,
     startContent: /*#__PURE__*/_jsx(DescribedCheckboxInput, {
-      ref: checkboxRef,
+      ref: checkboxInputRef,
       label: checkboxLabel,
       "aria-labelledby": namesFromVisibleLabel ? labelID : undefined,
       isLabelHidden: true,

package/dist/CheckboxList/requiredGroup.d.ts

@@ -0,0 +1,22 @@
+/** The state of one box that decides which box carries `required`. */
+export interface RequiredGroupBox {
+    isChecked: boolean;
+    /** False for a disabled or read-only box, which the user cannot check. */
+    isEnabled: boolean;
+}
+export interface RequiredGroup {
+    /**
+     * Adds a checkbox with its state and updates `required` on every box.
+     * Returns a function that removes the checkbox, clears its `required`, and
+     * updates the rest. An item registers again when its state changes.
+     */
+    register: (input: HTMLInputElement, box: RequiredGroupBox) => () => void;
+    /**
+     * Updates `required` when the group's options move, for example after a
+     * keyed reorder, which registers no box again. Returns a function that
+     * stops it.
+     */
+    observe: (container: HTMLElement) => () => void;
+}
+export declare function createRequiredGroup(): RequiredGroup;
+//# sourceMappingURL=requiredGroup.d.ts.map

package/dist/CheckboxList/requiredGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requiredGroup.d.ts","sourceRoot":"","sources":["../../src/CheckboxList/requiredGroup.ts"],"names":[],"mappings":"AAkBA,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IACzE;;;;OAIG;IACH,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,KAAK,MAAM,IAAI,CAAC;CACjD;AAUD,wBAAgB,mBAAmB,IAAI,aAAa,CA4BnD"}

package/dist/CheckboxList/requiredGroup.js

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file requiredGroup.ts
+ * @input The checkbox inputs of a required CheckboxList and each box's state;
+ *   Core's shared mutation observer
+ * @output Exports createRequiredGroup, RequiredGroup, and RequiredGroupBox
+ * @position Internal to CheckboxList; CheckboxList creates one for an
+ *   `isRequired` group and CheckboxListItem registers its checkbox with it
+ *
+ * The browser has no required state for a group of checkboxes. While no box
+ * is checked, the first enabled box carries native `required`. The browser
+ * then blocks submit and moves focus to that box with its own message. Once
+ * any box is checked, no box carries `required`.
+ */
+
+import { observeMutations } from "../utils/sharedMutationObserver.js";
+
+/** The state of one box that decides which box carries `required`. */
+
+const MOVE_OPTIONS = {
+  childList: true,
+  subtree: true
+};
+function byDocumentOrder(a, b) {
+  return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+}
+export function createRequiredGroup() {
+  const boxes = new Map();
+  function update() {
+    const ordered = [...boxes.keys()].sort(byDocumentOrder);
+    const isEmpty = ![...boxes.values()].some(box => box.isChecked);
+    const target = isEmpty ? ordered.find(input => boxes.get(input)?.isEnabled === true) : undefined;
+    for (const input of ordered) {
+      input.required = input === target;
+    }
+  }
+  return {
+    register(input, box) {
+      boxes.set(input, box);
+      update();
+      return () => {
+        boxes.delete(input);
+        input.required = false;
+        update();
+      };
+    },
+    observe(container) {
+      return observeMutations(container, MOVE_OPTIONS, update);
+    }
+  };
+}

package/dist/utils/sharedMutationObserver.d.ts

@@ -4,7 +4,8 @@
  * @output Exports observeMutations (one shared observer per set of options)
  *   and observeContent, its text-and-children form
  * @position Internal utility; consumed by useTruncation, hitArea, AppShell's
- *   main-overflow observer and ModalAnnounceProvider's presentation watch. The mutation counterpart of sharedResizeObserver:
+ *   main-overflow observer, ModalAnnounceProvider's presentation watch and
+ *   CheckboxList's required group. The mutation counterpart of sharedResizeObserver:
  *   one observer for every element observed with the same options, so a
  *   repeated cell, row or region does not create one observer per instance.
  */

package/dist/utils/sharedMutationObserver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sharedMutationObserver.d.ts","sourceRoot":"","sources":["../../src/utils/sharedMutationObserver.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,KAAK,gBAAgB,GAAG,MAAM,IAAI,CAAC;AA4DnC;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,IAAI,EACb,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,gBAAgB,GACzB,MAAM,IAAI,CAmCZ;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,gBAAgB,GACzB,MAAM,IAAI,CAEZ"}
+{"version":3,"file":"sharedMutationObserver.d.ts","sourceRoot":"","sources":["../../src/utils/sharedMutationObserver.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,KAAK,gBAAgB,GAAG,MAAM,IAAI,CAAC;AA4DnC;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,IAAI,EACb,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,gBAAgB,GACzB,MAAM,IAAI,CAmCZ;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,gBAAgB,GACzB,MAAM,IAAI,CAEZ"}

package/dist/utils/sharedMutationObserver.js

@@ -8,7 +8,8 @@
  * @output Exports observeMutations (one shared observer per set of options)
  *   and observeContent, its text-and-children form
  * @position Internal utility; consumed by useTruncation, hitArea, AppShell's
- *   main-overflow observer and ModalAnnounceProvider's presentation watch. The mutation counterpart of sharedResizeObserver:
+ *   main-overflow observer, ModalAnnounceProvider's presentation watch and
+ *   CheckboxList's required group. The mutation counterpart of sharedResizeObserver:
  *   one observer for every element observed with the same options, so a
  *   repeated cell, row or region does not create one observer per instance.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.8-canary.d3ec2ef",
+  "version": "0.7.8-canary.e4c81f3",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -870,9 +870,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.8-canary.d3ec2ef",
-    "@astryxdesign/cli": "0.7.8-canary.d3ec2ef",
-    "@astryxdesign/interaction-harness": "0.7.8-canary.d3ec2ef",
+    "@astryxdesign/a11y-spec": "0.7.8-canary.e4c81f3",
+    "@astryxdesign/cli": "0.7.8-canary.e4c81f3",
+    "@astryxdesign/interaction-harness": "0.7.8-canary.e4c81f3",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/CheckboxList/CheckboxList.doc.mjs

@@ -134,6 +134,13 @@ export const docs = {
         'Whether the group is optional. Shows the optional indicator after the group label, unless a surrounding FormLayout already makes fields optional by default.',
       default: 'false',
     },
+    {
+      name: 'isRequired',
+      type: 'boolean',
+      description:
+        'Whether the group needs at least one checked box. Shows the required indicator after the group label by the same rules as every input field. While no box is checked, the browser blocks submit and moves focus to the first box that is neither disabled nor read-only, with its own message. A disabled or read-only group requires nothing. Show your own error text through status. Mutually exclusive with isOptional.',
+      default: 'false',
+    },
     {
       name: 'density',
       type: "'compact' | 'balanced' | 'spacious'",

package/src/CheckboxList/CheckboxList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file CheckboxList.tsx
- * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext
+ * @input Uses React, useId, useOptimistic, useTransition, Field, List, CheckboxListContext, requiredGroup
  * @output Exports CheckboxList component, CheckboxListProps
  * @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
  *
@@ -43,6 +43,7 @@ import {
   CheckboxListContext,
   type CheckboxListContextValue,
 } from './CheckboxListContext';
+import {createRequiredGroup} from './requiredGroup';
 
 const EMPTY_ARRAY: string[] = [];
 
@@ -72,6 +73,17 @@ export interface CheckboxListProps extends Omit<
    * @default false
    */
   isOptional?: boolean;
+  /**
+   * Whether the group needs at least one checked box. Shows the required
+   * indicator after the group label by the same rules as every input field.
+   * While no box is checked, the browser blocks submit and moves focus to
+   * the first box that is neither disabled nor read-only. A disabled or
+   * read-only group requires nothing. Show your own error text through
+   * `status`.
+   * Mutually exclusive with isOptional.
+   * @default false
+   */
+  isRequired?: boolean;
   /**
    * Status indicator for the checkbox group.
    * When set with a message, displays a colored message box below the group.
@@ -161,6 +173,7 @@ export function CheckboxList({
   isLabelHidden = false,
   description,
   isOptional = false,
+  isRequired = false,
   status,
   value,
   onChange,
@@ -193,6 +206,18 @@ export function CheckboxList({
   const descriptionID = useId();
   const statusMessageID = useId();
 
+  const requiredGroup = useMemo(
+    () => (isRequired ? createRequiredGroup() : undefined),
+    [isRequired],
+  );
+  const observeRequiredGroup = useCallback(
+    (container: HTMLDivElement | null) =>
+      container != null && requiredGroup != null
+        ? requiredGroup.observe(container)
+        : undefined,
+    [requiredGroup],
+  );
+
   const [, startTransition] = useTransition();
   const isCollectionMode = value !== undefined;
   const effectiveValue = value ?? EMPTY_ARRAY;
@@ -256,6 +281,7 @@ export function CheckboxList({
       isReadOnly,
       isInvalid: status?.type === 'error',
       loadingValues,
+      requiredGroup,
     }),
     [
       isCollectionMode,
@@ -267,6 +293,7 @@ export function CheckboxList({
       isReadOnly,
       status?.type,
       loadingValues,
+      requiredGroup,
     ],
   );
 
@@ -279,6 +306,7 @@ export function CheckboxList({
       labelID={labelID}
       isGroupLabel
       isOptional={isOptional}
+      isRequired={isRequired}
       descriptionID={description ? descriptionID : undefined}
       isDisabled={isDisabled}
       status={
@@ -302,7 +330,11 @@ export function CheckboxList({
           {...rest}
           // The disabled-message tooltip anchors here; its handlers are gated
           // internally by isEnabled, so attaching unconditionally is safe.
-          ref={useMergedRefs(ref, disabledMessageTooltip.ref)}
+          ref={useMergedRefs(
+            ref,
+            disabledMessageTooltip.ref,
+            observeRequiredGroup,
+          )}
           {...mergeProps(
             stylex.props(controlXstyle),
             controlClassName,

package/src/CheckboxList/CheckboxListContext.tsx

@@ -4,12 +4,14 @@
 
 /**
  * @file CheckboxListContext.tsx
- * @input Uses the private layer-scoped context factory
+ * @input Uses the private layer-scoped context factory and the RequiredGroup
+ *   type
  * @output Exports CheckboxListContext for parent-child communication
  * @position Internal context; consumed by CheckboxList.tsx and CheckboxListItem.tsx
  */
 
 import {createLayerScopedContext} from '../Layer/layerScopedContext';
+import type {RequiredGroup} from './requiredGroup';
 
 export interface CheckboxListContextValue {
   value?: string[];
@@ -49,6 +51,12 @@ export interface CheckboxListContextValue {
    * when idle.
    */
   loadingValues?: ReadonlyArray<string>;
+  /**
+   * Present when the list is `isRequired`. Each item registers its checkbox,
+   * so that while no box is checked the first enabled box carries native
+   * `required`.
+   */
+  requiredGroup?: RequiredGroup;
 }
 
 export const CheckboxListContext =

package/src/CheckboxList/CheckboxListItem.tsx

@@ -17,7 +17,7 @@
  * - /packages/cli/assets/templates/blocks/components/CheckboxList/ (showcase blocks)
  */
 
-import {use, useId, useRef, type ReactNode} from 'react';
+import {use, useCallback, useId, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
@@ -30,6 +30,7 @@ import {ListContext} from '../List/ListContext';
 import {CheckboxListContext} from './CheckboxListContext';
 import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';
 import {joinAriaIDs} from '../utils/inputAria';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {ItemAlign} from '../Item';
 import {
   registerEnglishFallback,
@@ -284,6 +285,26 @@ export function CheckboxListItem({
   const checkboxRef = useRef<HTMLInputElement | null>(null);
   const hasRowInteraction = isInteractive || onClickProp != null;
 
+  // A required group decides which box carries native `required` from the
+  // state of every box. A change to this box's state registers it again.
+  const requiredGroup = ctx?.requiredGroup;
+  const isBoxChecked = resolvedChecked === true;
+  const isBoxEnabled = !effectiveDisabled && !effectiveReadOnly;
+  const registerWithRequiredGroup = useCallback(
+    (input: HTMLInputElement | null) =>
+      input != null && requiredGroup != null
+        ? requiredGroup.register(input, {
+            isChecked: isBoxChecked,
+            isEnabled: isBoxEnabled,
+          })
+        : undefined,
+    [requiredGroup, isBoxChecked, isBoxEnabled],
+  );
+  const checkboxInputRef = useMergedRefs(
+    checkboxRef,
+    registerWithRequiredGroup,
+  );
+
   // A read-only checkbox carries aria-readonly, which the row's clickable
   // container treats as a non-interactive target, so a click on it would be
   // delegated straight back to the checkbox without end. Stop that click at
@@ -349,7 +370,7 @@ export function CheckboxListItem({
       style={style}
       startContent={
         <DescribedCheckboxInput
-          ref={checkboxRef}
+          ref={checkboxInputRef}
           label={checkboxLabel}
           aria-labelledby={namesFromVisibleLabel ? labelID : undefined}
           isLabelHidden

package/src/CheckboxList/requiredGroup.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file requiredGroup.ts
+ * @input The checkbox inputs of a required CheckboxList and each box's state;
+ *   Core's shared mutation observer
+ * @output Exports createRequiredGroup, RequiredGroup, and RequiredGroupBox
+ * @position Internal to CheckboxList; CheckboxList creates one for an
+ *   `isRequired` group and CheckboxListItem registers its checkbox with it
+ *
+ * The browser has no required state for a group of checkboxes. While no box
+ * is checked, the first enabled box carries native `required`. The browser
+ * then blocks submit and moves focus to that box with its own message. Once
+ * any box is checked, no box carries `required`.
+ */
+
+import {observeMutations} from '../utils/sharedMutationObserver';
+
+/** The state of one box that decides which box carries `required`. */
+export interface RequiredGroupBox {
+  isChecked: boolean;
+  /** False for a disabled or read-only box, which the user cannot check. */
+  isEnabled: boolean;
+}
+
+export interface RequiredGroup {
+  /**
+   * Adds a checkbox with its state and updates `required` on every box.
+   * Returns a function that removes the checkbox, clears its `required`, and
+   * updates the rest. An item registers again when its state changes.
+   */
+  register: (input: HTMLInputElement, box: RequiredGroupBox) => () => void;
+  /**
+   * Updates `required` when the group's options move, for example after a
+   * keyed reorder, which registers no box again. Returns a function that
+   * stops it.
+   */
+  observe: (container: HTMLElement) => () => void;
+}
+
+const MOVE_OPTIONS: MutationObserverInit = {childList: true, subtree: true};
+
+function byDocumentOrder(a: HTMLInputElement, b: HTMLInputElement): number {
+  return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING
+    ? -1
+    : 1;
+}
+
+export function createRequiredGroup(): RequiredGroup {
+  const boxes = new Map<HTMLInputElement, RequiredGroupBox>();
+
+  function update() {
+    const ordered = [...boxes.keys()].sort(byDocumentOrder);
+    const isEmpty = ![...boxes.values()].some(box => box.isChecked);
+    const target = isEmpty
+      ? ordered.find(input => boxes.get(input)?.isEnabled === true)
+      : undefined;
+    for (const input of ordered) {
+      input.required = input === target;
+    }
+  }
+
+  return {
+    register(input, box) {
+      boxes.set(input, box);
+      update();
+      return () => {
+        boxes.delete(input);
+        input.required = false;
+        update();
+      };
+    },
+    observe(container) {
+      return observeMutations(container, MOVE_OPTIONS, update);
+    },
+  };
+}

package/src/utils/sharedMutationObserver.ts

@@ -8,7 +8,8 @@
  * @output Exports observeMutations (one shared observer per set of options)
  *   and observeContent, its text-and-children form
  * @position Internal utility; consumed by useTruncation, hitArea, AppShell's
- *   main-overflow observer and ModalAnnounceProvider's presentation watch. The mutation counterpart of sharedResizeObserver:
+ *   main-overflow observer, ModalAnnounceProvider's presentation watch and
+ *   CheckboxList's required group. The mutation counterpart of sharedResizeObserver:
  *   one observer for every element observed with the same options, so a
  *   repeated cell, row or region does not create one observer per instance.
  */