@arun-dev/headless 4.1.0 → 4.3.0

package/dist/radio-group/index.d.ts

@@ -0,0 +1,128 @@
+import * as react from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+/**
+ * RadioGroup.Root's own props. Everything else — `id`, `className`, `children`,
+ * `aria-*`, `data-*`, event handlers — comes from React's own `<div>` props.
+ *
+ * `aria-labelledby` in particular is how a group gets its accessible name, pointing at
+ * the visible caption. A `<fieldset>` with a `<legend>` does the same through `render`.
+ */
+type RadioGroupRootOwnProps = {
+    /**
+     * Controlled value — the `value` of the selected item, or `null` for none. Provide
+     * `onValueChange` alongside it.
+     *
+     * Never `undefined` once mounted. The mode is latched at mount, so an `undefined`
+     * first render makes the group uncontrolled for good. Use `null` for "nothing
+     * selected" — `value={x ?? null}`.
+     */
+    value?: string | null;
+    /** Initial value when uncontrolled. Read once, at mount. */
+    defaultValue?: string | null;
+    /**
+     * Called with the value being moved to, in both controlled and uncontrolled modes.
+     * A user can only move to a value; `null` arrives only from `form.reset()` returning
+     * a group that mounted with nothing selected.
+     */
+    onValueChange?: (value: string | null) => void;
+    /**
+     * The name every radio in the group shares, and submits under.
+     *
+     * The platform groups radios by name — that is what makes arrow keys move between
+     * them and keeps one checked at a time — so one is generated when this is omitted.
+     * A generated name still submits: pass your own when the group is inside a form.
+     */
+    name?: string;
+    /** Disables every radio in the group. */
+    disabled?: boolean;
+    /** Blocks form submission until a radio is selected, via the platform's validation. */
+    required?: boolean;
+    /** Associates the radios with a `<form>` by id, when the group is rendered outside it. */
+    form?: string;
+    /**
+     * Component to render instead of the default `<div>` — a `<fieldset>`, say. Props,
+     * className, event handlers and ref are merged onto it.
+     */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type RadioGroupRootProps = RadioGroupRootOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof RadioGroupRootOwnProps>;
+/**
+ * A set of radios, of which at most one is selected.
+ *
+ * The radios are native `<input type="radio">` elements — the native element passes all
+ * three of decision 7's tests, so nothing here rebuilds what the platform already does.
+ * Arrow keys move the selection, Tab enters the group at the checked radio, `required`
+ * blocks submission and the form submits the checked value, all without JavaScript.
+ *
+ * What the group adds is the one thing the platform leaves to the page: a single value
+ * in React. It owns that value, and every radio derives `checked` from it.
+ *
+ * Inside a form, `form.reset()` returns the group to the value it mounted with. The
+ * platform resets the inputs by itself, but React's value would not follow — the same
+ * seam `useFormReset` closes for Checkbox and Switch, closed here for a group.
+ */
+declare function RadioGroupRoot({ value: valueProp, defaultValue, onValueChange, name: nameProp, disabled, required, form, className, children, render, ...rest }: RadioGroupRootProps): react.JSX.Element;
+
+/**
+ * RadioGroup.Item's own props. Everything else — `id`, `className`, `aria-*`, `data-*`,
+ * event handlers — comes from React's own `<input>` props.
+ *
+ * `name`, `checked`, `defaultChecked`, `required` and `form` belong to the group and are
+ * not accepted here: a radio's checkedness is the group's value, not its own. `type` is
+ * always `radio`, and `children` is left out because an `<input>` cannot hold any.
+ */
+type RadioGroupItemOwnProps = {
+    /** The group's value when this radio is selected, and what the form submits for it. */
+    value: string;
+    /** Disables this radio alone. A disabled group disables it regardless. */
+    disabled?: boolean;
+    /** Element to render instead of the default `<input type="radio">`. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
+};
+type RadioGroupItemProps = RadioGroupItemOwnProps & Omit<ComponentPropsWithRef<'input'>, keyof RadioGroupItemOwnProps | 'type' | 'name' | 'checked' | 'defaultChecked' | 'required' | 'form' | 'children'>;
+/**
+ * One radio — a native `<input type="radio">`.
+ *
+ * Void, so it has no parts: there is no indicator to hold, and the dot is drawn by CSS
+ * off `:checked` or the `data-*` attributes. Decision 11 — one element, one component.
+ *
+ * It has no accessible name of its own — wrap it in a `<label>`, pair it with one by
+ * `id`, or pass `aria-label`. A wrapping label names it natively, but
+ * jsx-a11y/label-has-associated-control cannot see through this component to the input,
+ * so under that rule pair it by `id` too.
+ */
+declare function RadioGroupItem({ value, disabled: disabledProp, className, render, ...rest }: RadioGroupItemProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { RadioGroupItem as Item, RadioGroupRoot as Root };
+}
+
+/**
+ * The state RadioGroup.Root shares with its items.
+ *
+ * `value` is `null` when nothing is selected — a real state for a radio group, and the
+ * one a native group starts in. `null` rather than `undefined`, because `undefined` is
+ * what tells `useControlled` a group is uncontrolled.
+ */
+type RadioGroupState = {
+    value: string | null;
+    disabled: boolean;
+    required: boolean;
+    /** Always set — the consumer's, or one generated so the radios still form a group. */
+    name: string;
+    form: string | undefined;
+    /** The group's single setter. Every change goes through it (decision 10, rule 5). */
+    select: (value: string) => void;
+};
+/** What one radio projects as `data-*` attributes. */
+type RadioGroupItemState = {
+    checked: boolean;
+    disabled: boolean;
+};
+
+export { index_parts as RadioGroup, type RadioGroupItemProps, type RadioGroupItemState, type RadioGroupRootProps, type RadioGroupState };

package/dist/radio-group/index.js

@@ -0,0 +1,157 @@
+import {
+  useControlled
+} from "../chunk-UEIB3I3T.js";
+import {
+  __export,
+  useRender
+} from "../chunk-OQTWWZ4B.js";
+
+// src/radio-group/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  Item: () => RadioGroupItem,
+  Root: () => RadioGroupRoot
+});
+
+// src/radio-group/RadioGroupRoot.tsx
+import { useCallback, useEffect, useId, useMemo, useRef } from "react";
+
+// src/radio-group/RadioGroupRootContext.ts
+import { createContext, useContext } from "react";
+var RadioGroupRootContext = createContext(null);
+function useRadioGroupRootContext() {
+  const context = useContext(RadioGroupRootContext);
+  if (context === null) {
+    throw new Error("<RadioGroup.Item> must be rendered inside <RadioGroup.Root>.");
+  }
+  return context;
+}
+
+// src/radio-group/radioGroupDataAttributes.ts
+function radioGroupItemDataAttributes({ checked, disabled }) {
+  return {
+    "data-checked": checked ? "" : void 0,
+    "data-unchecked": checked ? void 0 : "",
+    "data-disabled": disabled ? "" : void 0
+  };
+}
+function radioGroupDataAttributes({ disabled }) {
+  return {
+    "data-disabled": disabled ? "" : void 0
+  };
+}
+
+// src/radio-group/RadioGroupRoot.tsx
+import { jsx } from "react/jsx-runtime";
+function radiosIn(root, name) {
+  if (!root) return [];
+  return [...root.querySelectorAll('input[type="radio"]')].filter(
+    (input) => input.name === name
+  );
+}
+function RadioGroupRoot({
+  value: valueProp,
+  defaultValue,
+  onValueChange,
+  name: nameProp,
+  disabled = false,
+  required = false,
+  form,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const [value, setValue] = useControlled({
+    controlled: valueProp,
+    default: defaultValue ?? null,
+    name: "RadioGroup.Root",
+    state: "value"
+  });
+  const generatedName = useId();
+  const name = nameProp ?? generatedName;
+  const commitValue = useCallback(
+    (next) => {
+      setValue(next);
+      onValueChange?.(next);
+    },
+    [setValue, onValueChange]
+  );
+  const elementRef = useRef(null);
+  const { current: initialValue } = useRef(value);
+  useEffect(() => {
+    const owner = radiosIn(elementRef.current, name)[0]?.form;
+    if (!owner) return;
+    function onReset(event) {
+      queueMicrotask(() => {
+        if (event.defaultPrevented) return;
+        for (const input of radiosIn(elementRef.current, name)) {
+          input.checked = input.value === value;
+        }
+        if (value === initialValue) return;
+        commitValue(initialValue);
+      });
+    }
+    owner.addEventListener("reset", onReset);
+    return () => owner.removeEventListener("reset", onReset);
+  }, [name, value, commitValue, initialValue]);
+  const state = useMemo(
+    () => ({ value, disabled, required, name, form, select: commitValue }),
+    [value, disabled, required, name, form, commitValue]
+  );
+  const element = useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      role: "radiogroup",
+      "aria-disabled": disabled || void 0,
+      "aria-required": required || void 0,
+      ...radioGroupDataAttributes(state),
+      className,
+      children,
+      ref: elementRef
+    },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ jsx(RadioGroupRootContext.Provider, { value: state, children: element });
+}
+
+// src/radio-group/RadioGroupItem.tsx
+import { useMemo as useMemo2 } from "react";
+function RadioGroupItem({
+  value,
+  disabled: disabledProp = false,
+  className,
+  render,
+  ...rest
+}) {
+  const group = useRadioGroupRootContext();
+  const disabled = group.disabled || disabledProp;
+  const checked = group.value === value;
+  const state = useMemo2(() => ({ checked, disabled }), [checked, disabled]);
+  return useRender({
+    render,
+    defaultTagName: "input",
+    props: {
+      type: "radio",
+      name: group.name,
+      value,
+      // Controlled from the group's value, so React restores it after any change the
+      // group declines — the platform never gets the last word on what is checked.
+      checked,
+      form: group.form,
+      required: group.required || void 0,
+      disabled: disabled || void 0,
+      ...radioGroupItemDataAttributes(state),
+      className,
+      onChange() {
+        if (disabled) return;
+        group.select(value);
+      }
+    },
+    consumerProps: rest
+  });
+}
+export {
+  index_parts_exports as RadioGroup
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Unstyled React behaviour primitives — render engine, controlled/uncontrolled state, and data-* state projection. Ships no CSS and no class names.",
   "license": "MIT",
   "type": "module",
@@ -54,6 +54,26 @@
         "default": "./dist/checkbox/index.cjs"
       }
     },
+    "./dialog": {
+      "import": {
+        "types": "./dist/dialog/index.d.ts",
+        "default": "./dist/dialog/index.js"
+      },
+      "require": {
+        "types": "./dist/dialog/index.d.cts",
+        "default": "./dist/dialog/index.cjs"
+      }
+    },
+    "./radio-group": {
+      "import": {
+        "types": "./dist/radio-group/index.d.ts",
+        "default": "./dist/radio-group/index.js"
+      },
+      "require": {
+        "types": "./dist/radio-group/index.d.cts",
+        "default": "./dist/radio-group/index.cjs"
+      }
+    },
     "./switch": {
       "import": {
         "types": "./dist/switch/index.d.ts",
@@ -83,8 +103,10 @@
     "@testing-library/react": "16.3.0",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.5",
+    "@vitest/browser-playwright": "4.1.11",
     "eslint": "9.39.4",
     "jsdom": "27.0.0",
+    "playwright": "1.63.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "tsup": "8.5.1",
@@ -99,6 +121,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "pnpm run test:unit",
-    "test:unit": "vitest run --passWithNoTests --config vitest.unit.config.ts"
+    "test:unit": "vitest run --passWithNoTests --config vitest.unit.config.ts",
+    "test:browser": "vitest run --config vitest.browser.config.ts"
   }
 }