@oneli8/react 1.0.0-beta.2 → 1.0.0-beta.4

package/src/index.d.ts

@@ -1,4 +1,167 @@
-export * from "./Button.js";
-export * from "./IconButton.js";
-export * from "./Link.js";
-export * from "./Icon.js";
+import type {
+  ComponentPropsWithoutRef, ForwardRefExoticComponent, ReactElement, ReactNode, RefAttributes,
+} from 'react';
+import type { Ol8IconName } from './foundations/icons.generated.js';
+
+export type { Ol8IconName };
+export { OL8_ICONS, OL8_ICON_VIEWBOX } from './foundations/icons.generated.js';
+
+export type Ol8Variant = 'primary' | 'secondary' | 'quiet' | 'destructive';
+export type Ol8Size = 'compact' | 'standard' | 'comfortable' | 'large';
+export type Ol8Material = 'regular' | 'gem';
+export type Ol8SelectionKind = 'checkbox' | 'radio' | 'switch';
+export type Ol8SelectionSize = 'compact' | 'comfortable';
+export type Ol8Selection =
+  | 'unchecked' | 'checked' | 'mixed'
+  | 'unselected' | 'selected'
+  | 'off' | 'on';
+export type Ol8OptionSize = 'standard' | 'large';
+export type Ol8Aggregate = 'none' | 'some' | 'all';
+
+export declare const OL8_BUTTON_VARIANTS: readonly Ol8Variant[];
+export declare const OL8_BUTTON_SIZES: readonly Ol8Size[];
+export declare const OL8_MATERIALS: readonly Ol8Material[];
+/** Gem is approved for Primary and Secondary only (Figma 100:3). */
+export declare const GEM_VARIANTS: readonly ('primary' | 'secondary')[];
+export declare const OL8_ICON_BUTTON_VARIANTS: readonly Ol8Variant[];
+export declare const OL8_ICON_BUTTON_SIZES: readonly Ol8Size[];
+export declare const OL8_ICON_BUTTON_SHAPES: readonly ('rounded' | 'circle')[];
+export declare const OL8_SELECTION_KINDS: readonly Ol8SelectionKind[];
+export declare const OL8_SELECTION_SIZES: readonly Ol8SelectionSize[];
+export declare const OL8_SELECTION_STATES: Record<Ol8SelectionKind, readonly Ol8Selection[]>;
+export declare const OL8_CHOICE_KINDS: readonly Ol8SelectionKind[];
+export declare const OL8_CHOICE_SIZES: readonly Ol8Size[];
+export declare const OL8_OPTION_SIZES: readonly Ol8OptionSize[];
+export declare const OL8_AGGREGATE: readonly Ol8Aggregate[];
+
+export declare function isOl8IconName(name: string): name is Ol8IconName;
+export declare function iconSizeForButton(size: Ol8Size): 18 | 24;
+export declare function artworkSizeForIconButton(size: Ol8Size): 18 | 24;
+export declare function indicatorSizeFor(size: Ol8Size): Ol8SelectionSize;
+export declare function selectionStateFor(
+  kind: Ol8SelectionKind, state?: { checked?: boolean; mixed?: boolean }
+): Ol8Selection;
+export declare function computeAggregate(
+  children: Iterable<{ checked?: boolean; disabled?: boolean }>
+): Ol8Aggregate;
+
+/** ATOM. Decorative unless given a label; the parent control carries meaning. */
+export interface IconProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children'> {
+  name: Ol8IconName;
+  size?: number;
+  /** Promotes the icon to role="img". Omit for decorative. */
+  label?: string;
+}
+export declare function Icon(props: IconProps): ReactElement;
+
+/** ATOM. Presentational only; the native input in ChoiceItem owns state and focus. */
+export interface SelectionIndicatorProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children'> {
+  kind: Ol8SelectionKind;
+  selection?: Ol8Selection;
+  size?: Ol8SelectionSize;
+  disabled?: boolean;
+  /** Switch thumb artwork only. */
+  icon?: Ol8IconName;
+}
+export declare function SelectionIndicator(props: SelectionIndicatorProps): ReactElement;
+
+/** MOLECULE. States are CSS, never classes. */
+export interface ButtonProps extends Omit<ComponentPropsWithoutRef<'button'>, 'type'> {
+  children?: ReactNode;
+  variant?: Ol8Variant;
+  size?: Ol8Size;
+  /** Throws for quiet and destructive: Gem has no approved treatment there. */
+  material?: Ol8Material;
+  leadingIcon?: Ol8IconName;
+  trailingIcon?: Ol8IconName;
+  loading?: boolean;
+  pressed?: boolean;
+  fullWidth?: boolean;
+  /** Renders an anchor instead of a button. */
+  href?: string;
+  type?: 'button' | 'submit' | 'reset';
+  /** Keeps the leading icon beside the spinner, Figma's literal reading. */
+  keepLeadingIconWhileLoading?: boolean;
+}
+export declare const Button: ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLElement>>;
+
+/** MOLECULE. An accessible name is mandatory and enforced at runtime. */
+export interface IconButtonProps extends Omit<ComponentPropsWithoutRef<'button'>, 'type'> {
+  icon: Ol8IconName;
+  accessibleName: string;
+  variant?: Ol8Variant;
+  size?: Ol8Size;
+  shape?: 'rounded' | 'circle';
+  material?: Ol8Material;
+  loading?: boolean;
+  pressed?: boolean;
+  type?: 'button' | 'submit' | 'reset';
+}
+export declare const IconButton: ForwardRefExoticComponent<IconButtonProps & RefAttributes<HTMLButtonElement>>;
+
+/** MOLECULE. A real input owns state, focus and form participation. */
+export interface ChoiceItemProps extends Omit<ComponentPropsWithoutRef<'input'>, 'size' | 'type' | 'children'> {
+  kind: Ol8SelectionKind;
+  children?: ReactNode;
+  size?: Ol8Size;
+  /** Checkbox only. Sets the JavaScript-only indeterminate flag. */
+  mixed?: boolean;
+  invalid?: boolean;
+  /** Associated with aria-describedby, outside the accessible name. */
+  description?: ReactNode;
+  material?: Ol8Material;
+}
+export declare const ChoiceItem: ForwardRefExoticComponent<ChoiceItemProps & RefAttributes<HTMLInputElement>>;
+
+/** MOLECULE. Never focusable; a listbox moves a virtual cursor instead. */
+export interface SelectionOptionProps extends Omit<ComponentPropsWithoutRef<'li'>, 'children'> {
+  children?: ReactNode;
+  value?: string;
+  size?: Ol8OptionSize;
+  selected?: boolean;
+  active?: boolean;
+  disabled?: boolean;
+  description?: ReactNode;
+  leadingIcon?: Ol8IconName;
+  focusRing?: boolean;
+}
+export declare function SelectionOption(props: SelectionOptionProps): ReactElement;
+
+export interface Ol8GroupOption {
+  label: ReactNode;
+  value: string;
+  description?: ReactNode;
+  disabled?: boolean;
+  /** CheckboxGroup only; radios take a single group value. */
+  checked?: boolean;
+}
+interface Ol8GroupShell {
+  legend: ReactNode;
+  instruction?: ReactNode;
+  message?: ReactNode;
+  invalid?: boolean;
+  disabled?: boolean;
+  size?: Ol8Size;
+  material?: Ol8Material;
+  id?: string;
+  className?: string;
+}
+/** ORGANISM. Native radios already give roving focus and single selection. */
+export interface RadioGroupProps extends Ol8GroupShell {
+  name: string;
+  options: Ol8GroupOption[];
+  value?: string;
+  onChange?: (value: string) => void;
+  orientation?: 'vertical' | 'horizontal';
+  required?: boolean;
+}
+export declare function RadioGroup(props: RadioGroupProps): ReactElement;
+
+/** ORGANISM. Aggregate is computed; Mixed is never a third preference. */
+export interface CheckboxGroupProps extends Ol8GroupShell {
+  parentLabel: ReactNode;
+  options: Ol8GroupOption[];
+  name?: string;
+  onChange?: (state: Record<string, boolean>) => void;
+}
+export declare function CheckboxGroup(props: CheckboxGroupProps): ReactElement;

package/src/index.js

@@ -1,4 +1,9 @@
-export {Button} from "./Button.js";
-export {IconButton} from "./IconButton.js";
-export {Link} from "./Link.js";
-export {Icon,iconNames} from "./Icon.js";
+export { Icon } from './atoms/Icon.js';
+export { SelectionIndicator } from './atoms/SelectionIndicator.js';
+export { Button } from './molecules/Button.js';
+export { IconButton } from './molecules/IconButton.js';
+export { ChoiceItem } from './molecules/ChoiceItem.js';
+export { SelectionOption } from './molecules/SelectionOption.js';
+export { RadioGroup, CheckboxGroup } from './organisms/ChoiceGroup.js';
+export * from './foundations/geometry.js';
+export { OL8_ICONS, OL8_ICON_VIEWBOX } from './foundations/icons.generated.js';

package/src/molecules/Button.js

@@ -1,21 +1,50 @@
-import {createElement,forwardRef} from "react";
-import {BusyIndicator} from "../atoms/BusyIndicator.js";
-import {ButtonControl} from "../atoms/ButtonControl.js";
-import {IconFrame,iconFrameSizeForControl} from "../atoms/IconFrame.js";
+import { createElement, forwardRef } from 'react';
+import { Icon, IconGlyph } from '../atoms/Icon.js';
+import { assertVariant, iconSizeForButton } from '../foundations/geometry.js';
 
-const motions=new Set(["none","rotate","forward","backward"]);
+/**
+ * MOLECULE. Figma's six States are visual evidence for review, not classes.
+ * In code they are :hover, :active, :focus-visible, [disabled] and
+ * [data-ol8-loading]. There is no .ol8-btn--hover.
+ */
+export const Button = forwardRef(function Button({
+  children, variant = 'primary', size = 'standard', material = 'regular',
+  leadingIcon, trailingIcon, loading = false, disabled = false, pressed,
+  fullWidth = false, href, type = 'button', className = '',
+  keepLeadingIconWhileLoading = false, ...rest
+}, ref) {
+  assertVariant(variant, size, material);
+  const isLink = typeof href === 'string';
+  const inert = disabled || loading;
+  const iconSize = iconSizeForButton(size);
 
-export const Button=forwardRef(function Button({
-  children,variant="primary",size="comfortable",material="regular",loading=false,disabled=false,pressed,
-  leadingIcon,trailingIcon,iconMotion="none",fullWidth=false,className="",type="button",onClick,...rest
-},ref){
-  const resolvedMotion=motions.has(iconMotion)?iconMotion:"none";
-  const iconSize=iconFrameSizeForControl(size);
-  const content=[];
-  if(leadingIcon)content.push(createElement(IconFrame,{className:"ol8-Button__icon",size:iconSize,key:"leading"},leadingIcon));
-  if(loading)content.push(createElement(BusyIndicator,{className:"ol8-Button__status",key:"status"}));
-  content.push(createElement("span",{className:"ol8-Button__label",key:"label"},children));
-  if(trailingIcon)content.push(createElement(IconFrame,{className:"ol8-Button__icon",size:iconSize,key:"trailing"},trailingIcon));
-  return createElement(ButtonControl,{...rest,ref,type,disabled,loading,pressed,variant,size,material,className,baseClass:"ol8-Button",onClick,
-    "data-ol8-icon-motion":resolvedMotion,"data-ol8-full-width":fullWidth||undefined},content);
+  // The spinner takes the leading slot by default, so the control never shows
+  // two competing leading glyphs and its width stays predictable.
+  const content = [];
+  if (loading) {
+    if (keepLeadingIconWhileLoading && leadingIcon) {
+      content.push(createElement(Icon, { key: 'leading', name: leadingIcon, size: iconSize }));
+    }
+    content.push(createElement('span', { key: 'spinner', className: 'ol8-btn__spinner ol8-icon', 'aria-hidden': 'true' },
+      createElement(IconGlyph, { name: 'loading' })));
+  } else if (leadingIcon) {
+    content.push(createElement(Icon, { key: 'leading', name: leadingIcon, size: iconSize }));
+  }
+  content.push(createElement('span', { key: 'label', className: 'ol8-btn__label' }, children));
+  if (trailingIcon) content.push(createElement(Icon, { key: 'trailing', name: trailingIcon, size: iconSize }));
+
+  const shared = {
+    ...rest, ref,
+    className: `ol8-btn ol8-btn--${variant}${className ? ` ${className}` : ''}`,
+    'data-ol8-size': size,
+    ...(loading ? { 'data-ol8-loading': 'true', 'aria-busy': 'true' } : {}),
+    ...(pressed !== undefined ? { 'aria-pressed': String(pressed) } : {}),
+    ...(fullWidth ? { 'data-ol8-fullwidth': 'true' } : {}),
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+    ...(loading && keepLeadingIconWhileLoading ? { 'data-ol8-loading-keep-icon': 'true' } : {}),
+  };
+  // A link cannot be natively disabled, so it leaves the tab order instead.
+  return isLink
+    ? createElement('a', { ...shared, ...(inert ? { role: 'button', 'aria-disabled': 'true', tabIndex: -1 } : { href }) }, content)
+    : createElement('button', { ...shared, type, ...(inert ? { disabled: true } : {}) }, content);
 });

package/src/molecules/ChoiceItem.js

@@ -0,0 +1,55 @@
+import { createElement, forwardRef, useId } from 'react';
+import { SelectionIndicator } from '../atoms/SelectionIndicator.js';
+import { OL8_CHOICE_KINDS, OL8_CHOICE_SIZES, indicatorSizeFor, selectionStateFor } from '../foundations/geometry.js';
+
+/**
+ * MOLECULE. A real input owns state, focus and form participation; this never
+ * reimplements toggling. `indeterminate` is the one thing markup cannot express,
+ * so React sets it through a ref callback rather than an attribute.
+ */
+export const ChoiceItem = forwardRef(function ChoiceItem({
+  kind, children, size = 'standard', checked, defaultChecked, mixed = false,
+  disabled = false, invalid = false, description, name, value, required = false,
+  material = 'regular', id, className = '', onChange, ...rest
+}, ref) {
+  if (!OL8_CHOICE_KINDS.includes(kind)) throw new Error(`[ol8] unknown choice kind "${kind}"`);
+  if (!OL8_CHOICE_SIZES.includes(size)) throw new Error(`[ol8] unknown choice size "${size}"`);
+  const auto = useId();
+  const rowId = id ?? `ol8-choice-${auto}`;
+  const descId = description ? `${rowId}-desc` : undefined;
+  const isOn = checked ?? defaultChecked ?? false;
+
+  return createElement('label', {
+    className: `ol8-choice ol8-choice--${kind}${className ? ` ${className}` : ''}`,
+    htmlFor: rowId,
+    'data-ol8-size': size,
+    'data-ol8-kind': kind,
+    'data-ol8-availability': disabled ? 'disabled' : 'enabled',
+    ...(invalid ? { 'data-ol8-validity': 'invalid' } : {}),
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+  }, [
+    createElement('input', {
+      key: 'input', ...rest,
+      ref: (node) => {
+        if (node) node.indeterminate = kind === 'checkbox' && mixed;
+        if (typeof ref === 'function') ref(node); else if (ref) ref.current = node;
+      },
+      type: kind === 'radio' ? 'radio' : 'checkbox',
+      className: 'ol8-choice__input', id: rowId, name, value, required, disabled, onChange,
+      ...(checked !== undefined ? { checked } : defaultChecked !== undefined ? { defaultChecked } : {}),
+      ...(descId ? { 'aria-describedby': descId } : {}),
+      ...(invalid ? { 'aria-invalid': 'true' } : {}),
+      ...(kind === 'switch' ? { role: 'switch' } : {}),
+    }),
+    createElement('span', { key: 'surface', className: 'ol8-choice__surface', 'aria-hidden': 'true' }),
+    createElement('span', { key: 'indicator', className: 'ol8-choice__indicator' },
+      createElement(SelectionIndicator, {
+        kind, size: indicatorSizeFor(size), disabled,
+        selection: selectionStateFor(kind, { checked: isOn, mixed }),
+      })),
+    createElement('span', { key: 'text', className: 'ol8-choice__text' }, [
+      createElement('span', { key: 'label', className: 'ol8-choice__label' }, children),
+      description ? createElement('span', { key: 'desc', className: 'ol8-choice__description', id: descId }, description) : null,
+    ]),
+  ]);
+});

package/src/molecules/IconButton.js

@@ -1,18 +1,33 @@
-import {createElement,forwardRef} from "react";
-import {BusyIndicator} from "../atoms/BusyIndicator.js";
-import {ButtonControl} from "../atoms/ButtonControl.js";
-import {IconFrame,iconFrameSizeForControl} from "../atoms/IconFrame.js";
+import { createElement, forwardRef } from 'react';
+import { Icon } from '../atoms/Icon.js';
+import { assertVariant, artworkSizeForIconButton, OL8_ICON_BUTTON_SHAPES } from '../foundations/geometry.js';
 
-const shapes=new Set(["rounded","circle"]);
-const motions=new Set(["system","none"]);
-
-export const IconButton=forwardRef(function IconButton({icon,accessibleName,variant="quiet",size="comfortable",shape="rounded",material="regular",loading=false,disabled=false,pressed,motion="system",className="",...rest},ref){
-  if(typeof accessibleName!=="string"||!accessibleName.trim())throw new TypeError("IconButton requires a non-empty accessibleName.");
-  if(!icon&&!loading)throw new TypeError("IconButton requires icon artwork when it is not loading.");
-  const iconSize=iconFrameSizeForControl(size,{large:"large"});
-  const content=loading?createElement(BusyIndicator,{className:"ol8-IconButton__status"}):createElement(IconFrame,{className:"ol8-IconButton__icon",size:iconSize},icon);
-  return createElement(ButtonControl,{...rest,ref,baseClass:"ol8-IconButton",variant,size,material,loading,disabled,pressed,className,"aria-label":accessibleName,
-    "data-ol8-shape":shapes.has(shape)?shape:"rounded","data-ol8-motion":motions.has(motion)?motion:"system"},
-    createElement("span",{className:"ol8-IconButton__surface","aria-hidden":"true"},content)
-  );
+/**
+ * MOLECULE. Two boxes deliberately: the outer element is the protected target
+ * and the inner surface is the visible box, so a Compact control still keeps a
+ * 48px hit area. An accessible name is mandatory and enforced here.
+ */
+export const IconButton = forwardRef(function IconButton({
+  icon, accessibleName, variant = 'primary', size = 'standard', shape = 'rounded',
+  material = 'regular', loading = false, disabled = false, pressed,
+  type = 'button', className = '', ...rest
+}, ref) {
+  assertVariant(variant, size, material);
+  if (!OL8_ICON_BUTTON_SHAPES.includes(shape)) throw new Error(`[ol8] unknown icon button shape "${shape}"`);
+  if (typeof accessibleName !== 'string' || accessibleName.trim() === '') {
+    throw new Error('[ol8] IconButton requires accessibleName. An icon alone announces nothing.');
+  }
+  const inert = disabled || loading;
+  return createElement('button', {
+    ...rest, ref, type,
+    className: `ol8-icon-btn ol8-icon-btn--${variant}${className ? ` ${className}` : ''}`,
+    'data-ol8-size': size,
+    'data-ol8-shape': shape,
+    'aria-label': accessibleName,
+    ...(inert ? { disabled: true } : {}),
+    ...(loading ? { 'data-ol8-loading': 'true', 'aria-busy': 'true' } : {}),
+    ...(pressed !== undefined ? { 'aria-pressed': String(pressed) } : {}),
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+  }, createElement('span', { className: 'ol8-icon-btn__surface' },
+    createElement(Icon, { name: loading ? 'loading' : icon, size: artworkSizeForIconButton(size) })));
 });

package/src/molecules/SelectionOption.js

@@ -0,0 +1,41 @@
+import { createElement, useId } from 'react';
+import { Icon } from '../atoms/Icon.js';
+import { OL8_OPTION_SIZES } from '../foundations/geometry.js';
+
+/**
+ * MOLECULE. Never focusable. A listbox moves a virtual cursor with
+ * aria-activedescendant while real focus stays on the combobox input, so this
+ * carries no tabIndex. Options cannot be natively disabled, hence aria-disabled.
+ */
+export function SelectionOption({
+  children, value, size = 'standard', selected = false, active = false,
+  disabled = false, description, leadingIcon, id, focusRing = false, className = '', ...rest
+}) {
+  if (!OL8_OPTION_SIZES.includes(size)) throw new Error(`[ol8] unknown option size "${size}"`);
+  const auto = useId();
+  const optionId = id ?? `ol8-option-${auto}`;
+  const labelId = `${optionId}-label`;
+  const descId = description ? `${optionId}-desc` : undefined;
+  return createElement('li', {
+    ...rest,
+    className: `ol8-option${className ? ` ${className}` : ''}`,
+    role: 'option', id: optionId,
+    'data-ol8-size': size,
+    'aria-selected': String(selected),
+    'aria-labelledby': labelId,
+    ...(descId ? { 'aria-describedby': descId } : {}),
+    ...(disabled ? { 'aria-disabled': 'true' } : {}),
+    ...(active ? { 'data-ol8-active': 'true' } : {}),
+    ...(focusRing ? { 'data-ol8-focus-ring': 'true' } : {}),
+    ...(value !== undefined ? { 'data-ol8-value': value } : {}),
+  }, createElement('span', { className: 'ol8-option__surface' }, [
+    leadingIcon ? createElement('span', { key: 'lead', className: 'ol8-option__leading' },
+      createElement(Icon, { name: leadingIcon, size: 18 })) : null,
+    createElement('span', { key: 'text', className: 'ol8-option__text' }, [
+      createElement('span', { key: 'l', className: 'ol8-option__label', id: labelId }, children),
+      description ? createElement('span', { key: 'd', className: 'ol8-option__description', id: descId }, description) : null,
+    ]),
+    selected ? createElement('span', { key: 'check', className: 'ol8-option__selected' },
+      createElement(Icon, { name: 'check', size: 18 })) : null,
+  ]));
+}

package/src/organisms/ChoiceGroup.js

@@ -0,0 +1,78 @@
+import { createElement, useId, useMemo, useState } from 'react';
+import { ChoiceItem } from '../molecules/ChoiceItem.js';
+import { computeAggregate } from '../foundations/geometry.js';
+
+function Shell({ kind, legend, instruction, message, invalid, orientation = 'vertical', id, className, children }) {
+  return createElement('fieldset', {
+    className: `ol8-choice-group ol8-choice-group--${kind}${className ? ` ${className}` : ''}`,
+    id,
+    ...(orientation === 'horizontal' ? { 'data-ol8-orientation': 'horizontal' } : {}),
+    ...(invalid ? { 'data-ol8-validity': 'invalid' } : {}),
+  }, [
+    createElement('legend', { key: 'legend', className: 'ol8-choice-group__legend' }, legend),
+    instruction ? createElement('p', { key: 'i', className: 'ol8-choice-group__instruction' }, instruction) : null,
+    children,
+    message ? createElement('p', { key: 'm', className: 'ol8-choice-group__message', ...(invalid ? { role: 'alert' } : {}) }, message) : null,
+  ]);
+}
+
+/**
+ * ORGANISM. Native radios already give roving focus, single selection and form
+ * submission, so this only builds the shell around them.
+ */
+export function RadioGroup({
+  legend, name, options, value, onChange, instruction, message, invalid = false,
+  disabled = false, orientation = 'vertical', size = 'standard', material = 'regular',
+  required = false, id, className = '',
+}) {
+  if (!legend) throw new Error('[ol8] a radio group requires a legend');
+  if (!name) throw new Error('[ol8] a radio group requires a name — it is what makes it a group');
+  if (!options?.length) throw new Error('[ol8] a radio group requires options');
+  return createElement(Shell, { kind: 'radio', legend, instruction, message, invalid, orientation, id, className },
+    createElement('div', { key: 'options', className: 'ol8-choice-group__options' },
+      options.map((o) => createElement(ChoiceItem, {
+        key: o.value, kind: 'radio', name, value: o.value, size, material, required, invalid,
+        description: o.description, disabled: disabled || !!o.disabled,
+        checked: value !== undefined ? o.value === value : undefined,
+        onChange: onChange ? () => onChange(o.value) : undefined,
+      }, o.label))));
+}
+
+/**
+ * ORGANISM. Aggregate None/Some/All is computed from the children; Mixed is
+ * never a third preference a user can choose. Toggling the parent resolves the
+ * whole subtree rather than cycling back through Mixed.
+ */
+export function CheckboxGroup({
+  legend, parentLabel, options, name, onChange, instruction, message, invalid = false,
+  disabled = false, size = 'standard', material = 'regular', id, className = '',
+}) {
+  if (!legend) throw new Error('[ol8] a checkbox group requires a legend');
+  if (!parentLabel) throw new Error('[ol8] a checkbox hierarchy requires a parent label');
+  if (!options?.length) throw new Error('[ol8] a checkbox group requires options');
+  const auto = useId();
+  const [state, setState] = useState(() => Object.fromEntries(options.map((o) => [o.value, !!o.checked])));
+  const aggregate = useMemo(
+    () => computeAggregate(options.map((o) => ({ checked: state[o.value], disabled: disabled || !!o.disabled }))),
+    [state, options, disabled]
+  );
+  const setAll = (next) => {
+    const updated = Object.fromEntries(options.map((o) => [o.value, (disabled || o.disabled) ? state[o.value] : next]));
+    setState(updated); onChange?.(updated);
+  };
+  return createElement(Shell, { kind: 'checkbox', legend, instruction, message, invalid, id: id ?? `ol8-group-${auto}`, className }, [
+    createElement(ChoiceItem, {
+      key: 'parent', kind: 'checkbox', size, material, disabled, invalid,
+      className: 'ol8-choice-group__parent',
+      checked: aggregate === 'all', mixed: aggregate === 'some',
+      onChange: () => setAll(aggregate !== 'all'),
+    }, parentLabel),
+    createElement('div', { key: 'children', className: 'ol8-choice-group__children' },
+      options.map((o) => createElement(ChoiceItem, {
+        key: o.value, kind: 'checkbox', name, value: o.value, size, material,
+        description: o.description, disabled: disabled || !!o.disabled,
+        className: 'ol8-choice-group__child', checked: !!state[o.value],
+        onChange: () => { const u = { ...state, [o.value]: !state[o.value] }; setState(u); onChange?.(u); },
+      }, o.label))),
+  ]);
+}