@primitiv-ui/react 0.1.28 → 0.1.29

package/src/Select/hooks/useSelectRoot.ts

@@ -0,0 +1,149 @@
+import {
+  ReactNode,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+import { useControllableState } from "../../hooks/index.ts";
+import type { SelectContextValue } from "../SelectContext";
+
+type UseSelectRootArgs = {
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+};
+
+/**
+ * State owner for the rich (non-`native`) Select. Manages the open/close
+ * state of the listbox popover — controlled (`open` + `onOpenChange`) or
+ * uncontrolled (`defaultOpen`) — and derives the trigger/content ids.
+ * Mirrors {@link useDropdownRoot}, including the `openRef` de-dupe so a
+ * single light-dismiss that fires both a `toggle` event and our own close
+ * does not double-notify `onOpenChange`.
+ */
+export function useSelectRoot({
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+  value: controlledValue,
+  defaultValue,
+  onValueChange,
+}: UseSelectRootArgs): {
+  contextValue: SelectContextValue;
+  value: string;
+  itemValues: string[];
+} {
+  const contentId = useId();
+  const triggerId = useId();
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const [open, setOpenBase] = useControllableState<boolean>(
+    controlledOpen,
+    defaultOpen,
+    onOpenChange,
+  );
+  const [value, setValue] = useControllableState<string>(
+    controlledValue,
+    defaultValue ?? "",
+    onValueChange,
+  );
+
+  const openRef = useRef(open);
+  useEffect(() => {
+    openRef.current = open;
+  });
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (openRef.current === next) return;
+      openRef.current = next;
+      setOpenBase(next);
+    },
+    [setOpenBase],
+  );
+
+  // Commit a selection: update the value, close the listbox, and return
+  // focus to the trigger (the standard listbox close-on-select behaviour).
+  const select = useCallback(
+    (next: string) => {
+      setValue(next);
+      setOpenBase(false);
+      openRef.current = false;
+      // Stryker disable next-line OptionalChaining: unreachable — the trigger is always mounted when an item is selected (selection happens inside the open Content).
+      triggerRef.current?.focus();
+    },
+    [setValue, setOpenBase],
+  );
+
+  // Item registry — lets Select.Value mirror the selected item's content
+  // (written once on the Item). Children live in a ref (updated silently
+  // every render, no re-render churn); `itemVersion` bumps only when the set
+  // of registered values changes (mount/unmount), so Value re-renders when
+  // items appear or disappear. See the react-component-patterns skill.
+  const itemChildrenRef = useRef<Map<string, ReactNode>>(new Map());
+  const [itemVersion, setItemVersion] = useState(0);
+
+  const registerItem = useCallback((itemValue: string, node: ReactNode) => {
+    const isNew = !itemChildrenRef.current.has(itemValue);
+    itemChildrenRef.current.set(itemValue, node);
+    // Stryker disable next-line ArithmeticOperator,ArrowFunction: equivalent — the version is an opaque re-render trigger; any updater (v+1, v-1, or `() => undefined`) changes state and re-renders identically.
+    if (isNew) setItemVersion((v) => v + 1);
+  }, []);
+
+  const unregisterItem = useCallback((itemValue: string) => {
+    itemChildrenRef.current.delete(itemValue);
+    // Stryker disable next-line ArithmeticOperator,ArrowFunction: equivalent — the version is an opaque re-render trigger; any updater changes state and re-renders identically.
+    setItemVersion((v) => v + 1);
+  }, []);
+
+  const getItemChildren = useCallback(
+    (itemValue: string) => itemChildrenRef.current.get(itemValue),
+    [],
+  );
+
+  // Registered values, recomputed whenever items mount/unmount, so Root can
+  // render a matching <option> in the hidden form <select>.
+  const itemValues = useMemo(
+    () => Array.from(itemChildrenRef.current.keys()),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [itemVersion],
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      open,
+      setOpen,
+      value,
+      select,
+      registerItem,
+      unregisterItem,
+      getItemChildren,
+      contentId,
+      triggerId,
+      triggerRef,
+    }),
+    // itemVersion is intentionally in the dep list (not the value) so the
+    // context identity changes when items mount/unmount, re-rendering
+    // Select.Value even though the callbacks are stable.
+    [
+      open,
+      setOpen,
+      value,
+      select,
+      registerItem,
+      unregisterItem,
+      getItemChildren,
+      contentId,
+      triggerId,
+      itemVersion,
+    ],
+  );
+
+  return { contextValue, value, itemValues };
+}

package/src/Select/types.ts

@@ -1,15 +1,24 @@
-import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
+import {
+  ChangeEventHandler,
+  ComponentProps,
+  HTMLAttributes,
+  ReactNode,
+  Ref,
+} from "react";
 
 /**
  * Shared base for both {@link SelectRootProps} variants — the native
- * `<select>` attributes (minus the state-owning ones), the `asChild`
- * escape hatch, and the raw `onChange` passthrough.
+ * `<select>` attributes (minus the state-owning and multiple-selection
+ * ones), the `asChild` escape hatch, and the raw `onChange` passthrough.
  */
 export type SelectRootBaseProps = Omit<
   ComponentProps<"select">,
   "value" | "defaultValue" | "multiple" | "onChange"
 > & {
+  /** Content of the select — typically {@link SelectOption}, {@link SelectGroup},
+   * and optionally a leading {@link SelectPlaceholder}. */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLSelectElement`. */
   ref?: Ref<HTMLSelectElement>;
   /**
    * Native `change` handler. Fires alongside `onValueChange` whenever the
@@ -20,11 +29,52 @@ export type SelectRootBaseProps = Omit<
   /**
    * When `true`, Root delegates to a single consumer-supplied element
    * (expected to render a `<select>`) and merges its own props onto it
-   * via the {@link Slot} pattern. The placeholder-detection inside Root
-   * walks direct children only, so placeholder + `asChild` requires the
-   * consumer to set `defaultValue=""` explicitly.
+   * via the {@link Slot} pattern. Placeholder-detection inside Root
+   * walks direct children only in this mode, so the `asChild` +
+   * placeholder combination requires the consumer to set
+   * `defaultValue=""` explicitly.
+   * @default false
    */
   asChild?: boolean;
+  /**
+   * Selects the render path:
+   *
+   * - `false` (the default) — the **rich** render path: a fully-styleable
+   *   Popover-API listbox built from {@link SelectTrigger | `Select.Trigger`},
+   *   {@link SelectValue | `Select.Value`},
+   *   {@link SelectContent | `Select.Content`} and
+   *   {@link SelectItem | `Select.Item`}. Icons and other rich content on an
+   *   item render as authored.
+   * - `true` — the **native** render path: a thin wrapper over a real
+   *   `<select>` / `<option>` / `<optgroup>`, for flat, OS-native cases
+   *   (mobile wheel pickers, maximum-compatibility forms). Under `native`,
+   *   {@link SelectItem | `Select.Item`} renders an `<option>` from its
+   *   string/number children only — element children (icons, indicators)
+   *   are dropped.
+   *
+   * Both modes share the same `value` / `onValueChange` / `disabled` / form
+   * `name` API.
+   * @default false
+   */
+  native?: boolean;
+  /**
+   * Rich mode only — whether the listbox popover is open on first render.
+   * Ignored under `native` (the browser owns the popup). Uncontrolled: pass
+   * this (or omit for closed) and let the component manage the state.
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Rich mode only — the controlled open state of the listbox popover. Pass
+   * together with {@link SelectRootBaseProps.onOpenChange | `onOpenChange`}
+   * to own the state from the parent.
+   */
+  open?: boolean;
+  /**
+   * Rich mode only — called with the next open state whenever the listbox
+   * opens or closes (trigger click, selection, Escape, light-dismiss).
+   */
+  onOpenChange?: (open: boolean) => void;
 };
 
 /**
@@ -33,8 +83,15 @@ export type SelectRootBaseProps = Omit<
  * and `value` is forbidden.
  */
 export type SelectRootUncontrolledProps = SelectRootBaseProps & {
+  /** Value of the option selected on first render. When omitted and a
+   * {@link SelectPlaceholder} is present among Root's direct children,
+   * Root infers `""` automatically so the placeholder is the initial
+   * selection. */
   defaultValue?: string;
+  /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
   value?: never;
+  /** Called with the new option value whenever the user changes the
+   * selection. Optional in uncontrolled mode. */
   onValueChange?: (value: string) => void;
 };
 
@@ -44,61 +101,172 @@ export type SelectRootUncontrolledProps = SelectRootBaseProps & {
  * forbidden.
  */
 export type SelectRootControlledProps = SelectRootBaseProps & {
+  /** Forbidden in controlled mode — use `value` instead. */
   defaultValue?: never;
+  /** The currently selected option value. Must be kept in sync by the
+   * parent via `onValueChange`. */
   value: string;
+  /** Called with the new option value whenever the user changes the
+   * selection. Required in controlled mode. */
   onValueChange: (value: string) => void;
 };
 
 /**
- * Props for {@link Select.Root}.
- *
- * Two state modes are statically discriminated at the type level so only
- * one shape is accepted by TypeScript:
+ * Props for {@link SelectRoot | `Select.Root`}.
  *
- * - **Uncontrolled** — pass `defaultValue` (or omit it). The browser owns
- *   the selection state. `onValueChange` is optional.
- * - **Controlled** — pass `value` and `onValueChange` together. The
- *   parent owns the selection; the component defers every transition
- *   back through the callback.
- *
- * Native `multiple`-selection mode is not supported in v1.
+ * Resolves to either {@link SelectRootUncontrolledProps} or
+ * {@link SelectRootControlledProps} — only one shape is accepted by
+ * TypeScript at a time. Native `multiple`-selection mode is not supported
+ * in v1.
  */
 export type SelectRootProps =
   | SelectRootUncontrolledProps
   | SelectRootControlledProps;
 
 /**
- * Props for {@link Select.Option} — all `OptionHTMLAttributes` on the
- * underlying `<option>` element, plus a typed `ref`.
+ * Props for {@link SelectItem | `Select.Item`}.
+ *
+ * `Select.Item` renders different elements per mode — an `<option>` under
+ * `native`, a `<div role="option">` in rich mode — so it extends the
+ * element-agnostic `HTMLAttributes<HTMLElement>` rather than an
+ * option-specific type.
  */
-export type SelectOptionProps = ComponentProps<"option"> & {
+export type SelectItemProps = HTMLAttributes<HTMLElement> & {
+  /** The value this item represents; committed as the Select's value when
+   * chosen, and matched against the current value for the selected state. */
+  value: string;
+  /** Marks the item unselectable while still visible. */
+  disabled?: boolean;
+  /** The item content. In `native` mode only its string/number parts are
+   * kept as the `<option>` text (element children are dropped); in rich mode
+   * arbitrary content (icons, indicators) renders as authored. */
   children?: ReactNode;
-  ref?: Ref<HTMLOptionElement>;
 };
 
 /**
- * Props for {@link Select.Group} — all `OptgroupHTMLAttributes` on the
- * underlying `<optgroup>` element, plus a typed `ref`. `label` is
- * required by the native element and is what assistive technology
- * announces for the group.
+ * Props for {@link SelectGroup | `Select.Group`} — all
+ * `OptgroupHTMLAttributes` on the underlying `<optgroup>` element (with
+ * `label` narrowed to a required `string`), plus a typed `ref`.
  */
-export type SelectGroupProps = ComponentProps<"optgroup"> & {
+export type SelectGroupProps = HTMLAttributes<HTMLElement> & {
+  /**
+   * The group heading. In `native` mode it is the `<optgroup>`'s `label`
+   * attribute; in rich mode it becomes the `<div role="group">`'s
+   * `aria-label`. Either way it is the group's accessible name. Required —
+   * a group without one is inaccessible.
+   */
   label: string;
+  /** The {@link SelectItem} elements belonging to this group. */
   children?: ReactNode;
-  ref?: Ref<HTMLOptGroupElement>;
 };
 
 /**
- * Props for {@link Select.Placeholder}.
+ * Props for {@link SelectPlaceholder | `Select.Placeholder`}.
  *
- * `value`, `disabled`, and `hidden` are owned by the component — the
- * placeholder always has `value=""`, is always disabled, and is always
- * hidden from the dropdown — so they can't be set by the consumer.
+ * `value`, `disabled`, and `hidden` are owned by the component —
+ * the placeholder always renders with `value=""`, `disabled`, and `hidden`
+ * — so they are excluded from this type and cannot be set by the consumer.
  */
 export type SelectPlaceholderProps = Omit<
   ComponentProps<"option">,
   "value" | "disabled" | "hidden"
 > & {
+  /** The placeholder hint text shown in the closed select before the user
+   * makes a selection (e.g. `"Choose a fruit…"`). */
   children?: ReactNode;
+  /** Forwarded to the underlying `HTMLOptionElement`. */
   ref?: Ref<HTMLOptionElement>;
 };
+
+/**
+ * Props for {@link SelectTrigger | `Select.Trigger`} — the rich-mode button
+ * that opens the listbox. Extends the native `<button>` attributes.
+ */
+export type SelectTriggerProps = ComponentProps<"button"> & {
+  /** Trigger content — typically a {@link SelectValue | `Select.Value`}. */
+  children?: ReactNode;
+  /**
+   * Render the composed child element instead of a `<button>`, merging the
+   * trigger's ARIA attributes and click handler via the {@link Slot}
+   * pattern.
+   * @default false
+   */
+  asChild?: boolean;
+  /** Forwarded to the underlying `HTMLButtonElement`. */
+  ref?: Ref<HTMLButtonElement>;
+};
+
+/**
+ * Props for {@link SelectValue | `Select.Value`} — the rich-mode element,
+ * placed inside {@link SelectTrigger | `Select.Trigger`}, that displays the
+ * current selection (mirrored from the selected item in a later cycle) or a
+ * placeholder when nothing is selected. Extends `<span>` attributes minus
+ * `children`, which the component owns.
+ */
+export type SelectValueProps = Omit<ComponentProps<"span">, "children"> & {
+  /** Shown when no value is selected (e.g. `"Select a framework…"`). */
+  placeholder?: ReactNode;
+  /** Forwarded to the underlying `HTMLSpanElement`. */
+  ref?: Ref<HTMLSpanElement>;
+};
+
+/**
+ * Props for {@link SelectItemIndicator | `Select.ItemIndicator`} — the
+ * selection mark inside a rich {@link SelectItem | `Select.Item`}. Extends
+ * the native `<span>` attributes.
+ */
+export type SelectItemIndicatorProps = ComponentProps<"span"> & {
+  /** The mark to render (e.g. a checkmark glyph or icon). */
+  children?: ReactNode;
+  /**
+   * Render the composed child element instead of a `<span>` via the
+   * {@link Slot} pattern.
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * Keep the indicator mounted even when the item is not selected (it still
+   * exposes `data-state="unchecked"`), useful for CSS enter/exit animation.
+   * @default false
+   */
+  forceMount?: boolean;
+  /** Forwarded to the underlying `HTMLSpanElement`. */
+  ref?: Ref<HTMLSpanElement>;
+};
+
+/**
+ * Props for {@link SelectContent | `Select.Content`} — the rich-mode
+ * Popover-API listbox panel. Extends the native `<div>` attributes.
+ */
+export type SelectContentProps = ComponentProps<"div"> & {
+  /** Listbox content — {@link SelectItem | `Select.Item`} /
+   * {@link SelectGroup | `Select.Group`} elements. */
+  children?: ReactNode;
+  /**
+   * Render the composed child element instead of a `<div>`, merging the
+   * listbox props via the {@link Slot} pattern.
+   * @default false
+   */
+  asChild?: boolean;
+  /** Forwarded to the underlying `HTMLDivElement`. */
+  ref?: Ref<HTMLDivElement>;
+};
+
+/**
+ * Props for {@link SelectSeparator | `Select.Separator`} — a non-interactive
+ * divider between groups of options in rich mode. Extends the native `<div>`
+ * attributes and adds `asChild`.
+ */
+export type SelectSeparatorProps = Omit<ComponentProps<"div">, "role"> & {
+  /** Optional content; separators are usually empty, and only render (via
+   * the {@link Slot} pattern) when `asChild` composes onto a custom element. */
+  children?: ReactNode;
+  /** Forwarded to the underlying `HTMLDivElement`. */
+  ref?: Ref<HTMLDivElement>;
+  /**
+   * Render the composed child element (with separator semantics) instead of
+   * the default `<div role="separator">`.
+   * @default false
+   */
+  asChild?: boolean;
+};

package/src/SkipNav/SkipNav.tsx

@@ -5,29 +5,42 @@ import { SkipNavContentProps, SkipNavLinkProps } from "./types";
 const DEFAULT_CONTENT_ID = "primitiv-skip-nav";
 
 /**
- * The skip link itself — an `<a>` that jumps keyboard and screen-reader
- * users past repeated navigation straight to the main content.
+ * The skip link — an `<a>` that jumps keyboard and screen-reader users past
+ * repeated navigation straight to the main content.
  *
  * Place it as the very first focusable element on the page (typically the
- * first child of `<body>`). It is a normal in-page anchor: its `href` is a
+ * first child of `<body>`). It is a plain in-page anchor: its `href` is a
  * URL fragment pointing at the `id` of the matching {@link SkipNavContent |
  * `SkipNav.Content`}, so following it moves focus there with no JavaScript.
  *
  * **`contentId`.** The `href` is derived as `#${contentId}` and defaults to
- * a shared id, so an unconfigured `SkipNav.Link` / `SkipNav.Content` pair
- * works out of the box. Override `contentId` on the link only if you also
- * set a matching `id` on the content.
+ * a shared id (`"primitiv-skip-nav"`), so an unconfigured
+ * `SkipNav.Link` / `SkipNav.Content` pair works out of the box. Override
+ * `contentId` on the link only if you also set a matching `id` on
+ * {@link SkipNavContent | `SkipNav.Content`}.
  *
- * **Visibility.** The link ships with no styles. The conventional pattern
- * is to keep it visually hidden until focused — see the component README
- * for the canonical CSS.
+ * **Visibility.** No styles ship with the component. The conventional
+ * pattern keeps the link visually hidden until it receives focus — position
+ * it off-screen by default and restore it on `:focus`. Do **not** use
+ * `display: none` or `visibility: hidden`, as those remove it from the tab
+ * order entirely:
+ *
+ * ```css
+ * a[href="#primitiv-skip-nav"] { position: absolute; left: -9999px; }
+ * a[href="#primitiv-skip-nav"]:focus { left: 0; top: 0; }
+ * ```
+ *
+ * Alternatively, pass a `className` and target that class in your
+ * stylesheet.
+ *
+ * @extends HTMLAnchorElement
  *
  * @example Default — shared content id
  * ```tsx
  * <SkipNav.Link>Skip to main content</SkipNav.Link>
  * ```
  *
- * @example Custom content id
+ * @example Custom content id (must match the `id` on `SkipNav.Content`)
  * ```tsx
  * <SkipNav.Link contentId="main">Skip to main content</SkipNav.Link>
  * ```
@@ -47,23 +60,36 @@ function SkipNavLink({
 SkipNavLink.displayName = "SkipNavLink";
 
 /**
- * The skip target — a `<div>` placed at the start of the main content that
- * {@link SkipNavLink | `SkipNav.Link`} jumps to.
+ * The skip target — a `<div tabIndex={-1}>` placed at the start of the main
+ * content that {@link SkipNavLink | `SkipNav.Link`} jumps to.
  *
- * It carries `tabIndex={-1}` so it is a valid focus destination for an
- * in-page fragment navigation: when the link is followed, the browser
- * scrolls to this element *and* moves focus into it, so the next Tab press
- * continues from the main content rather than the top of the page.
+ * `tabIndex={-1}` makes the element a valid programmatic focus destination:
+ * when the link is followed the browser scrolls to this element *and* moves
+ * focus into it, so the next <kbd>Tab</kbd> press continues from within the
+ * main content rather than cycling back to the top of the page. No
+ * JavaScript runs; it is pure anchor navigation.
  *
- * **`id`.** Defaults to the same shared id as `SkipNav.Link`'s `contentId`.
- * Pass a custom `id` only if you set a matching `contentId` on the link.
+ * **`id`.** Defaults to the same shared id (`"primitiv-skip-nav"`) as
+ * {@link SkipNavLink | `SkipNav.Link`}'s `contentId`. Pass a custom `id`
+ * via the native `id` prop only if you set a matching `contentId` on the
+ * link — the spread props override the default, so the two always stay in
+ * sync.
  *
- * @example
+ * @extends HTMLDivElement
+ *
+ * @example Default — wraps the main page content
  * ```tsx
  * <SkipNav.Content>
  *   <main>…</main>
  * </SkipNav.Content>
  * ```
+ *
+ * @example Custom id (must match `contentId` on `SkipNav.Link`)
+ * ```tsx
+ * <SkipNav.Content id="main">
+ *   <main>…</main>
+ * </SkipNav.Content>
+ * ```
  */
 function SkipNavContent({
   children,
@@ -81,18 +107,22 @@ SkipNavContent.displayName = "SkipNavContent";
 /**
  * Headless, accessible **Skip Nav** — a "skip to main content" link and its
  * focus target, letting keyboard and screen-reader users bypass repeated
- * navigation.
+ * navigation. Implements the
+ * [WCAG 2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html)
+ * technique with no JavaScript — pure in-page anchor navigation.
  *
- * It is a stateless pair of sub-components, used as siblings rather than
- * nested:
+ * `SkipNav` is a stateless pair of sub-components used as siblings (not
+ * nested). Render the link first; place the content wrapper at the start of
+ * the main content area:
  *
- * - {@link SkipNavLink | `SkipNav.Link`} — the `<a>` skip link; render it
- *   first on the page.
- * - {@link SkipNavContent | `SkipNav.Content`} — the focusable `<div>`
- *   target wrapping the main content.
+ * - {@link SkipNavLink | `SkipNav.Link`} — the `<a>` skip link; must be
+ *   the first focusable element on the page.
+ * - {@link SkipNavContent | `SkipNav.Content`} — the `<div tabIndex={-1}>`
+ *   target; wrap it around (or immediately before) your main content.
  *
- * The two connect by a shared content id with a sensible default, so the
- * common case needs no configuration.
+ * The two sub-components are connected by a shared content id
+ * (`"primitiv-skip-nav"`) with no configuration required. Override both
+ * sides when you need a custom id.
  *
  * @example Minimal usage
  * ```tsx
@@ -111,7 +141,17 @@ SkipNavContent.displayName = "SkipNavContent";
  * }
  * ```
  *
- * @see {@link SkipNavLink} for the `contentId` contract and the visually-hidden-until-focused CSS pattern.
+ * @example Custom id — both sides must match
+ * ```tsx
+ * <SkipNav.Link contentId="main">Skip to main content</SkipNav.Link>
+ * <SkipNav.Content id="main">
+ *   <main>…</main>
+ * </SkipNav.Content>
+ * ```
+ *
+ * @see {@link SkipNavLink} for the `contentId` contract and the
+ *   visually-hidden-until-focused CSS pattern.
+ * @see {@link SkipNavContent} for the `tabIndex={-1}` focus-target behaviour.
  */
 const SkipNav = {
   Link: SkipNavLink,

package/src/SkipNav/__tests__/SkipNav.basic-rendering.test.tsx

@@ -20,4 +20,10 @@ describe("SkipNav component", () => {
     expect(content).toHaveAttribute("id", "primitiv-skip-nav");
     expect(content).toHaveAttribute("tabindex", "-1");
   });
+
+  it("sets displayName on each sub-component for React DevTools and stack traces", () => {
+    // Assert — an empty displayName would render each as anonymous.
+    expect(SkipNav.Link.displayName).toBe("SkipNavLink");
+    expect(SkipNav.Content.displayName).toBe("SkipNavContent");
+  });
 });

package/src/SkipNav/types.ts

@@ -1,26 +1,34 @@
 import type { AnchorHTMLAttributes, HTMLAttributes, ReactNode } from "react";
 
 /**
- * Props for {@link SkipNav.Link} — `children`, an optional `contentId`,
- * plus all `AnchorHTMLAttributes` on the rendered `<a>`.
+ * Props for {@link SkipNavLink | `SkipNav.Link`} — `children`, an optional
+ * `contentId`, plus all native `<a>` attributes.
  */
 export type SkipNavLinkProps = {
+  /** The visible link text (e.g. `"Skip to main content"`). */
   children?: ReactNode;
   /**
-   * Id of the matching {@link SkipNav.Content} target. The link's `href`
-   * is derived as `#${contentId}`. Defaults to a shared id, so an
-   * unconfigured `SkipNav.Link` / `SkipNav.Content` pair works as-is.
+   * Id of the matching {@link SkipNavContent | `SkipNav.Content`} target.
+   * The link's `href` is derived as `#${contentId}`. Defaults to the shared
+   * id (`"primitiv-skip-nav"`), so an unconfigured
+   * `SkipNav.Link` / `SkipNav.Content` pair works out of the box. Override
+   * only when you also set a matching native `id` prop on `SkipNav.Content`.
+   * @default "primitiv-skip-nav"
    */
   contentId?: string;
 } & AnchorHTMLAttributes<HTMLAnchorElement>;
 
 /**
- * Props for {@link SkipNav.Content} — `children` plus all `HTMLAttributes`
- * on the rendered `<div>`.
+ * Props for {@link SkipNavContent | `SkipNav.Content`} — `children` plus
+ * all native `<div>` attributes.
  *
- * Pass a custom `id` only if you set a matching `contentId` on
- * {@link SkipNav.Link}; it defaults to the same shared id.
+ * The component always renders with `tabIndex={-1}` (making it a valid
+ * programmatic focus target) and sets `id` to `"primitiv-skip-nav"` by
+ * default. Pass a native `id` prop to override the default; when you do,
+ * set the same value as `contentId` on {@link SkipNavLink | `SkipNav.Link`}
+ * so the anchor's `href` resolves correctly.
  */
 export type SkipNavContentProps = {
+  /** The main page content that follows the skip target. */
   children?: ReactNode;
 } & HTMLAttributes<HTMLDivElement>;