@hh.ru/magritte-internal-default-props-context 1.0.1

package/index.d.ts

@@ -0,0 +1,54 @@
+import { type FC, type ReactNode } from 'react';
+export interface BoundDefaultPropsContextProps<P> {
+    props: Partial<P>;
+    /**
+     * Если `true`, заданные здесь пропсы форсируются: по пересекающимся ключам они побеждают
+     * любой вложенный (внутренний) провайдер, а не наоборот. Между несколькими `important`
+     * побеждает самый внешний. Влияет только на ключи, перечисленные в `props`.
+     * Явные пропсы на самом компоненте по-прежнему перекрывают любой дефолт.
+     * @default false
+     */
+    important?: boolean;
+    children?: ReactNode;
+}
+/**
+ * Результат `createDefaultPropsContext`: провайдер с забинженным типом пропсов и хук для чтения.
+ */
+export interface DefaultPropsContextBundle<P> {
+    /** Провайдер дефолтных пропсов — тип пропсов забинжен фабрикой. */
+    DefaultPropsContext: FC<BoundDefaultPropsContextProps<P>>;
+    /** Хук для чтения смёрженных дефолтов из ближайшего провайдера этого бандла. */
+    useDefaultProps: () => Partial<P>;
+}
+/**
+ * Фабрика, создающая изолированный `DefaultPropsContext` и хук чтения, параметризованные типом пропсов `P`.
+ *
+ * Контекст создаётся один раз на вызов фабрики и живёт в замыкании модуля компонента, поэтому провайдер
+ * и читающий хук гарантированно делят один и тот же объект контекста, даже если центральный пакет
+ * задублирован по версиям в дереве зависимостей. Каждый компонент создаёт свой бандл в своём пакете
+ * и экспортирует наружу только провайдер, оставляя хук внутренней деталью реализации.
+ *
+ * Мерж дефолтов выполняется в провайдере (один раз на провайдер), поэтому потребитель читает готовое
+ * значение со стабильной ссылкой между рендерами.
+ *
+ * Вызывать строго один раз на уровне модуля (не внутри рендера) — иначе на каждый рендер будет новый контекст.
+ *
+ * @param name — имя компонента для `displayName` провайдера в React DevTools (необязательно).
+ *
+ * @example
+ * ```tsx
+ * // в пакете иконок, внутренний модуль
+ * const { DefaultPropsContext: IconDefaultPropsContext, useDefaultProps: useIconDefaultProps } =
+ *     createDefaultPropsContext<IconProps>('Icon');
+ *
+ * export { IconDefaultPropsContext };
+ *
+ * // Icon.tsx
+ * const Icon: FC<IconProps> = (props) => {
+ *     const defaults = useIconDefaultProps();
+ *     const { size = 'medium', ...rest } = { ...defaults, ...props };
+ *     // ...
+ * };
+ * ```
+ */
+export declare const createDefaultPropsContext: <P>(name?: string) => DefaultPropsContextBundle<P>;

package/index.js

@@ -0,0 +1,103 @@
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useContext, useMemo, useRef } from 'react';
+
+const shallowEqual = (a, b) => {
+    if (a === b) {
+        return true;
+    }
+    let countA = 0;
+    for (const key in a) {
+        if (!Object.is(a[key], b[key])) {
+            return false;
+        }
+        countA += 1;
+    }
+    for (const _ in b) {
+        countA -= 1;
+        if (countA < 0) {
+            return false;
+        }
+    }
+    return true;
+};
+const useShallowMemo = (value) => {
+    const ref = useRef(value);
+    if (!shallowEqual(ref.current, value)) {
+        ref.current = value;
+    }
+    return ref.current;
+};
+const EMPTY_DEFAULTS = { values: {}, importantKeys: new Set() };
+/**
+ * Инкрементальная свёртка «родитель + пропсы провайдера» сверху вниз.
+ *
+ * Для каждого ключа провайдера:
+ * - если ключ уже зафиксирован `important` снаружи — пропускаем (внешний `important` побеждает);
+ * - иначе записываем значение (обычный внутренний так перекрывает обычный внешний, т.к. идём сверху вниз);
+ * - если провайдер `important` — дополнительно фиксируем ключ, чтобы внутренние провайдеры его не перебили.
+ *
+ * Эквивалентно полному обходу цепочки на чтении, но считается один раз на провайдер, а не на потребителя.
+ */
+const foldDefaults = (parent, props, important) => {
+    const values = { ...parent.values };
+    let importantKeys = parent.importantKeys;
+    for (const key in props) {
+        // Ключ, уже зафиксированный important-провайдером снаружи, не трогаем — внешний important побеждает.
+        if (!parent.importantKeys.has(key)) {
+            values[key] = props[key];
+            if (important) {
+                if (importantKeys === parent.importantKeys) {
+                    importantKeys = new Set(parent.importantKeys);
+                }
+                importantKeys.add(key);
+            }
+        }
+    }
+    return { values, importantKeys };
+};
+/**
+ * Фабрика, создающая изолированный `DefaultPropsContext` и хук чтения, параметризованные типом пропсов `P`.
+ *
+ * Контекст создаётся один раз на вызов фабрики и живёт в замыкании модуля компонента, поэтому провайдер
+ * и читающий хук гарантированно делят один и тот же объект контекста, даже если центральный пакет
+ * задублирован по версиям в дереве зависимостей. Каждый компонент создаёт свой бандл в своём пакете
+ * и экспортирует наружу только провайдер, оставляя хук внутренней деталью реализации.
+ *
+ * Мерж дефолтов выполняется в провайдере (один раз на провайдер), поэтому потребитель читает готовое
+ * значение со стабильной ссылкой между рендерами.
+ *
+ * Вызывать строго один раз на уровне модуля (не внутри рендера) — иначе на каждый рендер будет новый контекст.
+ *
+ * @param name — имя компонента для `displayName` провайдера в React DevTools (необязательно).
+ *
+ * @example
+ * ```tsx
+ * // в пакете иконок, внутренний модуль
+ * const { DefaultPropsContext: IconDefaultPropsContext, useDefaultProps: useIconDefaultProps } =
+ *     createDefaultPropsContext<IconProps>('Icon');
+ *
+ * export { IconDefaultPropsContext };
+ *
+ * // Icon.tsx
+ * const Icon: FC<IconProps> = (props) => {
+ *     const defaults = useIconDefaultProps();
+ *     const { size = 'medium', ...rest } = { ...defaults, ...props };
+ *     // ...
+ * };
+ * ```
+ */
+const createDefaultPropsContext = (name) => {
+    const BoundContext = createContext(EMPTY_DEFAULTS);
+    const DefaultPropsContext = ({ props, important = false, children }) => {
+        const parent = useContext(BoundContext);
+        const stableProps = useShallowMemo(props);
+        const resolved = useMemo(() => foldDefaults(parent, stableProps, important), [parent, stableProps, important]);
+        return jsx(BoundContext.Provider, { value: resolved, children: children });
+    };
+    DefaultPropsContext.displayName = name ? `${name}DefaultPropsContext` : 'DefaultPropsContext';
+    const useDefaultProps = () => useContext(BoundContext).values;
+    return { DefaultPropsContext, useDefaultProps };
+};
+
+export { createDefaultPropsContext };
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["src/index.tsx"],"sourcesContent":["import { createContext, useContext, useMemo, useRef, type FC, type ReactNode } from 'react';\n\nconst shallowEqual = (a: Record<string, unknown>, b: Record<string, unknown>): boolean => {\n    if (a === b) {\n        return true;\n    }\n    let countA = 0;\n    for (const key in a) {\n        if (!Object.is(a[key], b[key])) {\n            return false;\n        }\n        countA += 1;\n    }\n    for (const _ in b) {\n        countA -= 1;\n        if (countA < 0) {\n            return false;\n        }\n    }\n    return true;\n};\n\nconst useShallowMemo = <T extends Record<string, unknown>>(value: T): T => {\n    const ref = useRef(value);\n    if (!shallowEqual(ref.current, value)) {\n        ref.current = value;\n    }\n    return ref.current;\n};\n\n/**\n * Свёрнутые дефолты для поддерева. `values` — итоговые значения для потребителя,\n * `importantKeys` — ключи, уже зафиксированные `important`-провайдером выше по дереву\n * (нужны, чтобы вложенный провайдер мог продолжить свёртку с правильным приоритетом).\n */\ntype ResolvedDefaults = {\n    values: Record<string, unknown>;\n    importantKeys: ReadonlySet<string>;\n};\n\nconst EMPTY_DEFAULTS: ResolvedDefaults = { values: {}, importantKeys: new Set() };\n\n/**\n * Инкрементальная свёртка «родитель + пропсы провайдера» сверху вниз.\n *\n * Для каждого ключа провайдера:\n * - если ключ уже зафиксирован `important` снаружи — пропускаем (внешний `important` побеждает);\n * - иначе записываем значение (обычный внутренний так перекрывает обычный внешний, т.к. идём сверху вниз);\n * - если провайдер `important` — дополнительно фиксируем ключ, чтобы внутренние провайдеры его не перебили.\n *\n * Эквивалентно полному обходу цепочки на чтении, но считается один раз на провайдер, а не на потребителя.\n */\nconst foldDefaults = (\n    parent: ResolvedDefaults,\n    props: Record<string, unknown>,\n    important: boolean\n): ResolvedDefaults => {\n    const values = { ...parent.values };\n    let importantKeys = parent.importantKeys;\n\n    for (const key in props) {\n        // Ключ, уже зафиксированный important-провайдером снаружи, не трогаем — внешний important побеждает.\n        if (!parent.importantKeys.has(key)) {\n            values[key] = props[key];\n            if (important) {\n                if (importantKeys === parent.importantKeys) {\n                    importantKeys = new Set(parent.importantKeys);\n                }\n                (importantKeys as Set<string>).add(key);\n            }\n        }\n    }\n\n    return { values, importantKeys };\n};\n\nexport interface BoundDefaultPropsContextProps<P> {\n    props: Partial<P>;\n    /**\n     * Если `true`, заданные здесь пропсы форсируются: по пересекающимся ключам они побеждают\n     * любой вложенный (внутренний) провайдер, а не наоборот. Между несколькими `important`\n     * побеждает самый внешний. Влияет только на ключи, перечисленные в `props`.\n     * Явные пропсы на самом компоненте по-прежнему перекрывают любой дефолт.\n     * @default false\n     */\n    important?: boolean;\n    children?: ReactNode;\n}\n\n/**\n * Результат `createDefaultPropsContext`: провайдер с забинженным типом пропсов и хук для чтения.\n */\nexport interface DefaultPropsContextBundle<P> {\n    /** Провайдер дефолтных пропсов — тип пропсов забинжен фабрикой. */\n    DefaultPropsContext: FC<BoundDefaultPropsContextProps<P>>;\n    /** Хук для чтения смёрженных дефолтов из ближайшего провайдера этого бандла. */\n    useDefaultProps: () => Partial<P>;\n}\n\n/**\n * Фабрика, создающая изолированный `DefaultPropsContext` и хук чтения, параметризованные типом пропсов `P`.\n *\n * Контекст создаётся один раз на вызов фабрики и живёт в замыкании модуля компонента, поэтому провайдер\n * и читающий хук гарантированно делят один и тот же объект контекста, даже если центральный пакет\n * задублирован по версиям в дереве зависимостей. Каждый компонент создаёт свой бандл в своём пакете\n * и экспортирует наружу только провайдер, оставляя хук внутренней деталью реализации.\n *\n * Мерж дефолтов выполняется в провайдере (один раз на провайдер), поэтому потребитель читает готовое\n * значение со стабильной ссылкой между рендерами.\n *\n * Вызывать строго один раз на уровне модуля (не внутри рендера) — иначе на каждый рендер будет новый контекст.\n *\n * @param name — имя компонента для `displayName` провайдера в React DevTools (необязательно).\n *\n * @example\n * ```tsx\n * // в пакете иконок, внутренний модуль\n * const { DefaultPropsContext: IconDefaultPropsContext, useDefaultProps: useIconDefaultProps } =\n *     createDefaultPropsContext<IconProps>('Icon');\n *\n * export { IconDefaultPropsContext };\n *\n * // Icon.tsx\n * const Icon: FC<IconProps> = (props) => {\n *     const defaults = useIconDefaultProps();\n *     const { size = 'medium', ...rest } = { ...defaults, ...props };\n *     // ...\n * };\n * ```\n */\nexport const createDefaultPropsContext = <P,>(name?: string): DefaultPropsContextBundle<P> => {\n    const BoundContext = createContext<ResolvedDefaults>(EMPTY_DEFAULTS);\n\n    const DefaultPropsContext: FC<BoundDefaultPropsContextProps<P>> = ({ props, important = false, children }) => {\n        const parent = useContext(BoundContext);\n        const stableProps = useShallowMemo(props as Record<string, unknown>);\n\n        const resolved = useMemo(() => foldDefaults(parent, stableProps, important), [parent, stableProps, important]);\n\n        return <BoundContext.Provider value={resolved}>{children}</BoundContext.Provider>;\n    };\n    DefaultPropsContext.displayName = name ? `${name}DefaultPropsContext` : 'DefaultPropsContext';\n\n    const useDefaultProps = (): Partial<P> => useContext(BoundContext).values as Partial<P>;\n\n    return { DefaultPropsContext, useDefaultProps };\n};\n"],"names":["_jsx"],"mappings":"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"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hh.ru/magritte-internal-default-props-context",
+  "version": "1.0.1",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "sideEffects": [
+    "index.css"
+  ],
+  "scripts": {
+    "build": "yarn root:build $(pwd)",
+    "build-test-branch": "yarn root:build-test-branch $(pwd)",
+    "prepack": "yarn root:prepack $(pwd)",
+    "postpublish": "yarn root:postpublish $(pwd)",
+    "stylelint-check": "yarn root:stylelint-check $(pwd)",
+    "eslint-check": "yarn root:eslint-check $(pwd)",
+    "ts-config": "yarn root:ts-config $(pwd)",
+    "ts-check": "yarn root:ts-check $(pwd)",
+    "test": "yarn root:test $(pwd)",
+    "watch": "yarn root:watch $(pwd)"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "fa01b9128d8cb502e80c61cd964d7a8a3a279957"
+}