@tripleform/utils 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qualifine
+
+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/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @tripleform/utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Провайдер темы и низкоуровневые React-хуки Tripleform UI.
+
+```bash
+pnpm add @tripleform/utils @tripleform/core
+```
+
+## TripleformUIProvider
+
+```tsx
+import { TripleformUIProvider } from "@tripleform/utils";
+import "@tripleform/core/primitives.css";
+import "@tripleform/core/foundation.css";
+import "@tripleform/core/themes/dark.css";
+
+export function Example() {
+  return <TripleformUIProvider theme="dark"><span>Приложение</span></TripleformUIProvider>;
+}
+```
+
+| Свойство | Контракт |
+|---|---|
+| children | Содержимое приложения, ReactNode |
+| theme | light/dark, ставит data-theme контейнеру |
+| tokens | TokenOverrides из @tripleform/core; глобальные CSS-переопределения |
+| className | Класс контейнера div с display: contents |
+
+DOM-ref провайдера не экспортируется. tokens применяются к document.documentElement,
+а не только к children. При cleanup свойства удаляются без восстановления прежних
+значений; несколько провайдеров требуют координации. theme не загружает CSS автоматически.
+
+## Хуки
+
+| Экспорт | Контракт и ограничения |
+|---|---|
+| `useControlled<T>({ controlled, default })` | Возвращает [value, setter]. Режим фиксируется на первом рендере. В controlled-режиме setter не меняет значение и не вызывает callback владельца |
+| `useFocusTrap(active)` | Возвращает ref HTMLElement. При активации фокусирует первый доступный элемент и зацикливает Tab/Shift+Tab, при cleanup возвращает прежний фокус. Список элементов фиксируется при активации |
+| `useMediaQuery(query)` | Возвращает boolean для window.matchMedia. На сервере false; после гидратации значение может измениться. Подписка обновляется при смене query |
+
+Не используйте useFocusTrap поверх готовых Modal/Drawer: их управление фокусом уже
+реализовано. Низкоуровневый хук не заменяет доступный диалог и блокировку фонового содержимого.
+Полные правила использования ДС — в [руководстве потребителя](../react/CONSUMER_GUIDE.md).

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { TokenOverrides } from '@tripleform/core';
+
+interface TripleformUIProviderProps {
+    /** Дочернее содержимое приложения. */
+    children: ReactNode;
+    /** Глобальные переопределения document.documentElement; cleanup удаляет их без восстановления прежних значений. */
+    tokens?: TokenOverrides;
+    /** Устанавливает data-theme контейнеру; не изолирует глобальные tokens. */
+    theme?: "light" | "dark";
+    /** Класс контейнера с display: contents. */
+    className?: string;
+}
+/** Провайдер темы и глобальных переопределений токенов. DOM-ref не экспортируется. Несколько tokens-провайдеров требуют координации: их эффекты не изолированы поддеревом. */
+declare function TripleformUIProvider({ children, tokens, theme, className, }: TripleformUIProviderProps): react.JSX.Element;
+
+/** Возвращает ref контейнера. При active переводит фокус на первый доступный элемент, зацикливает Tab/Shift+Tab и возвращает прежний фокус при cleanup. Не добавляйте этот хук поверх готового Modal/Drawer: их механизмы уже управляют фокусом. Набор фокусируемых элементов фиксируется при активации. */
+declare function useFocusTrap(active: boolean): react.RefObject<HTMLElement>;
+
+interface UseControlledParams<T> {
+    controlled: T | undefined;
+    default: T;
+}
+/** Возвращает пару [значение, setter]. Режим определяется первым controlled: undefined означает внутреннее состояние из default. В controlled-режиме setter не меняет значение и не вызывает внешний callback. Не переключайте режим после монтирования. */
+declare function useControlled<T>({ controlled, default: defaultValue, }: UseControlledParams<T>): [T, (value: T) => void];
+
+/** Подписывается на window.matchMedia(query) и возвращает boolean. При SSR начальное значение false; на клиенте возможна смена после гидратации. query — корректное CSS media query; обработчик change удаляется при cleanup. */
+declare function useMediaQuery(query: string): boolean;
+
+export { TripleformUIProvider, useControlled, useFocusTrap, useMediaQuery };

package/dist/index.js

@@ -0,0 +1,118 @@
+// src/TripleformUIProvider.tsx
+import { useEffect } from "react";
+import { jsx } from "react/jsx-runtime";
+function TripleformUIProvider({
+  children,
+  tokens,
+  theme,
+  className
+}) {
+  useEffect(() => {
+    if (!tokens) return;
+    const root = document.documentElement;
+    const entries = Object.entries(tokens);
+    entries.forEach(([name, value]) => {
+      root.style.setProperty(name, value);
+    });
+    return () => {
+      entries.forEach(([name]) => {
+        root.style.removeProperty(name);
+      });
+    };
+  }, [tokens]);
+  return /* @__PURE__ */ jsx("div", { "data-theme": theme, className, style: { display: "contents" }, children });
+}
+
+// src/hooks/useFocusTrap.ts
+import { useEffect as useEffect2, useRef } from "react";
+var FOCUSABLE_SELECTORS = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+  "details > summary"
+].join(", ");
+function useFocusTrap(active) {
+  const containerRef = useRef(null);
+  useEffect2(() => {
+    if (!active || !containerRef.current) return;
+    const container = containerRef.current;
+    const focusableElements = Array.from(
+      container.querySelectorAll(FOCUSABLE_SELECTORS)
+    );
+    const firstElement = focusableElements[0];
+    const lastElement = focusableElements[focusableElements.length - 1];
+    const previouslyFocused = document.activeElement;
+    firstElement?.focus();
+    function handleKeyDown(event) {
+      if (event.key !== "Tab") return;
+      if (event.shiftKey) {
+        if (document.activeElement === firstElement) {
+          event.preventDefault();
+          lastElement?.focus();
+        }
+      } else {
+        if (document.activeElement === lastElement) {
+          event.preventDefault();
+          firstElement?.focus();
+        }
+      }
+    }
+    container.addEventListener("keydown", handleKeyDown);
+    return () => {
+      container.removeEventListener("keydown", handleKeyDown);
+      previouslyFocused?.focus();
+    };
+  }, [active]);
+  return containerRef;
+}
+
+// src/hooks/useControlled.ts
+import { useCallback, useRef as useRef2, useState } from "react";
+function useControlled({
+  controlled,
+  default: defaultValue
+}) {
+  const isControlled = useRef2(controlled !== void 0);
+  const [uncontrolledState, setUncontrolledState] = useState(defaultValue);
+  const value = isControlled.current ? controlled : uncontrolledState;
+  const setValue = useCallback(
+    (newValue) => {
+      if (!isControlled.current) {
+        setUncontrolledState(newValue);
+      }
+    },
+    []
+  );
+  return [value, setValue];
+}
+
+// src/hooks/useMediaQuery.ts
+import { useEffect as useEffect3, useState as useState2 } from "react";
+function useMediaQuery(query) {
+  const [matches, setMatches] = useState2(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia(query).matches;
+  });
+  useEffect3(() => {
+    if (typeof window === "undefined") return;
+    const mediaQueryList = window.matchMedia(query);
+    setMatches(mediaQueryList.matches);
+    function handleChange(event) {
+      setMatches(event.matches);
+    }
+    mediaQueryList.addEventListener("change", handleChange);
+    return () => {
+      mediaQueryList.removeEventListener("change", handleChange);
+    };
+  }, [query]);
+  return matches;
+}
+export {
+  TripleformUIProvider,
+  useControlled,
+  useFocusTrap,
+  useMediaQuery
+};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@tripleform/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Tripleform UI — provider, hooks and utilities",
+  "license": "MIT",
+  "author": "Qualifine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArthurIvanov/tripleform.git",
+    "directory": "products/tripleform-ui/packages/utils"
+  },
+  "homepage": "https://github.com/ArthurIvanov/tripleform/tree/master/products/tripleform-ui#readme",
+  "bugs": {
+    "url": "https://github.com/ArthurIvanov/tripleform/issues"
+  },
+  "keywords": [
+    "design-system",
+    "react",
+    "hooks",
+    "provider"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tripleform/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external react,react-dom",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }

package/src/TripleformUIProvider.tsx

@@ -0,0 +1,44 @@
+import { useEffect, type ReactNode } from "react";
+import type { TokenOverrides } from "@tripleform/core";
+
+interface TripleformUIProviderProps {
+  /** Дочернее содержимое приложения. */
+  children: ReactNode;
+  /** Глобальные переопределения document.documentElement; cleanup удаляет их без восстановления прежних значений. */
+  tokens?: TokenOverrides;
+  /** Устанавливает data-theme контейнеру; не изолирует глобальные tokens. */
+  theme?: "light" | "dark";
+  /** Класс контейнера с display: contents. */
+  className?: string;
+}
+
+/** Провайдер темы и глобальных переопределений токенов. DOM-ref не экспортируется. Несколько tokens-провайдеров требуют координации: их эффекты не изолированы поддеревом. */
+export function TripleformUIProvider({
+  children,
+  tokens,
+  theme,
+  className,
+}: TripleformUIProviderProps) {
+  useEffect(() => {
+    if (!tokens) return;
+
+    const root = document.documentElement;
+    const entries = Object.entries(tokens);
+
+    entries.forEach(([name, value]) => {
+      root.style.setProperty(name, value);
+    });
+
+    return () => {
+      entries.forEach(([name]) => {
+        root.style.removeProperty(name);
+      });
+    };
+  }, [tokens]);
+
+  return (
+    <div data-theme={theme} className={className} style={{ display: "contents" }}>
+      {children}
+    </div>
+  );
+}

package/src/hooks/useControlled.ts

@@ -0,0 +1,28 @@
+import { useCallback, useRef, useState } from "react";
+
+interface UseControlledParams<T> {
+  controlled: T | undefined;
+  default: T;
+}
+
+/** Возвращает пару [значение, setter]. Режим определяется первым controlled: undefined означает внутреннее состояние из default. В controlled-режиме setter не меняет значение и не вызывает внешний callback. Не переключайте режим после монтирования. */
+export function useControlled<T>({
+  controlled,
+  default: defaultValue,
+}: UseControlledParams<T>): [T, (value: T) => void] {
+  const isControlled = useRef(controlled !== undefined);
+  const [uncontrolledState, setUncontrolledState] = useState<T>(defaultValue);
+
+  const value = isControlled.current ? (controlled as T) : uncontrolledState;
+
+  const setValue = useCallback(
+    (newValue: T) => {
+      if (!isControlled.current) {
+        setUncontrolledState(newValue);
+      }
+    },
+    [],
+  );
+
+  return [value, setValue];
+}

package/src/hooks/useFocusTrap.ts

@@ -0,0 +1,56 @@
+import { useEffect, useRef } from "react";
+
+const FOCUSABLE_SELECTORS = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+  "details > summary",
+].join(", ");
+
+/** Возвращает ref контейнера. При active переводит фокус на первый доступный элемент, зацикливает Tab/Shift+Tab и возвращает прежний фокус при cleanup. Не добавляйте этот хук поверх готового Modal/Drawer: их механизмы уже управляют фокусом. Набор фокусируемых элементов фиксируется при активации. */
+export function useFocusTrap(active: boolean) {
+  const containerRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (!active || !containerRef.current) return;
+
+    const container = containerRef.current;
+    const focusableElements = Array.from(
+      container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTORS),
+    );
+
+    const firstElement = focusableElements[0];
+    const lastElement = focusableElements[focusableElements.length - 1];
+
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    firstElement?.focus();
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key !== "Tab") return;
+
+      if (event.shiftKey) {
+        if (document.activeElement === firstElement) {
+          event.preventDefault();
+          lastElement?.focus();
+        }
+      } else {
+        if (document.activeElement === lastElement) {
+          event.preventDefault();
+          firstElement?.focus();
+        }
+      }
+    }
+
+    container.addEventListener("keydown", handleKeyDown);
+
+    return () => {
+      container.removeEventListener("keydown", handleKeyDown);
+      previouslyFocused?.focus();
+    };
+  }, [active]);
+
+  return containerRef;
+}

package/src/hooks/useMediaQuery.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState } from "react";
+
+/** Подписывается на window.matchMedia(query) и возвращает boolean. При SSR начальное значение false; на клиенте возможна смена после гидратации. query — корректное CSS media query; обработчик change удаляется при cleanup. */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState<boolean>(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia(query).matches;
+  });
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const mediaQueryList = window.matchMedia(query);
+    setMatches(mediaQueryList.matches);
+
+    function handleChange(event: MediaQueryListEvent) {
+      setMatches(event.matches);
+    }
+
+    mediaQueryList.addEventListener("change", handleChange);
+    return () => {
+      mediaQueryList.removeEventListener("change", handleChange);
+    };
+  }, [query]);
+
+  return matches;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { TripleformUIProvider } from "./TripleformUIProvider";
+export { useFocusTrap } from "./hooks/useFocusTrap";
+export { useControlled } from "./hooks/useControlled";
+export { useMediaQuery } from "./hooks/useMediaQuery";