@arun-dev/headless 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arun Tripathi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,161 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  booleanAttribute: () => booleanAttribute,
+  getStateAttributes: () => getStateAttributes,
+  mergeProps: () => mergeProps,
+  useControlled: () => useControlled,
+  useRender: () => useRender
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/mergeProps.ts
+function isEventHandler(key) {
+  return key.length > 2 && key.startsWith("on") && key[2] === key[2]?.toUpperCase();
+}
+function mergeRefs(...refs) {
+  return (node) => {
+    const cleanups = refs.map((ref) => {
+      if (typeof ref === "function") {
+        const result = ref(node);
+        return typeof result === "function" ? result : () => ref(null);
+      }
+      if (ref && typeof ref === "object") {
+        ref.current = node;
+        return () => {
+          ref.current = null;
+        };
+      }
+      return void 0;
+    });
+    return () => {
+      cleanups.forEach((cleanup) => {
+        if (typeof cleanup === "function") cleanup();
+      });
+    };
+  };
+}
+function mergeProps(...objects) {
+  const merged = {};
+  for (const props of objects) {
+    if (!props) continue;
+    for (const key of Object.keys(props)) {
+      const value = props[key];
+      if (value === void 0) continue;
+      if (isEventHandler(key) && typeof value === "function") {
+        const existing = merged[key];
+        merged[key] = typeof existing === "function" ? (...args) => {
+          existing(...args);
+          value(...args);
+        } : value;
+      } else if (key === "className") {
+        merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
+      } else if (key === "style") {
+        merged.style = { ...merged.style, ...value };
+      } else if (key === "ref") {
+        merged.ref = merged.ref ? mergeRefs(merged.ref, value) : value;
+      } else {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+// src/core/useRender.ts
+var import_react = require("react");
+
+// src/core/stateAttributes.ts
+function getStateAttributes(state, mapping) {
+  if (!mapping) return {};
+  const attributes = {};
+  for (const key of Object.keys(state)) {
+    const toAttributes = mapping[key];
+    if (!toAttributes) continue;
+    const result = toAttributes(state[key]);
+    if (result) Object.assign(attributes, result);
+  }
+  return attributes;
+}
+function booleanAttribute(whenTrue, whenFalse) {
+  return (value) => {
+    if (value) return { [whenTrue]: "" };
+    return whenFalse ? { [whenFalse]: "" } : null;
+  };
+}
+
+// src/core/useRender.ts
+function useRender({
+  render,
+  defaultTagName,
+  props,
+  state,
+  stateAttributes
+}) {
+  const attributes = state ? getStateAttributes(state, stateAttributes) : {};
+  const merged = mergeProps(attributes, ...props);
+  if ((0, import_react.isValidElement)(render)) {
+    return (0, import_react.cloneElement)(render, mergeProps(merged, render.props));
+  }
+  return (0, import_react.createElement)(defaultTagName, merged);
+}
+
+// src/core/useControlled.ts
+var import_react2 = require("react");
+function useControlled({
+  controlled,
+  default: defaultValue,
+  name = "Component",
+  state = "value"
+}) {
+  const { current: isControlled } = (0, import_react2.useRef)(controlled !== void 0);
+  const [uncontrolled, setUncontrolled] = (0, import_react2.useState)(defaultValue);
+  const defaultRef = (0, import_react2.useRef)(defaultValue);
+  const value = isControlled ? controlled : uncontrolled;
+  if (process.env.NODE_ENV !== "production") {
+    if (isControlled !== (controlled !== void 0)) {
+      console.error(
+        `${name}: cannot switch between controlled and uncontrolled \`${state}\`. Decide which one this component is for the whole of its life.`
+      );
+    }
+    if (!isControlled && defaultRef.current !== defaultValue) {
+      console.error(
+        `${name}: cannot change the default \`${state}\` after mount. It is only read once, so later changes are silently ignored.`
+      );
+    }
+  }
+  const setValue = (0, import_react2.useCallback)(
+    (next) => {
+      if (!isControlled) setUncontrolled(next);
+    },
+    [isControlled]
+  );
+  return [value, setValue];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  booleanAttribute,
+  getStateAttributes,
+  mergeProps,
+  useControlled,
+  useRender
+});

package/dist/index.d.cts

@@ -0,0 +1,99 @@
+import { ReactElement } from 'react';
+
+/**
+ * Prop merging for headless components.
+ *
+ * A component and its consumer both want to put things on the same element. Naive
+ * spreading lets whichever runs last silently destroy the other's behaviour, so each
+ * kind of prop is combined rather than replaced.
+ */
+type UnknownProps = Record<string, unknown>;
+/**
+ * Merge prop objects left to right. Later objects win for plain values, but:
+ * - event handlers are chained rather than replaced
+ * - className is concatenated
+ * - style is shallow-merged
+ * - refs are merged
+ *
+ * `undefined` values are skipped, so an absent key on a later object never
+ * clobbers a value set by an earlier one.
+ */
+declare function mergeProps(...objects: (UnknownProps | undefined)[]): UnknownProps;
+
+/**
+ * Projects a component's state onto the DOM as `data-*` attributes.
+ *
+ * This is the contract between behaviour and styling. A headless component owns no
+ * class names, so the only way CSS can react to `checked` or `disabled` is for the
+ * state to be visible in the DOM:
+ *
+ *   .switch[data-checked] { background: var(--switch-track-bg-checked); }
+ *
+ * Doing it through a declared mapping rather than by hand keeps the attributes
+ * consistent across components — Base UI's Checkbox emits eleven of them, which is
+ * not something anyone maintains by hand — and makes the state a component exposes
+ * a single readable object rather than scattered JSX.
+ */
+/**
+ * Maps one state value to the attributes it should produce. Return `null` for
+ * "no attribute". A single value may produce several, and mutually exclusive
+ * attributes are how a third state stays addressable: with only `data-checked`,
+ * `:not([data-checked])` would match both unchecked *and* indeterminate.
+ */
+type StateAttributeMapping<State> = {
+    [Key in keyof State]?: (value: State[Key]) => Record<string, string> | null;
+};
+declare function getStateAttributes<State extends Record<string, unknown>>(state: State, mapping: StateAttributeMapping<State> | undefined): UnknownProps;
+/**
+ * The common case: a boolean that emits one attribute when true and another when
+ * false, so both sides are addressable at equal specificity.
+ *
+ *   checked: booleanAttribute('data-checked', 'data-unchecked')
+ */
+declare function booleanAttribute(whenTrue: string, whenFalse?: string): (value: unknown) => Record<string, string> | null;
+
+/**
+ * Resolves what a component part actually renders.
+ *
+ * Every part goes through here, which is what makes the whole library consistent:
+ * one place decides how props merge, how state reaches the DOM, and what element
+ * comes out. A part supplies its default element, its state, and the props it wants;
+ * the consumer can replace the element entirely via `render` without losing any of it.
+ *
+ * Currently uses no hooks. The `use` prefix matches the API it will grow into
+ * (memoised merging, so parts stop re-rendering their children needlessly) and keeps
+ * call sites stable when that lands.
+ */
+interface UseRenderParams<State extends Record<string, unknown>> {
+    /** Element to render instead of the default. Props, className and ref are merged onto it. */
+    render?: ReactElement | undefined;
+    /** Tag rendered when `render` is not supplied. */
+    defaultTagName: string;
+    /** Prop objects to merge, in precedence order (later wins). */
+    props: (UnknownProps | undefined)[];
+    /** The part's state, projected onto the DOM through `stateAttributes`. */
+    state?: State;
+    /** How each state field becomes `data-*` attributes. */
+    stateAttributes?: StateAttributeMapping<State>;
+}
+declare function useRender<State extends Record<string, unknown> = Record<string, never>>({ render, defaultTagName, props, state, stateAttributes, }: UseRenderParams<State>): ReactElement;
+
+/**
+ * Supports both controlled and uncontrolled use of a single value.
+ *
+ * The mode is decided once, at mount, and never re-evaluated. Recomputing it per
+ * render would let a parent that briefly passes `undefined` flip the component to
+ * uncontrolled and hand it stale internal state — a bug that is very hard to see.
+ *
+ * In controlled mode the setter deliberately does not write state: the parent owns
+ * the value. Callers still fire their `onChange` in both modes, so the component
+ * notifies either way.
+ */
+declare function useControlled<T>({ controlled, default: defaultValue, name, state, }: {
+    controlled: T | undefined;
+    default: T;
+    name?: string;
+    state?: string;
+}): [T, (next: T) => void];
+
+export { type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, getStateAttributes, mergeProps, useControlled, useRender };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { ReactElement } from 'react';
+
+/**
+ * Prop merging for headless components.
+ *
+ * A component and its consumer both want to put things on the same element. Naive
+ * spreading lets whichever runs last silently destroy the other's behaviour, so each
+ * kind of prop is combined rather than replaced.
+ */
+type UnknownProps = Record<string, unknown>;
+/**
+ * Merge prop objects left to right. Later objects win for plain values, but:
+ * - event handlers are chained rather than replaced
+ * - className is concatenated
+ * - style is shallow-merged
+ * - refs are merged
+ *
+ * `undefined` values are skipped, so an absent key on a later object never
+ * clobbers a value set by an earlier one.
+ */
+declare function mergeProps(...objects: (UnknownProps | undefined)[]): UnknownProps;
+
+/**
+ * Projects a component's state onto the DOM as `data-*` attributes.
+ *
+ * This is the contract between behaviour and styling. A headless component owns no
+ * class names, so the only way CSS can react to `checked` or `disabled` is for the
+ * state to be visible in the DOM:
+ *
+ *   .switch[data-checked] { background: var(--switch-track-bg-checked); }
+ *
+ * Doing it through a declared mapping rather than by hand keeps the attributes
+ * consistent across components — Base UI's Checkbox emits eleven of them, which is
+ * not something anyone maintains by hand — and makes the state a component exposes
+ * a single readable object rather than scattered JSX.
+ */
+/**
+ * Maps one state value to the attributes it should produce. Return `null` for
+ * "no attribute". A single value may produce several, and mutually exclusive
+ * attributes are how a third state stays addressable: with only `data-checked`,
+ * `:not([data-checked])` would match both unchecked *and* indeterminate.
+ */
+type StateAttributeMapping<State> = {
+    [Key in keyof State]?: (value: State[Key]) => Record<string, string> | null;
+};
+declare function getStateAttributes<State extends Record<string, unknown>>(state: State, mapping: StateAttributeMapping<State> | undefined): UnknownProps;
+/**
+ * The common case: a boolean that emits one attribute when true and another when
+ * false, so both sides are addressable at equal specificity.
+ *
+ *   checked: booleanAttribute('data-checked', 'data-unchecked')
+ */
+declare function booleanAttribute(whenTrue: string, whenFalse?: string): (value: unknown) => Record<string, string> | null;
+
+/**
+ * Resolves what a component part actually renders.
+ *
+ * Every part goes through here, which is what makes the whole library consistent:
+ * one place decides how props merge, how state reaches the DOM, and what element
+ * comes out. A part supplies its default element, its state, and the props it wants;
+ * the consumer can replace the element entirely via `render` without losing any of it.
+ *
+ * Currently uses no hooks. The `use` prefix matches the API it will grow into
+ * (memoised merging, so parts stop re-rendering their children needlessly) and keeps
+ * call sites stable when that lands.
+ */
+interface UseRenderParams<State extends Record<string, unknown>> {
+    /** Element to render instead of the default. Props, className and ref are merged onto it. */
+    render?: ReactElement | undefined;
+    /** Tag rendered when `render` is not supplied. */
+    defaultTagName: string;
+    /** Prop objects to merge, in precedence order (later wins). */
+    props: (UnknownProps | undefined)[];
+    /** The part's state, projected onto the DOM through `stateAttributes`. */
+    state?: State;
+    /** How each state field becomes `data-*` attributes. */
+    stateAttributes?: StateAttributeMapping<State>;
+}
+declare function useRender<State extends Record<string, unknown> = Record<string, never>>({ render, defaultTagName, props, state, stateAttributes, }: UseRenderParams<State>): ReactElement;
+
+/**
+ * Supports both controlled and uncontrolled use of a single value.
+ *
+ * The mode is decided once, at mount, and never re-evaluated. Recomputing it per
+ * render would let a parent that briefly passes `undefined` flip the component to
+ * uncontrolled and hand it stale internal state — a bug that is very hard to see.
+ *
+ * In controlled mode the setter deliberately does not write state: the parent owns
+ * the value. Callers still fire their `onChange` in both modes, so the component
+ * notifies either way.
+ */
+declare function useControlled<T>({ controlled, default: defaultValue, name, state, }: {
+    controlled: T | undefined;
+    default: T;
+    name?: string;
+    state?: string;
+}): [T, (next: T) => void];
+
+export { type StateAttributeMapping, type UnknownProps, type UseRenderParams, booleanAttribute, getStateAttributes, mergeProps, useControlled, useRender };

package/dist/index.js

@@ -0,0 +1,130 @@
+// src/core/mergeProps.ts
+function isEventHandler(key) {
+  return key.length > 2 && key.startsWith("on") && key[2] === key[2]?.toUpperCase();
+}
+function mergeRefs(...refs) {
+  return (node) => {
+    const cleanups = refs.map((ref) => {
+      if (typeof ref === "function") {
+        const result = ref(node);
+        return typeof result === "function" ? result : () => ref(null);
+      }
+      if (ref && typeof ref === "object") {
+        ref.current = node;
+        return () => {
+          ref.current = null;
+        };
+      }
+      return void 0;
+    });
+    return () => {
+      cleanups.forEach((cleanup) => {
+        if (typeof cleanup === "function") cleanup();
+      });
+    };
+  };
+}
+function mergeProps(...objects) {
+  const merged = {};
+  for (const props of objects) {
+    if (!props) continue;
+    for (const key of Object.keys(props)) {
+      const value = props[key];
+      if (value === void 0) continue;
+      if (isEventHandler(key) && typeof value === "function") {
+        const existing = merged[key];
+        merged[key] = typeof existing === "function" ? (...args) => {
+          existing(...args);
+          value(...args);
+        } : value;
+      } else if (key === "className") {
+        merged.className = merged.className ? `${String(merged.className)} ${String(value)}` : value;
+      } else if (key === "style") {
+        merged.style = { ...merged.style, ...value };
+      } else if (key === "ref") {
+        merged.ref = merged.ref ? mergeRefs(merged.ref, value) : value;
+      } else {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+// src/core/useRender.ts
+import { cloneElement, createElement, isValidElement } from "react";
+
+// src/core/stateAttributes.ts
+function getStateAttributes(state, mapping) {
+  if (!mapping) return {};
+  const attributes = {};
+  for (const key of Object.keys(state)) {
+    const toAttributes = mapping[key];
+    if (!toAttributes) continue;
+    const result = toAttributes(state[key]);
+    if (result) Object.assign(attributes, result);
+  }
+  return attributes;
+}
+function booleanAttribute(whenTrue, whenFalse) {
+  return (value) => {
+    if (value) return { [whenTrue]: "" };
+    return whenFalse ? { [whenFalse]: "" } : null;
+  };
+}
+
+// src/core/useRender.ts
+function useRender({
+  render,
+  defaultTagName,
+  props,
+  state,
+  stateAttributes
+}) {
+  const attributes = state ? getStateAttributes(state, stateAttributes) : {};
+  const merged = mergeProps(attributes, ...props);
+  if (isValidElement(render)) {
+    return cloneElement(render, mergeProps(merged, render.props));
+  }
+  return createElement(defaultTagName, merged);
+}
+
+// src/core/useControlled.ts
+import { useCallback, useRef, useState } from "react";
+function useControlled({
+  controlled,
+  default: defaultValue,
+  name = "Component",
+  state = "value"
+}) {
+  const { current: isControlled } = useRef(controlled !== void 0);
+  const [uncontrolled, setUncontrolled] = useState(defaultValue);
+  const defaultRef = useRef(defaultValue);
+  const value = isControlled ? controlled : uncontrolled;
+  if (process.env.NODE_ENV !== "production") {
+    if (isControlled !== (controlled !== void 0)) {
+      console.error(
+        `${name}: cannot switch between controlled and uncontrolled \`${state}\`. Decide which one this component is for the whole of its life.`
+      );
+    }
+    if (!isControlled && defaultRef.current !== defaultValue) {
+      console.error(
+        `${name}: cannot change the default \`${state}\` after mount. It is only read once, so later changes are silently ignored.`
+      );
+    }
+  }
+  const setValue = useCallback(
+    (next) => {
+      if (!isControlled) setUncontrolled(next);
+    },
+    [isControlled]
+  );
+  return [value, setValue];
+}
+export {
+  booleanAttribute,
+  getStateAttributes,
+  mergeProps,
+  useControlled,
+  useRender
+};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@arun-dev/headless",
+  "version": "0.1.0",
+  "description": "Unstyled React behaviour primitives — the render engine and state plumbing @arun-dev/ui is built on. Ships no CSS and no class names.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arun9483/arun-design-system.git",
+    "directory": "packages/headless"
+  },
+  "keywords": [
+    "react",
+    "headless",
+    "unstyled",
+    "design-system",
+    "primitives"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@types/react": ">=19.0.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "eslint": "9.39.4",
+    "jsdom": "27.0.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "3.2.6",
+    "@arun-dev/config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist .turbo",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "pnpm run test:unit",
+    "test:unit": "vitest run --passWithNoTests --config vitest.unit.config.ts"
+  }
+}