@css-hooks/core 3.2.0-next.8 → 4.0.0-next.0

package/README.md

@@ -1,16 +1,16 @@
 <div align="center">
-  <a id="logomark" href="https://next.css-hooks.com"><img alt="CSS Hooks" src="https://github.com/css-hooks/css-hooks/raw/v3.2.0-next.8/.github/logomark.svg" height="128" /></a><br/><br/>
+  <a id="logomark" href="https://next.css-hooks.com"><img alt="CSS Hooks" src="https://github.com/css-hooks/css-hooks/raw/v4.0.0-next.0/.github/logomark.svg" height="128" /></a><br/><br/>
   <div id="wordmark">
-    <a href="https://next.css-hooks.com"><img alt="CSS Hooks" src="https://github.com/css-hooks/css-hooks/raw/v3.2.0-next.8/.github/wordmark-dark.svg" width="256"></a>
+    <a href="https://next.css-hooks.com"><img alt="CSS Hooks" src="https://github.com/css-hooks/css-hooks/raw/v4.0.0-next.0/.github/wordmark-dark.svg" width="256"></a>
   </div>
 </div>
 
 <br/>
 
 <div align="center" id="badges">
-  <a href="https://github.com/css-hooks/css-hooks/tree/v3.2.0-next.8"><img src="https://img.shields.io/badge/tag-v3.2.0--next.8-ffd700" alt="tag v3.2.0-next.8"></a>
-  <a href="https://www.npmjs.com/package/@css-hooks/core/v/3.2.0-next.8"><img src="https://img.shields.io/badge/npm-v3.2.0--next.8-ffd700" alt="npm version"></a>
-  <a href="https://github.com/css-hooks/css-hooks/blob/v3.2.0-next.8/LICENSE"><img src="https://img.shields.io/badge/license-MIT-ffd700" alt="license"></a>
+  <a href="https://github.com/css-hooks/css-hooks/tree/v4.0.0-next.0"><img src="https://img.shields.io/badge/tag-v4.0.0--next.0-ffd700" alt="tag v4.0.0-next.0"></a>
+  <a href="https://www.npmjs.com/package/@css-hooks/core/v/4.0.0-next.0"><img src="https://img.shields.io/badge/npm-v4.0.0--next.0-ffd700" alt="npm version"></a>
+  <a href="https://github.com/css-hooks/css-hooks/blob/v4.0.0-next.0/LICENSE"><img src="https://img.shields.io/badge/license-MIT-ffd700" alt="license"></a>
 </div>
 
 ---

package/cjs/index.js

@@ -9,18 +9,22 @@ exports.buildHooksSystem = buildHooksSystem;
 /**
  * Creates a flavor of CSS Hooks tailored to a specific app framework.
  *
+ * @remarks
+ * Primarily for internal use, advanced use cases, or when an appropriate
+ * framework integration is not provided
+ *
+ * @typeParam CSSProperties - The type of a style object, typically defined by
+ *   an app framework (e.g., React's `CSSProperties` type)
+ * @typeParam CSSPropertyConflicts - A map from CSS properties to the properties
+ *   with which they conflict
+ *
  * @param stringify - The function used to stringify values when merging
- * conditional styles.
+ *   override styles
  *
  * @returns The `createHooks` function used to bootstrap CSS Hooks within an app
- * or component library.
- *
- * @remarks
- * Primarily for internal use, advanced use cases, or when an appropriate
- * framework integration is not provided.
+ *   or component library
  *
  * @public
- *
  */
 function buildHooksSystem(stringify = String) {
     return (...selectors) => {
@@ -32,8 +36,8 @@ function buildHooksSystem(stringify = String) {
                 const indent = Array(2).fill(space).join("");
                 return `*${space}{${newline}${selectors
                     .flatMap(selector => [
-                    `${indent}--${createHash(selector)}-0:${space}initial;`,
-                    `${indent}--${createHash(selector)}-1:${space};`,
+                    `${indent}--${createHash(selector)}0:${space}initial;`,
+                    `${indent}--${createHash(selector)}1:${space};`,
                 ])
                     .join(newline)}${newline}}${newline}${selectors
                     .flatMap(def => {
@@ -41,16 +45,16 @@ function buildHooksSystem(stringify = String) {
                         return [
                             `${def} {`,
                             `${indent}* {`,
-                            `${indent}${indent}--${createHash(def)}-0:${space};`,
-                            `${indent}${indent}--${createHash(def)}-1:${space}initial;`,
+                            `${indent}${indent}--${createHash(def)}0:${space};`,
+                            `${indent}${indent}--${createHash(def)}1:${space}initial;`,
                             `${indent}}`,
                             "}",
                         ];
                     }
                     return [
                         `${def.replace(/&/g, "*")}${space}{`,
-                        `${indent}--${createHash(def)}-0:${space};`,
-                        `${indent}--${createHash(def)}-1:${space}initial;`,
+                        `${indent}--${createHash(def)}0:${space};`,
+                        `${indent}--${createHash(def)}1:${space}initial;`,
                         "}",
                     ];
                 })
@@ -59,15 +63,12 @@ function buildHooksSystem(stringify = String) {
             and: (...and) => ({ and }),
             or: (...or) => ({ or }),
             not: not => ({ not }),
-            on(condition, conditionalStyleOrFn) {
-                return fallbackStyle => {
-                    const conditionalStyle = conditionalStyleOrFn instanceof Function
-                        ? conditionalStyleOrFn(fallbackStyle)
-                        : conditionalStyleOrFn;
+            on(condition, overrideStyle) {
+                return (fallbackStyle) => {
                     const style = { ...fallbackStyle };
-                    for (const property in conditionalStyle) {
-                        const conditionalValue = stringify(conditionalStyle[property], property);
-                        if (conditionalValue === null) {
+                    for (const property in overrideStyle) {
+                        const overrideValue = stringify(overrideStyle[property], property);
+                        if (overrideValue === null) {
                             continue;
                         }
                         let fallbackValue = "revert-layer";
@@ -77,7 +78,7 @@ function buildHooksSystem(stringify = String) {
                                 fallbackValue = fv;
                             }
                         }
-                        const [value, extraDecls] = buildExpression(condition, conditionalValue, fallbackValue);
+                        const [value, extraDecls] = buildExpression(condition, overrideValue, fallbackValue);
                         Object.assign(style, { [property]: value }, extraDecls);
                     }
                     return style;
@@ -96,7 +97,7 @@ function buildHooksSystem(stringify = String) {
                                 valFalse = `var(--${hash})`;
                             }
                             return [
-                                `var(--${createHash(condition)}-1,${space}${valTrue})${space}var(--${createHash(condition)}-0,${space}${valFalse})`,
+                                `var(--${createHash(condition)}1,${space}${valTrue})${space}var(--${createHash(condition)}0,${space}${valFalse})`,
                                 extraDecls,
                             ];
                         }
@@ -125,14 +126,26 @@ function buildHooksSystem(stringify = String) {
         };
     };
 }
-function createHash(obj) {
-    const jsonString = JSON.stringify(obj);
-    let hashValue = 0;
-    for (let i = 0; i < jsonString.length; i++) {
-        const charCode = jsonString.charCodeAt(i);
-        hashValue = (hashValue << 5) - hashValue + charCode;
-        hashValue &= 0x7fffffff;
+const hashAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function createHash(value) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        h1 = Math.imul(h1 ^ code, 0x9e3779b1);
+        h2 = Math.imul(h2 ^ code, 0x5f356495);
+    }
+    h1 =
+        Math.imul(h1 ^ (h1 >>> 16), 0x85ebca6b) ^
+            Math.imul(h2 ^ (h2 >>> 13), 0xc2b2ae35);
+    h2 =
+        Math.imul(h2 ^ (h2 >>> 16), 0x85ebca6b) ^
+            Math.imul(h1 ^ (h1 >>> 13), 0xc2b2ae35);
+    let hash = (h1 >>> 0) + 0x100000000 * (h2 & 0xf);
+    let encoded = "";
+    for (let i = 0; i < 6; i++) {
+        encoded = hashAlphabet.charAt(hash % 64) + encoded;
+        hash = Math.floor(hash / 64);
     }
-    const str = hashValue.toString(36);
-    return /^[0-9]/.test(str) ? `a${str}` : str;
+    return encoded;
 }

package/esm/index.js

@@ -6,18 +6,22 @@
 /**
  * Creates a flavor of CSS Hooks tailored to a specific app framework.
  *
+ * @remarks
+ * Primarily for internal use, advanced use cases, or when an appropriate
+ * framework integration is not provided
+ *
+ * @typeParam CSSProperties - The type of a style object, typically defined by
+ *   an app framework (e.g., React's `CSSProperties` type)
+ * @typeParam CSSPropertyConflicts - A map from CSS properties to the properties
+ *   with which they conflict
+ *
  * @param stringify - The function used to stringify values when merging
- * conditional styles.
+ *   override styles
  *
  * @returns The `createHooks` function used to bootstrap CSS Hooks within an app
- * or component library.
- *
- * @remarks
- * Primarily for internal use, advanced use cases, or when an appropriate
- * framework integration is not provided.
+ *   or component library
  *
  * @public
- *
  */
 export function buildHooksSystem(stringify = String) {
     return (...selectors) => {
@@ -29,8 +33,8 @@ export function buildHooksSystem(stringify = String) {
                 const indent = Array(2).fill(space).join("");
                 return `*${space}{${newline}${selectors
                     .flatMap(selector => [
-                    `${indent}--${createHash(selector)}-0:${space}initial;`,
-                    `${indent}--${createHash(selector)}-1:${space};`,
+                    `${indent}--${createHash(selector)}0:${space}initial;`,
+                    `${indent}--${createHash(selector)}1:${space};`,
                 ])
                     .join(newline)}${newline}}${newline}${selectors
                     .flatMap(def => {
@@ -38,16 +42,16 @@ export function buildHooksSystem(stringify = String) {
                         return [
                             `${def} {`,
                             `${indent}* {`,
-                            `${indent}${indent}--${createHash(def)}-0:${space};`,
-                            `${indent}${indent}--${createHash(def)}-1:${space}initial;`,
+                            `${indent}${indent}--${createHash(def)}0:${space};`,
+                            `${indent}${indent}--${createHash(def)}1:${space}initial;`,
                             `${indent}}`,
                             "}",
                         ];
                     }
                     return [
                         `${def.replace(/&/g, "*")}${space}{`,
-                        `${indent}--${createHash(def)}-0:${space};`,
-                        `${indent}--${createHash(def)}-1:${space}initial;`,
+                        `${indent}--${createHash(def)}0:${space};`,
+                        `${indent}--${createHash(def)}1:${space}initial;`,
                         "}",
                     ];
                 })
@@ -56,15 +60,12 @@ export function buildHooksSystem(stringify = String) {
             and: (...and) => ({ and }),
             or: (...or) => ({ or }),
             not: not => ({ not }),
-            on(condition, conditionalStyleOrFn) {
-                return fallbackStyle => {
-                    const conditionalStyle = conditionalStyleOrFn instanceof Function
-                        ? conditionalStyleOrFn(fallbackStyle)
-                        : conditionalStyleOrFn;
+            on(condition, overrideStyle) {
+                return (fallbackStyle) => {
                     const style = { ...fallbackStyle };
-                    for (const property in conditionalStyle) {
-                        const conditionalValue = stringify(conditionalStyle[property], property);
-                        if (conditionalValue === null) {
+                    for (const property in overrideStyle) {
+                        const overrideValue = stringify(overrideStyle[property], property);
+                        if (overrideValue === null) {
                             continue;
                         }
                         let fallbackValue = "revert-layer";
@@ -74,7 +75,7 @@ export function buildHooksSystem(stringify = String) {
                                 fallbackValue = fv;
                             }
                         }
-                        const [value, extraDecls] = buildExpression(condition, conditionalValue, fallbackValue);
+                        const [value, extraDecls] = buildExpression(condition, overrideValue, fallbackValue);
                         Object.assign(style, { [property]: value }, extraDecls);
                     }
                     return style;
@@ -93,7 +94,7 @@ export function buildHooksSystem(stringify = String) {
                                 valFalse = `var(--${hash})`;
                             }
                             return [
-                                `var(--${createHash(condition)}-1,${space}${valTrue})${space}var(--${createHash(condition)}-0,${space}${valFalse})`,
+                                `var(--${createHash(condition)}1,${space}${valTrue})${space}var(--${createHash(condition)}0,${space}${valFalse})`,
                                 extraDecls,
                             ];
                         }
@@ -122,14 +123,26 @@ export function buildHooksSystem(stringify = String) {
         };
     };
 }
-function createHash(obj) {
-    const jsonString = JSON.stringify(obj);
-    let hashValue = 0;
-    for (let i = 0; i < jsonString.length; i++) {
-        const charCode = jsonString.charCodeAt(i);
-        hashValue = (hashValue << 5) - hashValue + charCode;
-        hashValue &= 0x7fffffff;
+const hashAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function createHash(value) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        h1 = Math.imul(h1 ^ code, 0x9e3779b1);
+        h2 = Math.imul(h2 ^ code, 0x5f356495);
+    }
+    h1 =
+        Math.imul(h1 ^ (h1 >>> 16), 0x85ebca6b) ^
+            Math.imul(h2 ^ (h2 >>> 13), 0xc2b2ae35);
+    h2 =
+        Math.imul(h2 ^ (h2 >>> 16), 0x85ebca6b) ^
+            Math.imul(h1 ^ (h1 >>> 13), 0xc2b2ae35);
+    let hash = (h1 >>> 0) + 0x100000000 * (h2 & 0xf);
+    let encoded = "";
+    for (let i = 0; i < 6; i++) {
+        encoded = hashAlphabet.charAt(hash % 64) + encoded;
+        hash = Math.floor(hash / 64);
     }
-    const str = hashValue.toString(36);
-    return /^[0-9]/.test(str) ? `a${str}` : str;
+    return encoded;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@css-hooks/core",
   "description": "CSS Hooks core library",
-  "version": "3.2.0-next.8",
+  "version": "4.0.0-next.0",
   "author": "Nick Saunders",
   "devDependencies": {
     "color": "^5.0.3",

package/types/index.d.ts

@@ -6,8 +6,7 @@
 /**
  * Represents the conditions under which a given hook or declaration applies.
  *
- * @typeParam S - The basic type of condition to enhance with boolean
- * operations.
+ * @typeParam S - The basic type of condition to enhance with boolean operations
  *
  * @public
  */
@@ -19,18 +18,16 @@ export type Condition<S> = S | {
     not: Condition<S>;
 };
 /**
- * Function to convert a value into a string.
+ * Function to convert a value into a string
  *
- * @param value - The value to stringify
+ * @remarks
+ * Used for merging a conditional property value with the fallback value
  *
+ * @param value - The value to stringify
  * @param propertyName - The property name corresponding to the value being
- * stringified
+ *   stringified
  *
- * @remarks
- * Used for merging a conditional property value with the fallback value.
- *
- * @returns The stringified value, or `undefined` if the value cannot be
- * stringified
+ * @returns The stringified value, or `null` if the value cannot be stringified
  *
  * @public
  */
@@ -39,57 +36,66 @@ export type StringifyFn = (value: unknown, propertyName: string) => string | nul
  * Represents the selector logic used to create a hook.
  *
  * @remarks
- * Two types are supported:
- * 1. A basic selector, where `&` is used as a placeholder for the element to
- *    which the condition applies. The `&` character must appear somewhere.
- * 2. A `@media`, `@container`, or `@supports` at-rule. The value must begin
- *    with one of these keywords, followed by a space.
- * 3. The `@starting-style` at-rule (exactly, with no additional parameters).
+ * Three forms are supported:
+ *
+ * 1. A basic selector, where `&` is used as a placeholder for the element to which
+ *    the condition applies. The `&` character must appear somewhere.
+ * 2. `@media`, `@container`, and `@supports` at-rules. Each value must begin with
+ *    its keyword, followed by a space.
+ * 3. `@starting-style` with no additional parameters
  *
  * @public
  */
 export type Selector = `${string}&${string}` | `@${"media" | "container" | "supports"} ${string}` | "@starting-style";
 /**
- * Enhances a style object by merging in conditional declarations.
- *
- * @typeParam CSSProperties - The type of a standard (flat) style object,
- * typically defined by an app framework (e.g., React's `CSSProperties` type).
+ * Resolves the CSS property names that conflict with an override style.
  *
- * @param style - The original style object containing default/fallback values
- *
- * @returns An enhanced style object with conditional styles applied
+ * @typeParam CSSPropertyConflicts - A map from CSS properties to the properties
+ *   they conflict with
+ * @typeParam OverrideCSSProperties - The conditional declarations for which
+ *   conflicting properties are resolved
+ */
+type CSSPropertyConflictKeys<CSSPropertyConflicts extends object, OverrideCSSProperties> = CSSPropertyConflicts[keyof OverrideCSSProperties & keyof CSSPropertyConflicts] & PropertyKey;
+/**
+ * Prevents conflicting CSS properties from being assigned values in a base
+ * style.
  *
- * @public
+ * @typeParam CSSPropertyConflicts - A map from CSS properties to the properties
+ *   with which they conflict
+ * @typeParam OverrideCSSProperties - The conditional declarations for which
+ *   conflicting properties are forbidden
  */
-export type EnhanceStyleFn<CSSProperties> = (style: CSSProperties) => CSSProperties;
+type ForbidCSSPropertyConflicts<CSSPropertyConflicts extends object, OverrideCSSProperties> = {
+    [P in CSSPropertyConflictKeys<CSSPropertyConflicts, OverrideCSSProperties>]?: never;
+};
 /**
  * An object containing the functions needed to support and use the configured
- * hooks.
+ * hooks
  *
  * @typeParam S - The type of the selector logic for which to generate hooks
- *
- * @typeParam CSSProperties - The type of a standard (flat) style object,
- * typically defined by an app framework (e.g., React's `CSSProperties` type).
- *
- * @public
+ * @typeParam CSSProperties - The type of a style object, typically defined by
+ *   an app framework (e.g., React's `CSSProperties` type)
+ * @typeParam CSSPropertyConflicts - A map from CSS properties to the properties
+ *   with which they conflict
  */
-export interface CreateHooksResult<S, CSSProperties> {
+interface CreateHooksResult<S, CSSProperties, CSSPropertyConflicts extends object> {
     /**
-     * Enhances a style object with conditional styles.
+     * Creates a function that enhances a style object with conditional override
+     * styles.
      */
-    on: (condition: Condition<S>, style: CSSProperties | ((style: CSSProperties) => CSSProperties)) => EnhanceStyleFn<CSSProperties>;
+    on: <OverrideCSSProperties extends CSSProperties, BaseCSSProperties extends Omit<CSSProperties, CSSPropertyConflictKeys<CSSPropertyConflicts, OverrideCSSProperties>>>(condition: Condition<S>, overrideStyle: OverrideCSSProperties) => (style: CSSProperties & BaseCSSProperties & ForbidCSSPropertyConflicts<CSSPropertyConflicts, OverrideCSSProperties>) => BaseCSSProperties & OverrideCSSProperties;
     /**
      * Combines a list of conditions into a single condition which is true when
      * all of the specified conditions are true.
      *
      * @typeParam C - The type of the conditions which must all be true in order
-     * for the condition to be true.
+     *   for the condition to be true
      *
      * @param conditions - The conditions which must all be true in order for the
-     * condition to be true.
+     *   condition to be true
      *
      * @returns A condition that is true when all of the specified conditions are
-     * true.
+     *   true
      */
     and: <C extends Condition<S>[]>(...conditions: C) => {
         and: C;
@@ -99,13 +105,13 @@ export interface CreateHooksResult<S, CSSProperties> {
      * any of the specified conditions are true.
      *
      * @typeParam C - The type of the conditions any one of which must be true in
-     * order for the condition to be true.
+     *   order for the condition to be true
      *
      * @param conditions - The conditions any one of which must be true in order
-     * for the condition to be true.
+     *   for the condition to be true
      *
      * @returns A condition that is true when any of the specified conditions are
-     * true.
+     *   true
      */
     or: <C extends Condition<S>[]>(...conditions: C) => {
         or: C;
@@ -113,54 +119,58 @@ export interface CreateHooksResult<S, CSSProperties> {
     /**
      * Negates a condition.
      *
-     * @typeParam condition - The type of the condition which must be false in
-     * order for the resulting condition to be true.
+     * @typeParam C - The type of the condition which must be false in order for
+     *   the resulting condition to be true
      *
      * @param condition - The condition which must be false in order for the
-     * resulting condition to be true.
+     *   resulting condition to be true
      *
      * @returns A condition that is true when the specified condition is false.
      */
     not: <C extends Condition<S>>(condition: C) => {
         not: C;
     };
-    /**
-     * The style sheet required to support the configured hooks.
-     */
+    /** Returns the style sheet required to support the configured hooks. */
     styleSheet: () => string;
 }
 /**
  * Represents the function used to define hooks and related configuration.
  *
- * @typeParam CSSProperties - The type of a standard (flat) style object,
- * typically defined by an app framework (e.g., React's `CSSProperties` type).
+ * @typeParam CSSProperties - The type of a style object, typically defined by
+ *   an app framework (e.g., React's `CSSProperties` type)
+ * @typeParam CSSPropertyConflicts - A map from CSS properties to the properties
+ *   with which they conflict
+ * @typeParam S - The type of selectors for which to create hooks
  *
- * @typeParam S - The type of selectors for which to create hooks.
- *
- * @param selectors - The selectors for which to create hooks.
+ * @param selectors - The selectors for which to create hooks
  *
  * @returns An object containing the functions needed to support and use the
- * configured hooks.
+ *   configured hooks
  *
  * @public
  */
-export type CreateHooksFn<CSSProperties> = <S extends Selector>(...selectors: S[]) => CreateHooksResult<S, CSSProperties>;
+export type CreateHooksFn<CSSProperties, CSSPropertyConflicts extends object = object> = <S extends Selector>(...selectors: S[]) => CreateHooksResult<S, CSSProperties, CSSPropertyConflicts>;
 /**
  * Creates a flavor of CSS Hooks tailored to a specific app framework.
  *
+ * @remarks
+ * Primarily for internal use, advanced use cases, or when an appropriate
+ * framework integration is not provided
+ *
+ * @typeParam CSSProperties - The type of a style object, typically defined by
+ *   an app framework (e.g., React's `CSSProperties` type)
+ * @typeParam CSSPropertyConflicts - A map from CSS properties to the properties
+ *   with which they conflict
+ *
  * @param stringify - The function used to stringify values when merging
- * conditional styles.
+ *   override styles
  *
  * @returns The `createHooks` function used to bootstrap CSS Hooks within an app
- * or component library.
- *
- * @remarks
- * Primarily for internal use, advanced use cases, or when an appropriate
- * framework integration is not provided.
+ *   or component library
  *
  * @public
- *
  */
 export declare function buildHooksSystem<CSSProperties extends {
     [P: string]: any;
-} = Record<string, unknown>>(stringify?: StringifyFn): CreateHooksFn<CSSProperties>;
+} = Record<string, unknown>, CSSPropertyConflicts extends object = object>(stringify?: StringifyFn): CreateHooksFn<CSSProperties, CSSPropertyConflicts>;
+export {};