@arun-dev/headless 4.5.1 → 4.7.0

package/dist/tabs/index.d.cts

@@ -0,0 +1,127 @@
+import * as react from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+/**
+ * Roving focus for composite widgets — one Tab stop for the group, arrow keys within it.
+ * Tabs first; Menu and Toolbar reuse it. Internal: shared between components, not exported
+ * (decision 9).
+ *
+ * The caller owns the list of items and which are enabled — from component props, never
+ * read back from the DOM (decision 10). This only answers "where does this key go".
+ */
+type Orientation = 'horizontal' | 'vertical';
+
+type TabsActivationMode = 'automatic' | 'manual';
+/** The state Tabs.Root shares with its parts, and projects as `data-*` attributes. */
+type TabsState = {
+    value: string | undefined;
+    orientation: Orientation;
+};
+
+type TabsRootOwnProps = {
+    /**
+     * Controlled selection: the `value` of the selected Tab. Provide `onValueChange` alongside.
+     *
+     * Never `undefined` once mounted: the mode is latched at mount, as for Switch.
+     */
+    value?: string;
+    /** Initial selection when uncontrolled. Read once, at mount. Without one, none is selected. */
+    defaultValue?: string;
+    /** Called with the Tab's `value` whenever the selection changes. */
+    onValueChange?: (value: string) => void;
+    /** The axis the tabs run along, and so which arrow keys move between them. */
+    orientation?: Orientation;
+    /**
+     * `automatic` selects a tab as soon as it has focus; `manual` waits for Enter, Space or a
+     * click. Manual suits panels that are slow to show.
+     */
+    activationMode?: TabsActivationMode;
+    /**
+     * Keeps disabled tabs in the arrow-key sequence, so a screen reader announces them as
+     * unavailable. They still cannot be selected. Only with `activationMode="manual"`: under
+     * `"automatic"` moving focus to a tab selects it, so disabled tabs are always skipped and
+     * this has no effect.
+     */
+    focusableWhenDisabled?: boolean;
+    /** Element to render instead of the default `<div>`. Props 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 TabsRootProps = TabsRootOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof TabsRootOwnProps | 'defaultValue' | 'onChange'>;
+/**
+ * Tabs, by the WAI-ARIA pattern: a tablist of tabs, one panel each, one selected.
+ *
+ * There is no native element to lean on (decision 7), so the behaviour is built here: the
+ * selection, arrow-key focus with a single Tab stop (roving tabindex, `core/rovingFocus`),
+ * and the ids that wire each tab to its panel.
+ *
+ * Each Tab registers its own `value` and `disabled` from its props; the Root never reads
+ * them back from the DOM (decision 10). Elements are kept only to move focus to.
+ */
+declare function TabsRoot({ value: valueProp, defaultValue, onValueChange, orientation, activationMode, focusableWhenDisabled: focusableWhenDisabledProp, className, children, render, ...rest }: TabsRootProps): react.JSX.Element;
+
+type TabsListOwnProps = {
+    /** Element to render instead of the default `<div>`. Props 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 TabsListProps = TabsListOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof TabsListOwnProps>;
+/**
+ * The tablist. Holds the keyboard: arrows along the orientation, wrapping at the ends,
+ * Home and End — moving focus among the enabled tabs, and the disabled ones too with
+ * `focusableWhenDisabled`. Whether focusing a tab also
+ * selects it is the Tab's to decide, by `activationMode`.
+ *
+ * Name it with `aria-label` or `aria-labelledby` when the page has more than one.
+ */
+declare function TabsList({ className, children, render, ...rest }: TabsListProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type TabsTabOwnProps = {
+    /** Identifies this tab, and the Panel with the same `value`. */
+    value: string;
+    /**
+     * Cannot be selected. Skipped by the arrow keys, unless the Root sets
+     * `focusableWhenDisabled` with `activationMode="manual"`.
+     */
+    disabled?: boolean;
+    /** Element to render instead of the default `<button>`. Props 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 TabsTabProps = TabsTabOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof TabsTabOwnProps | 'value'>;
+/**
+ * One tab. A native `<button>`, so Enter, Space and a click select it with no key handling
+ * here. Only the tab holding the group's Tab stop has `tabIndex={0}` — roving tabindex — so
+ * Tab enters the list at the selected tab and leaves it after one press.
+ *
+ * With `activationMode="automatic"` (the default) focus selects: the arrow keys change the
+ * panel as they move. With `"manual"` they only move focus.
+ */
+declare function TabsTab({ value, disabled, onClick, className, children, render, ...rest }: TabsTabProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type TabsPanelOwnProps = {
+    /** The `value` of the Tab this panel belongs to. */
+    value: string;
+    /** Element to render instead of the default `<div>`. Props 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 TabsPanelProps = TabsPanelOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof TabsPanelOwnProps>;
+/**
+ * The content for one tab, labelled by it. Hidden with the `hidden` attribute while its tab
+ * is not selected, and stays mounted, so what is inside keeps its state between visits.
+ *
+ * `tabIndex={0}`, as the pattern recommends, so a panel with nothing focusable inside is
+ * still reached by Tab after the tablist.
+ */
+declare function TabsPanel({ value, className, children, render, ...rest }: TabsPanelProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { TabsList as List, TabsPanel as Panel, TabsRoot as Root, TabsTab as Tab };
+}
+
+export { index_parts as Tabs, type TabsActivationMode, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsState, type TabsTabProps };

package/dist/tabs/index.d.ts

@@ -0,0 +1,127 @@
+import * as react from 'react';
+import { ReactElement, Ref, ComponentPropsWithRef } from 'react';
+
+/**
+ * Roving focus for composite widgets — one Tab stop for the group, arrow keys within it.
+ * Tabs first; Menu and Toolbar reuse it. Internal: shared between components, not exported
+ * (decision 9).
+ *
+ * The caller owns the list of items and which are enabled — from component props, never
+ * read back from the DOM (decision 10). This only answers "where does this key go".
+ */
+type Orientation = 'horizontal' | 'vertical';
+
+type TabsActivationMode = 'automatic' | 'manual';
+/** The state Tabs.Root shares with its parts, and projects as `data-*` attributes. */
+type TabsState = {
+    value: string | undefined;
+    orientation: Orientation;
+};
+
+type TabsRootOwnProps = {
+    /**
+     * Controlled selection: the `value` of the selected Tab. Provide `onValueChange` alongside.
+     *
+     * Never `undefined` once mounted: the mode is latched at mount, as for Switch.
+     */
+    value?: string;
+    /** Initial selection when uncontrolled. Read once, at mount. Without one, none is selected. */
+    defaultValue?: string;
+    /** Called with the Tab's `value` whenever the selection changes. */
+    onValueChange?: (value: string) => void;
+    /** The axis the tabs run along, and so which arrow keys move between them. */
+    orientation?: Orientation;
+    /**
+     * `automatic` selects a tab as soon as it has focus; `manual` waits for Enter, Space or a
+     * click. Manual suits panels that are slow to show.
+     */
+    activationMode?: TabsActivationMode;
+    /**
+     * Keeps disabled tabs in the arrow-key sequence, so a screen reader announces them as
+     * unavailable. They still cannot be selected. Only with `activationMode="manual"`: under
+     * `"automatic"` moving focus to a tab selects it, so disabled tabs are always skipped and
+     * this has no effect.
+     */
+    focusableWhenDisabled?: boolean;
+    /** Element to render instead of the default `<div>`. Props 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 TabsRootProps = TabsRootOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof TabsRootOwnProps | 'defaultValue' | 'onChange'>;
+/**
+ * Tabs, by the WAI-ARIA pattern: a tablist of tabs, one panel each, one selected.
+ *
+ * There is no native element to lean on (decision 7), so the behaviour is built here: the
+ * selection, arrow-key focus with a single Tab stop (roving tabindex, `core/rovingFocus`),
+ * and the ids that wire each tab to its panel.
+ *
+ * Each Tab registers its own `value` and `disabled` from its props; the Root never reads
+ * them back from the DOM (decision 10). Elements are kept only to move focus to.
+ */
+declare function TabsRoot({ value: valueProp, defaultValue, onValueChange, orientation, activationMode, focusableWhenDisabled: focusableWhenDisabledProp, className, children, render, ...rest }: TabsRootProps): react.JSX.Element;
+
+type TabsListOwnProps = {
+    /** Element to render instead of the default `<div>`. Props 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 TabsListProps = TabsListOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof TabsListOwnProps>;
+/**
+ * The tablist. Holds the keyboard: arrows along the orientation, wrapping at the ends,
+ * Home and End — moving focus among the enabled tabs, and the disabled ones too with
+ * `focusableWhenDisabled`. Whether focusing a tab also
+ * selects it is the Tab's to decide, by `activationMode`.
+ *
+ * Name it with `aria-label` or `aria-labelledby` when the page has more than one.
+ */
+declare function TabsList({ className, children, render, ...rest }: TabsListProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type TabsTabOwnProps = {
+    /** Identifies this tab, and the Panel with the same `value`. */
+    value: string;
+    /**
+     * Cannot be selected. Skipped by the arrow keys, unless the Root sets
+     * `focusableWhenDisabled` with `activationMode="manual"`.
+     */
+    disabled?: boolean;
+    /** Element to render instead of the default `<button>`. Props 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 TabsTabProps = TabsTabOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof TabsTabOwnProps | 'value'>;
+/**
+ * One tab. A native `<button>`, so Enter, Space and a click select it with no key handling
+ * here. Only the tab holding the group's Tab stop has `tabIndex={0}` — roving tabindex — so
+ * Tab enters the list at the selected tab and leaves it after one press.
+ *
+ * With `activationMode="automatic"` (the default) focus selects: the arrow keys change the
+ * panel as they move. With `"manual"` they only move focus.
+ */
+declare function TabsTab({ value, disabled, onClick, className, children, render, ...rest }: TabsTabProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+type TabsPanelOwnProps = {
+    /** The `value` of the Tab this panel belongs to. */
+    value: string;
+    /** Element to render instead of the default `<div>`. Props 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 TabsPanelProps = TabsPanelOwnProps & Omit<ComponentPropsWithRef<'div'>, keyof TabsPanelOwnProps>;
+/**
+ * The content for one tab, labelled by it. Hidden with the `hidden` attribute while its tab
+ * is not selected, and stays mounted, so what is inside keeps its state between visits.
+ *
+ * `tabIndex={0}`, as the pattern recommends, so a panel with nothing focusable inside is
+ * still reached by Tab after the tablist.
+ */
+declare function TabsPanel({ value, className, children, render, ...rest }: TabsPanelProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { TabsList as List, TabsPanel as Panel, TabsRoot as Root, TabsTab as Tab };
+}
+
+export { index_parts as Tabs, type TabsActivationMode, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsState, type TabsTabProps };

package/dist/tabs/index.js

@@ -0,0 +1,242 @@
+import {
+  byDocumentOrder,
+  rovingIndex
+} from "../chunk-2S4XG4VD.js";
+import {
+  useControlled
+} from "../chunk-UEIB3I3T.js";
+import {
+  __export,
+  useRender
+} from "../chunk-OQTWWZ4B.js";
+
+// src/tabs/index.parts.ts
+var index_parts_exports = {};
+__export(index_parts_exports, {
+  List: () => TabsList,
+  Panel: () => TabsPanel,
+  Root: () => TabsRoot,
+  Tab: () => TabsTab
+});
+
+// src/tabs/TabsRoot.tsx
+import { useCallback, useId, useMemo, useState } from "react";
+
+// src/tabs/TabsRootContext.ts
+import { createContext, useContext } from "react";
+var TabsRootContext = createContext(null);
+function useTabsRootContext(part) {
+  const context = useContext(TabsRootContext);
+  if (context === null) {
+    throw new Error(`<Tabs.${part}> must be rendered inside <Tabs.Root>.`);
+  }
+  return context;
+}
+
+// src/tabs/tabsDataAttributes.ts
+function orientationDataAttributes(orientation) {
+  return { "data-orientation": orientation };
+}
+function selectedDataAttributes(selected, disabled = false) {
+  return {
+    "data-selected": selected ? "" : void 0,
+    "data-unselected": selected ? void 0 : "",
+    "data-disabled": disabled ? "" : void 0
+  };
+}
+
+// src/tabs/TabsRoot.tsx
+import { jsx } from "react/jsx-runtime";
+function idPart(value) {
+  return value.replace(/\s+/g, "_");
+}
+function TabsRoot({
+  value: valueProp,
+  defaultValue,
+  onValueChange,
+  orientation = "horizontal",
+  activationMode = "automatic",
+  focusableWhenDisabled: focusableWhenDisabledProp = false,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const [value, setValueState] = useControlled({
+    controlled: valueProp,
+    default: defaultValue,
+    name: "Tabs.Root",
+    state: "value"
+  });
+  const setValue = useCallback(
+    (next) => {
+      if (next === value) return;
+      setValueState(next);
+      onValueChange?.(next);
+    },
+    [value, setValueState, onValueChange]
+  );
+  const [tabs, setTabs] = useState([]);
+  const register = useCallback((entry) => {
+    setTabs(
+      (current) => [...current.filter((t) => t.value !== entry.value), entry].sort(byDocumentOrder)
+    );
+    return () => setTabs((current) => current.filter((t) => t !== entry));
+  }, []);
+  const focusableWhenDisabled = focusableWhenDisabledProp && activationMode === "manual";
+  const navigableTabs = useMemo(
+    () => focusableWhenDisabled ? tabs : tabs.filter((t) => !t.disabled),
+    [tabs, focusableWhenDisabled]
+  );
+  const tabStopValue = tabs.length === 0 ? value : (navigableTabs.find((t) => t.value === value) ?? navigableTabs[0])?.value;
+  const baseId = useId();
+  const context = useMemo(
+    () => ({
+      value,
+      setValue,
+      orientation,
+      activationMode,
+      navigableTabs,
+      focusableWhenDisabled,
+      tabStopValue,
+      register,
+      tabId: (v) => `${baseId}-tab-${idPart(v)}`,
+      panelId: (v) => `${baseId}-panel-${idPart(v)}`
+    }),
+    [
+      value,
+      setValue,
+      orientation,
+      activationMode,
+      navigableTabs,
+      focusableWhenDisabled,
+      tabStopValue,
+      register,
+      baseId
+    ]
+  );
+  const element = useRender({
+    render,
+    defaultTagName: "div",
+    props: { ...orientationDataAttributes(orientation), className, children },
+    consumerProps: rest
+  });
+  return /* @__PURE__ */ jsx(TabsRootContext.Provider, { value: context, children: element });
+}
+
+// src/tabs/TabsList.tsx
+import { useRef } from "react";
+function TabsList({ className, children, render, ...rest }) {
+  const { orientation, navigableTabs } = useTabsRootContext("List");
+  const elementRef = useRef(null);
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      role: "tablist",
+      // Horizontal is the ARIA default for a tablist, so it is only stated when vertical.
+      "aria-orientation": orientation === "vertical" ? "vertical" : void 0,
+      ...orientationDataAttributes(orientation),
+      className,
+      children,
+      ref: elementRef,
+      onKeyDown(event) {
+        const current = navigableTabs.findIndex((t) => t.ref.current === event.target);
+        if (current < 0) return;
+        const list = elementRef.current;
+        const rtl = list ? getComputedStyle(list).direction === "rtl" : false;
+        const next = rovingIndex(event.key, {
+          count: navigableTabs.length,
+          current,
+          orientation,
+          rtl
+        });
+        if (next === null) return;
+        event.preventDefault();
+        navigableTabs[next]?.ref.current?.focus();
+      }
+    },
+    consumerProps: rest
+  });
+}
+
+// src/tabs/TabsTab.tsx
+import { useLayoutEffect, useRef as useRef2 } from "react";
+function TabsTab({
+  value,
+  disabled = false,
+  onClick,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const {
+    value: selectedValue,
+    setValue,
+    activationMode,
+    focusableWhenDisabled,
+    tabStopValue,
+    register,
+    tabId,
+    panelId
+  } = useTabsRootContext("Tab");
+  const elementRef = useRef2(null);
+  const selected = value === selectedValue;
+  useLayoutEffect(
+    () => register({ value, disabled, ref: elementRef }),
+    [register, value, disabled]
+  );
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      type: "button",
+      role: "tab",
+      id: tabId(value),
+      "aria-selected": selected,
+      "aria-controls": panelId(value),
+      tabIndex: value === tabStopValue ? 0 : -1,
+      // The platform keeps a disabled button out of focus and activation. Focusable when
+      // disabled, it is aria-disabled instead, and activation is blocked here.
+      disabled: disabled && !focusableWhenDisabled || void 0,
+      "aria-disabled": disabled && focusableWhenDisabled || void 0,
+      ...selectedDataAttributes(selected, disabled),
+      className,
+      children,
+      ref: elementRef,
+      onClick() {
+        if (!disabled) setValue(value);
+      },
+      onFocus() {
+        if (activationMode === "automatic" && !disabled) setValue(value);
+      }
+    },
+    // A native `disabled` would block your onClick; aria-disabled does not, so it is left off.
+    consumerProps: disabled ? rest : { ...rest, onClick }
+  });
+}
+
+// src/tabs/TabsPanel.tsx
+function TabsPanel({ value, className, children, render, ...rest }) {
+  const { value: selectedValue, tabId, panelId } = useTabsRootContext("Panel");
+  const selected = value === selectedValue;
+  return useRender({
+    render,
+    defaultTagName: "div",
+    props: {
+      role: "tabpanel",
+      id: panelId(value),
+      "aria-labelledby": tabId(value),
+      tabIndex: 0,
+      hidden: !selected || void 0,
+      ...selectedDataAttributes(selected),
+      className,
+      children
+    },
+    consumerProps: rest
+  });
+}
+export {
+  index_parts_exports as Tabs
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.5.1",
+  "version": "4.7.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",
@@ -64,6 +64,16 @@
         "default": "./dist/dialog/index.cjs"
       }
     },
+    "./menu": {
+      "import": {
+        "types": "./dist/menu/index.d.ts",
+        "default": "./dist/menu/index.js"
+      },
+      "require": {
+        "types": "./dist/menu/index.d.cts",
+        "default": "./dist/menu/index.cjs"
+      }
+    },
     "./popover": {
       "import": {
         "types": "./dist/popover/index.d.ts",
@@ -94,6 +104,16 @@
         "default": "./dist/switch/index.cjs"
       }
     },
+    "./tabs": {
+      "import": {
+        "types": "./dist/tabs/index.d.ts",
+        "default": "./dist/tabs/index.js"
+      },
+      "require": {
+        "types": "./dist/tabs/index.d.cts",
+        "default": "./dist/tabs/index.cjs"
+      }
+    },
     "./tooltip": {
       "import": {
         "types": "./dist/tooltip/index.d.ts",