@grapu-design/react-fieldset 0.1.0

package/lib/index.js

@@ -0,0 +1,12 @@
+import { F as FieldsetDescription, a as FieldsetErrorMessage, b as FieldsetLabel, c as FieldsetRoot } from './Fieldset-12s-CW3j613b.js';
+export { d as FieldsetProvider, u as useFieldset, e as useFieldsetContext } from './Fieldset-12s-CW3j613b.js';
+
+var Fieldset_namespace = {
+  __proto__: null,
+  Description: FieldsetDescription,
+  ErrorMessage: FieldsetErrorMessage,
+  Label: FieldsetLabel,
+  Root: FieldsetRoot
+};
+
+export { Fieldset_namespace as Fieldset, FieldsetDescription, FieldsetErrorMessage, FieldsetLabel, FieldsetRoot };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@grapu-design/react-fieldset",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grapu-design/designsystem.git",
+    "directory": "packages/react-headless/fieldset"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./lib/index.cjs",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rm -rf lib",
+    "build": "bunchee",
+    "lint:publish": "bun publint"
+  },
+  "dependencies": {
+    "@radix-ui/react-compose-refs": "^1.1.2",
+    "@grapu-design/dom-utils": "^0.1.0",
+    "@grapu-design/react-primitive": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Fieldset.namespace.ts

@@ -0,0 +1,10 @@
+export {
+  FieldsetRoot as Root,
+  FieldsetLabel as Label,
+  FieldsetDescription as Description,
+  FieldsetErrorMessage as ErrorMessage,
+  type FieldsetRootProps as RootProps,
+  type FieldsetLabelProps as LabelProps,
+  type FieldsetDescriptionProps as DescriptionProps,
+  type FieldsetErrorMessageProps as ErrorMessageProps,
+} from "./Fieldset";

package/src/Fieldset.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+import { composeRefs } from "@radix-ui/react-compose-refs";
+import { mergeProps } from "@grapu-design/dom-utils";
+import { Primitive, type PrimitiveProps } from "@grapu-design/react-primitive";
+import type * as React from "react";
+import { forwardRef } from "react";
+import { useFieldset } from "./useFieldset";
+import { FieldsetProvider, useFieldsetContext } from "./useFieldsetContext";
+
+export interface FieldsetRootProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const FieldsetRoot = forwardRef<HTMLDivElement, FieldsetRootProps>((props, ref) => {
+  const api = useFieldset();
+  const mergedProps = mergeProps(api.rootProps, props);
+
+  return (
+    <FieldsetProvider value={api}>
+      <Primitive.div ref={ref} {...mergedProps} />
+    </FieldsetProvider>
+  );
+});
+FieldsetRoot.displayName = "FieldsetRoot";
+
+export interface FieldsetLabelProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const FieldsetLabel = forwardRef<HTMLDivElement, FieldsetLabelProps>((props, ref) => {
+  const { refs, labelProps } = useFieldsetContext();
+  const mergedProps = mergeProps(labelProps, props);
+
+  return <Primitive.div ref={composeRefs(refs.label, ref)} {...mergedProps} />;
+});
+FieldsetLabel.displayName = "FieldsetLabel";
+
+export interface FieldsetDescriptionProps
+  extends PrimitiveProps,
+    React.HTMLAttributes<HTMLSpanElement> {}
+
+export const FieldsetDescription = forwardRef<HTMLSpanElement, FieldsetDescriptionProps>(
+  (props, ref) => {
+    const { refs, descriptionProps } = useFieldsetContext();
+    const mergedProps = mergeProps(descriptionProps, props);
+
+    return <Primitive.span ref={composeRefs(refs.description, ref)} {...mergedProps} />;
+  },
+);
+FieldsetDescription.displayName = "FieldsetDescription";
+
+export interface FieldsetErrorMessageProps
+  extends PrimitiveProps,
+    React.HTMLAttributes<HTMLDivElement> {}
+
+export const FieldsetErrorMessage = forwardRef<HTMLDivElement, FieldsetErrorMessageProps>(
+  (props, ref) => {
+    const { refs, errorMessageProps } = useFieldsetContext();
+    const mergedProps = mergeProps(errorMessageProps, props);
+
+    return <Primitive.div ref={composeRefs(refs.errorMessage, ref)} {...mergedProps} />;
+  },
+);
+FieldsetErrorMessage.displayName = "FieldsetErrorMessage";

package/src/dom.ts

@@ -0,0 +1,3 @@
+export const getLabelId = (id: string) => `fieldset:${id}:label`;
+export const getDescriptionId = (id: string) => `fieldset:${id}:description`;
+export const getErrorMessageId = (id: string) => `fieldset:${id}:error-message`;

package/src/index.ts

@@ -0,0 +1,20 @@
+export { useFieldset, type UseFieldsetReturn } from "./useFieldset";
+
+export {
+  FieldsetRoot,
+  FieldsetLabel,
+  FieldsetDescription,
+  FieldsetErrorMessage,
+  type FieldsetRootProps,
+  type FieldsetLabelProps,
+  type FieldsetDescriptionProps,
+  type FieldsetErrorMessageProps,
+} from "./Fieldset";
+
+export {
+  FieldsetProvider,
+  useFieldsetContext,
+  type UseFieldsetContext,
+} from "./useFieldsetContext";
+
+export * as Fieldset from "./Fieldset.namespace";

package/src/useFieldset.test.tsx

@@ -0,0 +1,161 @@
+import "@testing-library/jest-dom/vitest";
+import { cleanup, render } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { forwardRef, type ReactElement, type ReactNode } from "react";
+
+import {
+  FieldsetDescription,
+  FieldsetErrorMessage,
+  FieldsetLabel,
+  FieldsetRoot,
+  type FieldsetRootProps,
+} from "./Fieldset";
+import { getDescriptionId, getErrorMessageId, getLabelId } from "./dom";
+
+afterEach(cleanup);
+
+function setUp(jsx: ReactElement) {
+  return {
+    user: userEvent.setup(),
+    ...render(jsx),
+  };
+}
+
+interface TestFieldsetProps extends FieldsetRootProps {
+  label?: ReactNode;
+  description?: ReactNode;
+  errorMessage?: ReactNode;
+}
+
+const Fieldset = forwardRef<HTMLDivElement, TestFieldsetProps>(
+  ({ label, description, errorMessage, ...rootProps }, ref) => {
+    return (
+      <FieldsetRoot data-testid="fieldset-root" {...rootProps} ref={ref}>
+        {label && <FieldsetLabel data-testid="fieldset-label">{label}</FieldsetLabel>}
+        <div data-testid="fieldset-content">Content</div>
+        {description && (
+          <FieldsetDescription data-testid="fieldset-description">
+            {description}
+          </FieldsetDescription>
+        )}
+        {errorMessage && (
+          <FieldsetErrorMessage data-testid="fieldset-error-message">
+            {errorMessage}
+          </FieldsetErrorMessage>
+        )}
+      </FieldsetRoot>
+    );
+  },
+);
+Fieldset.displayName = "Fieldset";
+
+describe("Fieldset components", () => {
+  describe("basic rendering", () => {
+    it("should render without crashing", () => {
+      const { getByTestId } = setUp(<Fieldset />);
+      expect(getByTestId("fieldset-root")).toBeInTheDocument();
+    });
+
+    it("should render label, description, and error message", () => {
+      const { getByTestId } = setUp(
+        <Fieldset label="Label" description="Description" errorMessage="Error" />,
+      );
+
+      expect(getByTestId("fieldset-label")).toHaveTextContent("Label");
+      expect(getByTestId("fieldset-description")).toHaveTextContent("Description");
+      expect(getByTestId("fieldset-error-message")).toHaveTextContent("Error");
+    });
+  });
+
+  describe("ID generation", () => {
+    it("should generate unique id for label", () => {
+      const { getByTestId } = setUp(<Fieldset label="Label" />);
+
+      const label = getByTestId("fieldset-label");
+      expect(label.id).toMatch(/^fieldset:.+:label$/);
+    });
+  });
+
+  describe("aria attributes", () => {
+    it("should have role=group on root", () => {
+      const { getByTestId } = setUp(<Fieldset />);
+
+      const root = getByTestId("fieldset-root");
+      expect(root).toHaveAttribute("role", "group");
+    });
+
+    it("should set aria-labelledby when label is rendered", () => {
+      const { getByTestId } = setUp(<Fieldset label="Label" />);
+
+      const root = getByTestId("fieldset-root");
+      const label = getByTestId("fieldset-label");
+
+      expect(root).toHaveAttribute("aria-labelledby", label.id);
+    });
+
+    it("should not set aria-labelledby when label is not rendered", () => {
+      const { getByTestId } = setUp(<Fieldset />);
+
+      const root = getByTestId("fieldset-root");
+      expect(root).not.toHaveAttribute("aria-labelledby");
+    });
+
+    it("should set aria-describedby with description id when description is rendered", () => {
+      const { getByTestId } = setUp(<Fieldset description="Description" />);
+
+      const root = getByTestId("fieldset-root");
+      const description = getByTestId("fieldset-description");
+
+      expect(root).toHaveAttribute("aria-describedby", description.id);
+    });
+
+    it("should set aria-describedby with error message id when error is rendered", () => {
+      const { getByTestId } = setUp(<Fieldset errorMessage="Error" />);
+
+      const root = getByTestId("fieldset-root");
+      const errorMessage = getByTestId("fieldset-error-message");
+
+      expect(root).toHaveAttribute("aria-describedby", errorMessage.id);
+    });
+
+    it("should combine description and error in aria-describedby", () => {
+      const { getByTestId } = setUp(<Fieldset description="Description" errorMessage="Error" />);
+
+      const root = getByTestId("fieldset-root");
+      const description = getByTestId("fieldset-description");
+      const errorMessage = getByTestId("fieldset-error-message");
+
+      expect(root).toHaveAttribute("aria-describedby", `${description.id} ${errorMessage.id}`);
+    });
+
+    it("should not set aria-describedby when neither description nor error is rendered", () => {
+      const { getByTestId } = setUp(<Fieldset label="Label" />);
+
+      const root = getByTestId("fieldset-root");
+      expect(root).not.toHaveAttribute("aria-describedby");
+    });
+
+    it("should set aria-live on error message", () => {
+      const { getByTestId } = setUp(<Fieldset errorMessage="Error" />);
+
+      const errorMessage = getByTestId("fieldset-error-message");
+      expect(errorMessage).toHaveAttribute("aria-live", "polite");
+    });
+  });
+});
+
+describe("dom utilities", () => {
+  it("getLabelId should return correct format", () => {
+    expect(getLabelId("test")).toBe("fieldset:test:label");
+  });
+
+  it("getDescriptionId should return correct format", () => {
+    expect(getDescriptionId("test")).toBe("fieldset:test:description");
+  });
+
+  it("getErrorMessageId should return correct format", () => {
+    expect(getErrorMessageId("test")).toBe("fieldset:test:error-message");
+  });
+});

package/src/useFieldset.ts

@@ -0,0 +1,73 @@
+import { useCallback, useId, useState } from "react";
+
+import { elementProps } from "@grapu-design/dom-utils";
+import { getDescriptionId, getErrorMessageId, getLabelId } from "./dom";
+
+export type UseFieldsetReturn = ReturnType<typeof useFieldset>;
+
+export function useFieldset() {
+  const id = useId();
+
+  const [isLabelRendered, setIsLabelRendered] = useState(false);
+  const labelRef = useCallback((node: HTMLElement | null) => {
+    setIsLabelRendered(!!node);
+  }, []);
+
+  const [isDescriptionRendered, setIsDescriptionRendered] = useState(false);
+  const descriptionRef = useCallback((node: HTMLElement | null) => {
+    setIsDescriptionRendered(!!node);
+  }, []);
+
+  const [isErrorMessageRendered, setIsErrorMessageRendered] = useState(false);
+  const errorMessageRef = useCallback((node: HTMLElement | null) => {
+    setIsErrorMessageRendered(!!node);
+  }, []);
+
+  const ariaDescribedBy =
+    [
+      isDescriptionRendered ? getDescriptionId(id) : false,
+      isErrorMessageRendered ? getErrorMessageId(id) : false,
+    ]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  return {
+    id,
+
+    refs: {
+      label: labelRef,
+      description: descriptionRef,
+      errorMessage: errorMessageRef,
+    },
+
+    renderedElements: {
+      label: isLabelRendered,
+      description: isDescriptionRendered,
+      errorMessage: isErrorMessageRendered,
+    },
+
+    rootProps: elementProps({
+      // see: https://w3c.github.io/aria/#group
+      role: "group",
+
+      // note: aria-disabled is supported but useFieldset doesn't know about the disabled state of its children
+      // note: aria-required and aria-invalid should not be set here
+
+      ...(isLabelRendered && { "aria-labelledby": getLabelId(id) }),
+      "aria-describedby": ariaDescribedBy,
+    }),
+
+    labelProps: elementProps({
+      id: getLabelId(id),
+    }),
+
+    descriptionProps: elementProps({
+      id: getDescriptionId(id),
+    }),
+
+    errorMessageProps: elementProps({
+      id: getErrorMessageId(id),
+      "aria-live": "polite",
+    }),
+  };
+}

package/src/useFieldsetContext.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+import type { UseFieldsetReturn } from "./useFieldset";
+
+export interface UseFieldsetContext extends UseFieldsetReturn {}
+
+const FieldsetContext = createContext<UseFieldsetContext | null>(null);
+
+export const FieldsetProvider = FieldsetContext.Provider;
+
+export function useFieldsetContext<T extends boolean | undefined = true>({
+  strict = true,
+}: {
+  strict?: T;
+} = {}): T extends false ? UseFieldsetContext | null : UseFieldsetContext {
+  const context = useContext(FieldsetContext);
+  if (!context && strict) {
+    throw new Error("useFieldsetContext must be used within a Fieldset");
+  }
+
+  return context as UseFieldsetContext;
+}