@primitiv-ui/react 0.1.38 → 0.1.40

package/src/SkipNav/SkipNav.tsx

@@ -1,161 +0,0 @@
-import type { ReactElement } from "react";
-
-import { SkipNavContentProps, SkipNavLinkProps } from "./types";
-
-const DEFAULT_CONTENT_ID = "primitiv-skip-nav";
-
-/**
- * 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 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 (`"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.** 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 (must match the `id` on `SkipNav.Content`)
- * ```tsx
- * <SkipNav.Link contentId="main">Skip to main content</SkipNav.Link>
- * ```
- */
-function SkipNavLink({
-  children,
-  contentId = DEFAULT_CONTENT_ID,
-  ...rest
-}: SkipNavLinkProps): ReactElement {
-  return (
-    <a href={`#${contentId}`} {...rest}>
-      {children}
-    </a>
-  );
-}
-
-SkipNavLink.displayName = "SkipNavLink";
-
-/**
- * The skip target — a `<div tabIndex={-1}>` placed at the start of the main
- * content that {@link SkipNavLink | `SkipNav.Link`} jumps to.
- *
- * `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 (`"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.
- *
- * @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,
-  ...rest
-}: SkipNavContentProps): ReactElement {
-  return (
-    <div id={DEFAULT_CONTENT_ID} tabIndex={-1} {...rest}>
-      {children}
-    </div>
-  );
-}
-
-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. 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.
- *
- * `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; 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 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
- * import { SkipNav } from "@primitiv-ui/react";
- *
- * export function App() {
- *   return (
- *     <>
- *       <SkipNav.Link>Skip to main content</SkipNav.Link>
- *       <header>...site navigation...</header>
- *       <SkipNav.Content>
- *         <main>...</main>
- *       </SkipNav.Content>
- *     </>
- *   );
- * }
- * ```
- *
- * @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,
-  Content: SkipNavContent,
-};
-
-export { SkipNav };

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

@@ -1,29 +0,0 @@
-import { SkipNav } from "../SkipNav";
-import { render, screen } from "@testing-library/react";
-
-describe("SkipNav component", () => {
-  it("should render a skip link as an anchor", () => {
-    // Arrange
-    render(<SkipNav.Link href="#main">Skip to content</SkipNav.Link>);
-
-    // Assert
-    const link = screen.getByRole("link", { name: "Skip to content" });
-    expect(link).toHaveAttribute("href", "#main");
-  });
-
-  it("should render Content as a programmatically focusable region", () => {
-    // Arrange
-    render(<SkipNav.Content>Main content</SkipNav.Content>);
-
-    // Assert
-    const content = screen.getByText("Main content");
-    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/__tests__/SkipNav.ids.test.tsx

@@ -1,19 +0,0 @@
-import { SkipNav } from "../index.ts";
-import { render, screen } from "@testing-library/react";
-
-describe("SkipNav id wiring", () => {
-  it("should derive SkipNav.Link href from the contentId prop", () => {
-    render(<SkipNav.Link contentId="main-content">Skip to content</SkipNav.Link>);
-
-    expect(screen.getByRole("link")).toHaveAttribute("href", "#main-content");
-  });
-
-  it("should default SkipNav.Link href to the shared content id", () => {
-    render(<SkipNav.Link>Skip to content</SkipNav.Link>);
-
-    expect(screen.getByRole("link")).toHaveAttribute(
-      "href",
-      "#primitiv-skip-nav",
-    );
-  });
-});

package/src/SkipNav/index.ts

@@ -1 +0,0 @@
-export * from "./SkipNav";

package/src/SkipNav/types.ts

@@ -1,34 +0,0 @@
-import type { AnchorHTMLAttributes, HTMLAttributes, ReactNode } from "react";
-
-/**
- * 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 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 SkipNavContent | `SkipNav.Content`} — `children` plus
- * all native `<div>` attributes.
- *
- * 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>;

package/src/Slider/README.md

@@ -1,245 +0,0 @@
-# Slider
-
-Headless, accessible **Slider** — a compound component implementing the
-[WAI-ARIA Slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/)
-and the
-[Multi-Thumb Slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/).
-The value is always an **array of numbers**, with one thumb per entry. Zero
-styles ship.
-
-```tsx
-import { Slider } from "@primitiv-ui/react";
-
-<Slider.Root defaultValue={[40]}>
-  <Slider.Track>
-    <Slider.Range />
-  </Slider.Track>
-  <Slider.Thumb aria-label="Volume" />
-</Slider.Root>
-```
-
-## Sub-components
-
-| Export | Element | ARIA / data hooks | `asChild` |
-|--------|---------|-------------------|-----------|
-| `Slider.Root` | `<span>` | `data-orientation`, `data-disabled` | yes |
-| `Slider.Track` | `<span>` | `data-orientation`, `data-disabled` | yes |
-| `Slider.Range` | `<span>` | `data-orientation`, `data-disabled`, inline position `style` | yes |
-| `Slider.Thumb` | `<span>` | `role="slider"`, `aria-valuemin/max/now`, `aria-orientation`, `aria-disabled`, `data-orientation`, `data-disabled`, inline position `style` | yes |
-
-Render **one `Slider.Thumb` per entry** in the value array, in order. A
-single-thumb slider has one thumb; a range slider has two; any number is
-supported.
-
-## Root props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `min` | `number` | `0` | Lowest value. |
-| `max` | `number` | `100` | Highest value. Must be greater than `min`. |
-| `step` | `number` | `1` | Granularity. Must be greater than `0`. |
-| `minStepsBetweenThumbs` | `number` | `0` | Minimum gap (in steps) kept between adjacent thumbs. |
-| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout axis. |
-| `dir` | `"ltr" \| "rtl"` | inherited | Reading direction (horizontal). Inherited from `DirectionProvider`, else `"ltr"`. |
-| `inverted` | `boolean` | `false` | Reverse the direction the value increases. |
-| `disabled` | `boolean` | `false` | Disable all interaction. |
-| `name` | `string` | — | Render hidden inputs for form submission. |
-| `defaultValue` / `value` | `number[]` | `[min]` | Uncontrolled / controlled value. |
-| `onValueChange` | `(value: number[]) => void` | — | Fires on every change. |
-| `onValueCommit` | `(value: number[]) => void` | — | Fires once when an interaction ends. |
-
-## State modes
-
-### Uncontrolled
-
-Pass `defaultValue` (or omit it for a single thumb seeded at `min`). The
-component owns the value internally.
-
-```tsx
-<Slider.Root defaultValue={[25, 75]}>
-  <Slider.Track>
-    <Slider.Range />
-  </Slider.Track>
-  <Slider.Thumb aria-label="Minimum" />
-  <Slider.Thumb aria-label="Maximum" />
-</Slider.Root>
-```
-
-### Controlled
-
-Pass `value` and `onValueChange` together. The parent owns the value.
-
-```tsx
-const [value, setValue] = useState([20, 80]);
-
-<Slider.Root value={value} onValueChange={setValue}>
-  <Slider.Track>
-    <Slider.Range />
-  </Slider.Track>
-  <Slider.Thumb />
-  <Slider.Thumb />
-</Slider.Root>
-```
-
-### Committing the final value
-
-`onValueChange` fires on every increment during a drag. `onValueCommit` fires
-**once** with the settled array when the interaction ends — use it to persist
-only the final value.
-
-```tsx
-<Slider.Root
-  defaultValue={[40]}
-  onValueCommit={(value) => save(value)}
->
-  ...
-</Slider.Root>
-```
-
-## Labelling
-
-**The accessible name goes on the `Thumb`, not the Root.** The Thumb is the
-`role="slider"`; the Root renders a plain `<span>` with no role, so an
-`aria-label` there is attached to nothing and announced nowhere. It is a silent
-failure — the slider still looks and behaves correctly — and the examples in this
-file used to model it.
-
-```tsx
-<Slider.Thumb aria-label="Volume" />
-```
-
-For a **visible** label, give it an id and point the thumb at it. A
-`<label htmlFor>` cannot associate with a `<span role="slider">`, and `Slider`
-does not read `FieldContext` (only `Input`, `Textarea` and `Select` do) — so a
-`Field.Label` does not reach the thumb on its own:
-
-```tsx
-<Field.Root>
-  <Field.Label id="volume-label">Volume</Field.Label>
-  <Slider.Root defaultValue={[40]}>
-    <Slider.Track><Slider.Range /></Slider.Track>
-    <Slider.Thumb aria-labelledby="volume-label" />
-  </Slider.Root>
-</Field.Root>
-```
-
-On a range, name each thumb separately — two thumbs sharing one label are
-announced identically, so you cannot tell by ear which end you are on.
-
-## Keyboard interaction
-
-Each thumb is independently focusable.
-
-| Key | Behaviour |
-|-----|-----------|
-| `Arrow Right` / `Arrow Up` | Increase by `step` |
-| `Arrow Left` / `Arrow Down` | Decrease by `step` |
-| `Page Up` / `Page Down` | Increase / decrease by ten steps |
-| `Home` / `End` | Jump to `min` / `max` |
-
-Arrow direction follows `orientation`, `dir`, and `inverted`. A thumb cannot
-cross its neighbours, and `minStepsBetweenThumbs` enforces a configurable gap.
-
-## Orientation
-
-Pass `orientation="vertical"` for a vertical slider. Pointer interaction maps
-the Y axis to the value and thumbs are positioned from the bottom edge.
-
-## Reading direction & inversion
-
-`dir="rtl"` flips a horizontal slider so the value increases leftwards.
-`inverted` reverses the direction the value increases on either axis. Both
-affect keyboard arrows, pointer mapping, and the inline positioning styles.
-
-When `dir` is omitted, it is inherited from the nearest
-[`DirectionProvider`](../DirectionProvider/README.md), falling back to `"ltr"`
-when there is no provider. An explicit `dir` prop always wins over the
-inherited value.
-
-## Disabled
-
-Pass `disabled` on the Root. Every part receives `data-disabled=""`, thumbs
-leave the tab order and gain `aria-disabled="true"`, and keyboard and pointer
-interaction are ignored.
-
-## Form submission
-
-Pass `name` to render a hidden `<input>` per thumb so the values post with a
-surrounding `<form>`. Multi-thumb sliders suffix the name with `[]`
-(`name="range[]"`).
-
-```tsx
-<form>
-  <Slider.Root defaultValue={[10, 90]} name="price">
-    ...
-  </Slider.Root>
-</form>
-```
-
-## `asChild` composition
-
-Every sub-component accepts `asChild`. The library's ARIA attributes,
-`data-*` hooks, positioning `style`, event handlers, and ref are merged onto
-the consumer's element.
-
-```tsx
-<Slider.Thumb asChild>
-  <MyHandle />
-</Slider.Thumb>
-```
-
-## Positioning
-
-`Slider.Range` and `Slider.Thumb` ship an inline `style` placing them along
-the track as a percentage offset. Give `Slider.Root` / `Slider.Track` a size
-and `position: relative`; the parts position themselves absolutely. Centre a
-thumb on its point with a `translate`.
-
-```scss
-.slider-root {
-  position: relative;
-  display: flex;
-  align-items: center;
-  width: 12rem;
-  height: 1.25rem;
-}
-
-.slider-track {
-  position: relative;
-  flex: 1;
-  height: 0.25rem;
-  border-radius: 9999px;
-  background: #d1d5db;
-}
-
-.slider-range {
-  height: 100%;
-  border-radius: inherit;
-  background: #6366f1;
-}
-
-.slider-thumb {
-  width: 1rem;
-  height: 1rem;
-  border-radius: 50%;
-  background: white;
-  box-shadow: 0 0 0 1px #6366f1;
-  translate: -50% 0;
-
-  &[data-disabled] {
-    opacity: 0.5;
-  }
-}
-```
-
-## Styling hooks
-
-| Attribute | Values | Set on |
-|-----------|--------|--------|
-| `data-orientation` | `"horizontal"` \| `"vertical"` | every part |
-| `data-disabled` | `""` (present when disabled) | every part |
-
-## Validation
-
-`Slider.Root` throws a descriptive error during render when `min` is not less
-than `max`, or when `step` is not greater than `0`.