@salt-ds/styles 0.0.0-snapshot-20260109210611 → 0.0.0-snapshot-20260112210403

package/CHANGELOG.md

@@ -1,10 +1,30 @@
 # @salt-ds/styles
 
-## 0.0.0-snapshot-20260109210611
+## 0.0.0-snapshot-20260112210403
 
 ### Patch Changes
 
-- e12cacd: poc
+- b639bf8: This feature is in-development, for exploration and feedback only.
+
+  Introduce a context‑driven API for injecting CSS class names into Salt components based on their props, and optionally stripping implementation‑only props before forwarding.
+
+  _Status_
+  Non‑breaking for existing Salt consumers
+  Experimental and incomplete — interfaces and behavior may change without notice
+
+  **Note to JPM employees**
+  Use only in non‑production codebases, or with prior permission from the Salt engineering team
+  What’s included
+
+  - `ClassNameInjectionProvider` — supplies a registry of class injectors via React context
+  - `useClassNameInjection(component, props)`
+    - computes additional classes via registered injectors
+    - merges them with any className provided at the call site
+    - removes internal/derived props (declared by each injector) before forwarding
+  - `registerClassInjector(registry, component, keys, injector)` — registers per‑component injection rules
+
+  _Documentation_
+  Full documentation will follow once the API is stabilized; for now, consider this API private and subject to change.
 
 ## 0.2.1
 

package/dist-cjs/index.js

@@ -14,5 +14,5 @@ exports.useInsertionPoint = InsertionPointProvider.useInsertionPoint;
 exports.useComponentCssInjection = useStyleInjection.useComponentCssInjection;
 exports.ClassNameInjectionProvider = useClassNameInjection.ClassNameInjectionProvider;
 exports.registerClassInjector = useClassNameInjection.registerClassInjector;
-exports.useInjectedClassName = useClassNameInjection.useInjectedClassName;
+exports.useClassNameInjection = useClassNameInjection.useClassNameInjection;
 //# sourceMappingURL=index.js.map

package/dist-cjs/useClassNameInjection.js

@@ -4,41 +4,72 @@ var jsxRuntime = require('react/jsx-runtime');
 var clsx = require('clsx');
 var React = require('react');
 
-const InjectionContext = React.createContext(null);
+const EMPTY_REGISTRY = /* @__PURE__ */ new Map();
+const InjectionContext = React.createContext(EMPTY_REGISTRY);
+let hasWarnedExperimentalOnce = false;
 function ClassNameInjectionProvider({
   children,
   value
 }) {
-  const registry = React.useMemo(() => value ?? {}, [value]);
+  const registry = React.useMemo(() => value ?? EMPTY_REGISTRY, [value]);
+  React.useEffect(() => {
+    if (!hasWarnedExperimentalOnce && process.env.NODE_ENV !== "production") {
+      console.warn(
+        "Salt ClassNameInjectionProvider is experimental and subject to change. JPM users: only recommended in non-production environments or with prior permission from the Salt team."
+      );
+      hasWarnedExperimentalOnce = true;
+    }
+  }, []);
   return /* @__PURE__ */ jsxRuntime.jsx(InjectionContext.Provider, { value: registry, children });
 }
-function useInjectedClassName(component, props) {
-  const { className: classNameProp, ...restProps } = props;
+function useClassNameInjection(component, props) {
   const registry = React.useContext(InjectionContext);
-  if (!registry) {
-    return {
-      className: classNameProp || "",
-      props: restProps
-    };
-  }
-  const entries = registry[component] ?? [];
-  const injected = entries.map((e) => e.fn(restProps)).filter(Boolean);
-  const className = clsx.clsx(classNameProp, injected);
-  const cleanProps = { ...restProps };
-  for (const entry of entries) {
-    for (const key of entry.keys) {
-      delete cleanProps[key];
+  const entries = registry.get(component) ?? [];
+  const deps = React.useMemo(
+    () => entries.length ? entries.flatMap((e) => e.keys.map((k) => props[k])) : [],
+    [entries, props]
+  );
+  const injected = React.useMemo(() => {
+    const { className: _ignore, ...restProps } = props;
+    if (!entries.length) return [];
+    return entries.map((e) => e.fn(restProps)).filter((v) => v != null);
+  }, [entries, deps, props]);
+  const className = React.useMemo(
+    () => clsx.clsx(props.className, injected) || void 0,
+    [props, injected]
+  );
+  const cleanProps = React.useMemo(() => {
+    const { className: _ignore, ...restProps } = props;
+    if (!entries.length) {
+      return restProps;
     }
-  }
+    const copy = { ...restProps };
+    for (const entry of entries) {
+      for (const key of entry.keys) {
+        if (Object.hasOwn(copy, key)) {
+          delete copy[key];
+        }
+      }
+    }
+    return copy;
+  }, [entries, deps, props]);
   return { className, props: cleanProps };
 }
 function registerClassInjector(registry, component, keys, injector) {
-  registry[component] ??= [];
-  const wrapped = (props) => injector(props);
-  registry[component] = [...registry[component], { fn: wrapped, keys }];
+  if (!registry.has(component)) {
+    registry.set(component, []);
+  }
+  const wrapped = (props) => {
+    const picked = Object.fromEntries(keys.map((k) => [k, props[k]]));
+    return injector(picked);
+  };
+  registry.get(component).push({
+    fn: wrapped,
+    keys
+  });
 }
 
 exports.ClassNameInjectionProvider = ClassNameInjectionProvider;
 exports.registerClassInjector = registerClassInjector;
-exports.useInjectedClassName = useInjectedClassName;
+exports.useClassNameInjection = useClassNameInjection;
 //# sourceMappingURL=useClassNameInjection.js.map

package/dist-cjs/useClassNameInjection.js.map

@@ -1 +1 @@
-{"version":3,"file":"useClassNameInjection.js","sources":["../src/useClassNameInjection.tsx"],"sourcesContent":["import { clsx } from \"clsx\";\nimport { createContext, useContext, useMemo } from \"react\";\n\nexport type ClassNameInjector<Props, Keys extends keyof Props> = (\n  props: Pick<Props, Keys>,\n) => string | undefined;\n\ninterface ClassNameInjectorEntry<Props> {\n  fn: (props: Props) => string | undefined;\n  keys: (keyof Props)[];\n}\n\nexport type ClassNameInjectionRegistry = Record<\n  string,\n  // biome-ignore lint/suspicious/noExplicitAny: refer to ClassNameInjector which derives it's entry type based on the Props\n  ClassNameInjectorEntry<any>[]\n>;\n\nconst InjectionContext = createContext<ClassNameInjectionRegistry | null>(null);\n\nexport type ClassNameInjectionProviderProps = {\n  children: React.ReactNode;\n  value?: ClassNameInjectionRegistry;\n};\n\nexport function ClassNameInjectionProvider({\n  children,\n  value,\n}: ClassNameInjectionProviderProps) {\n  const registry = useMemo(() => value ?? {}, [value]);\n  return (\n    <InjectionContext.Provider value={registry}>\n      {children}\n    </InjectionContext.Provider>\n  );\n}\n\ntype PropsWithClassName = { className?: string } & Record<string, any>;\n\nexport function useInjectedClassName<Props extends PropsWithClassName>(\n  component: string,\n  props: Props,\n): { className: string; props: Omit<Props, \"className\"> } {\n  const { className: classNameProp, ...restProps } = props;\n  const registry = useContext(InjectionContext);\n\n  if (!registry) {\n    return {\n      className: classNameProp || \"\",\n      props: restProps as Omit<Props, \"className\">,\n    };\n  }\n\n  const entries = registry[component] ?? [];\n  const injected = entries.map((e) => e.fn(restProps)).filter(Boolean);\n  const className = clsx(classNameProp, injected);\n\n  const cleanProps = { ...restProps } as Omit<Props, \"className\">;\n  for (const entry of entries) {\n    for (const key of entry.keys) {\n      delete (cleanProps as any)[key];\n    }\n  }\n\n  return { className, props: cleanProps };\n}\n\nexport function registerClassInjector<Props, Keys extends keyof Props>(\n  registry: ClassNameInjectionRegistry,\n  component: string,\n  keys: Keys[],\n  injector: ClassNameInjector<Props, Keys>,\n) {\n  registry[component] ??= [];\n  const wrapped = (props: Props) => injector(props as Props);\n  registry[component] = [...registry[component], { fn: wrapped, keys }];\n}\n"],"names":["createContext","useMemo","useContext","clsx"],"mappings":";;;;;;AAkBA,MAAM,gBAAA,GAAmBA,oBAAiD,IAAI,CAAA;AAOvE,SAAS,0BAAA,CAA2B;AAAA,EACzC,QAAA;AAAA,EACA;AACF,CAAA,EAAoC;AAClC,EAAA,MAAM,QAAA,GAAWC,cAAQ,MAAM,KAAA,IAAS,EAAC,EAAG,CAAC,KAAK,CAAC,CAAA;AACnD,EAAA,sCACG,gBAAA,CAAiB,QAAA,EAAjB,EAA0B,KAAA,EAAO,UAC/B,QAAA,EACH,CAAA;AAEJ;AAIO,SAAS,oBAAA,CACd,WACA,KAAA,EACwD;AACxD,EAAA,MAAM,EAAE,SAAA,EAAW,aAAA,EAAe,GAAG,WAAU,GAAI,KAAA;AACnD,EAAA,MAAM,QAAA,GAAWC,iBAAW,gBAAgB,CAAA;AAE5C,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,OAAO;AAAA,MACL,WAAW,aAAA,IAAiB,EAAA;AAAA,MAC5B,KAAA,EAAO;AAAA,KACT;AAAA,EACF;AAEA,EAAA,MAAM,OAAA,GAAU,QAAA,CAAS,SAAS,CAAA,IAAK,EAAC;AACxC,EAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,EAAA,CAAG,SAAS,CAAC,CAAA,CAAE,MAAA,CAAO,OAAO,CAAA;AACnE,EAAA,MAAM,SAAA,GAAYC,SAAA,CAAK,aAAA,EAAe,QAAQ,CAAA;AAE9C,EAAA,MAAM,UAAA,GAAa,EAAE,GAAG,SAAA,EAAU;AAClC,EAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,IAAA,KAAA,MAAW,GAAA,IAAO,MAAM,IAAA,EAAM;AAC5B,MAAA,OAAQ,WAAmB,GAAG,CAAA;AAAA,IAChC;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,SAAA,EAAW,KAAA,EAAO,UAAA,EAAW;AACxC;AAEO,SAAS,qBAAA,CACd,QAAA,EACA,SAAA,EACA,IAAA,EACA,QAAA,EACA;AACA,EAAA,QAAA,CAAS,SAAS,MAAM,EAAC;AACzB,EAAA,MAAM,OAAA,GAAU,CAAC,KAAA,KAAiB,QAAA,CAAS,KAAc,CAAA;AACzD,EAAA,QAAA,CAAS,SAAS,CAAA,GAAI,CAAC,GAAG,QAAA,CAAS,SAAS,CAAA,EAAG,EAAE,EAAA,EAAI,OAAA,EAAS,IAAA,EAAM,CAAA;AACtE;;;;;;"}
+{"version":3,"file":"useClassNameInjection.js","sources":["../src/useClassNameInjection.tsx"],"sourcesContent":["import { clsx } from \"clsx\";\nimport { createContext, useContext, useEffect, useMemo } from \"react\";\n\n/**\n * Extensible map of supported components → their props.\n * @salt-ds/core must augment this with the components that support the API,\n * using the same key string that the component passes to useClassNameInjection,\n * e.g., \"saltButton\": ButtonProps.\n */\nexport type ComponentPropMap = {};\n\n/** Component key type: only keys declared in ComponentPropMap are allowed. */\ntype SupportedComponent = keyof ComponentPropMap extends never\n  ? string\n  : keyof ComponentPropMap;\n\nexport type ClassNameInjector<Props, Keys extends keyof Props> = (\n  props: Pick<Props, Keys>,\n) => string | undefined;\n\ninterface ClassNameInjectorEntry {\n  fn: (props: unknown) => string | undefined;\n  keys: string[];\n}\n\nexport type ClassNameInjectionRegistry = Map<\n  SupportedComponent,\n  ClassNameInjectorEntry[]\n>;\n\nconst EMPTY_REGISTRY: ClassNameInjectionRegistry = new Map();\nconst InjectionContext =\n  createContext<ClassNameInjectionRegistry>(EMPTY_REGISTRY);\n\nexport type ClassNameInjectionProviderProps = {\n  children: React.ReactNode;\n  value?: ClassNameInjectionRegistry;\n};\n\nlet hasWarnedExperimentalOnce = false;\n\nexport function ClassNameInjectionProvider({\n  children,\n  value,\n}: ClassNameInjectionProviderProps) {\n  const registry = useMemo(() => value ?? EMPTY_REGISTRY, [value]);\n\n  useEffect(() => {\n    if (!hasWarnedExperimentalOnce && process.env.NODE_ENV !== \"production\") {\n      // eslint-disable-next-line no-console\n      console.warn(\n        \"Salt ClassNameInjectionProvider is experimental and subject to change. JPM users: only recommended in non-production environments or with prior permission from the Salt team.\",\n      );\n      hasWarnedExperimentalOnce = true;\n    }\n  }, []);\n\n  return (\n    <InjectionContext.Provider value={registry}>\n      {children}\n    </InjectionContext.Provider>\n  );\n}\n\ntype PropsWithClassName = { className?: string } & Record<string, any>;\n\n/**\n * Return the className created by the registry and a props object with injector keys stripped.\n * Only components declared in ComponentPropMap can call this at compile time.\n */\nexport function useClassNameInjection<Props extends PropsWithClassName>(\n  component: SupportedComponent,\n  props: Props,\n): { className: string | undefined; props: Omit<Props, \"className\"> } {\n  const registry = useContext(InjectionContext);\n  const entries = registry.get(component) ?? [];\n\n  const deps = useMemo(\n    () =>\n      entries.length\n        ? entries.flatMap((e) => e.keys.map((k) => (props as any)[k]))\n        : [],\n    [entries, props],\n  );\n\n  // Compute injected classes provided through ClassNameInjectionRegistry\n  const injected = useMemo(() => {\n    const { className: _ignore, ...restProps } = props as any;\n    if (!entries.length) return [];\n    return entries\n      .map((e) => e.fn(restProps))\n      .filter((v): v is string => v != null);\n  }, [entries, deps, props]);\n\n  // Merge original className with injected classes\n  const className = useMemo(\n    () => clsx((props as any).className, injected) || undefined,\n    [props, injected],\n  );\n\n  // Create a cleaned props object by stripping keys used by injectors, to avoid DOM errors with unknown attributes\n  const cleanProps = useMemo(() => {\n    const { className: _ignore, ...restProps } = props as any;\n    if (!entries.length) {\n      return restProps as Omit<Props, \"className\">;\n    }\n    const copy = { ...restProps } as Omit<Props, \"className\">;\n    for (const entry of entries) {\n      for (const key of entry.keys) {\n        if (Object.hasOwn(copy, key)) {\n          delete (copy as any)[key];\n        }\n      }\n    }\n    return copy;\n  }, [entries, deps, props]);\n\n  return { className, props: cleanProps };\n}\n\n/**\n * Register a class injector for a supported component name.\n * - Keys must be valid string keys for that component’s props (as declared in ComponentPropMap).\n * - Injector receives only the declared keys (Pick<PropsOf<C>, Keys>).\n */\nexport function registerClassInjector<\n  Props extends Record<string, any>,\n  Keys extends Extract<keyof Props, string>,\n>(\n  registry: ClassNameInjectionRegistry,\n  component: SupportedComponent,\n  keys: Keys[],\n  injector: ClassNameInjector<Props, Keys>,\n) {\n  if (!registry.has(component)) {\n    registry.set(component, []);\n  }\n\n  const wrapped = (props: Record<string, any>) => {\n    const picked = Object.fromEntries(keys.map((k) => [k, props[k]])) as Pick<\n      Props,\n      Keys\n    >;\n    return injector(picked);\n  };\n\n  registry.get(component)!.push({\n    fn: wrapped as (props: unknown) => string | undefined,\n    keys: keys as string[],\n  });\n}\n"],"names":["createContext","useMemo","useEffect","useContext","clsx"],"mappings":"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"}

package/dist-es/index.js

@@ -1,5 +1,5 @@
 export { StyleInjectionProvider, useStyleInjection } from './style-injection-provider/index.js';
 export { InsertionPointProvider, useInsertionPoint } from './use-style-injection/InsertionPointProvider.js';
 export { useComponentCssInjection } from './use-style-injection/useStyleInjection.js';
-export { ClassNameInjectionProvider, registerClassInjector, useInjectedClassName } from './useClassNameInjection.js';
+export { ClassNameInjectionProvider, registerClassInjector, useClassNameInjection } from './useClassNameInjection.js';
 //# sourceMappingURL=index.js.map

package/dist-es/useClassNameInjection.js

@@ -1,40 +1,71 @@
 import { jsx } from 'react/jsx-runtime';
 import { clsx } from 'clsx';
-import { createContext, useMemo, useContext } from 'react';
+import { createContext, useMemo, useEffect, useContext } from 'react';
 
-const InjectionContext = createContext(null);
+const EMPTY_REGISTRY = /* @__PURE__ */ new Map();
+const InjectionContext = createContext(EMPTY_REGISTRY);
+let hasWarnedExperimentalOnce = false;
 function ClassNameInjectionProvider({
   children,
   value
 }) {
-  const registry = useMemo(() => value ?? {}, [value]);
+  const registry = useMemo(() => value ?? EMPTY_REGISTRY, [value]);
+  useEffect(() => {
+    if (!hasWarnedExperimentalOnce && process.env.NODE_ENV !== "production") {
+      console.warn(
+        "Salt ClassNameInjectionProvider is experimental and subject to change. JPM users: only recommended in non-production environments or with prior permission from the Salt team."
+      );
+      hasWarnedExperimentalOnce = true;
+    }
+  }, []);
   return /* @__PURE__ */ jsx(InjectionContext.Provider, { value: registry, children });
 }
-function useInjectedClassName(component, props) {
-  const { className: classNameProp, ...restProps } = props;
+function useClassNameInjection(component, props) {
   const registry = useContext(InjectionContext);
-  if (!registry) {
-    return {
-      className: classNameProp || "",
-      props: restProps
-    };
-  }
-  const entries = registry[component] ?? [];
-  const injected = entries.map((e) => e.fn(restProps)).filter(Boolean);
-  const className = clsx(classNameProp, injected);
-  const cleanProps = { ...restProps };
-  for (const entry of entries) {
-    for (const key of entry.keys) {
-      delete cleanProps[key];
+  const entries = registry.get(component) ?? [];
+  const deps = useMemo(
+    () => entries.length ? entries.flatMap((e) => e.keys.map((k) => props[k])) : [],
+    [entries, props]
+  );
+  const injected = useMemo(() => {
+    const { className: _ignore, ...restProps } = props;
+    if (!entries.length) return [];
+    return entries.map((e) => e.fn(restProps)).filter((v) => v != null);
+  }, [entries, deps, props]);
+  const className = useMemo(
+    () => clsx(props.className, injected) || void 0,
+    [props, injected]
+  );
+  const cleanProps = useMemo(() => {
+    const { className: _ignore, ...restProps } = props;
+    if (!entries.length) {
+      return restProps;
     }
-  }
+    const copy = { ...restProps };
+    for (const entry of entries) {
+      for (const key of entry.keys) {
+        if (Object.hasOwn(copy, key)) {
+          delete copy[key];
+        }
+      }
+    }
+    return copy;
+  }, [entries, deps, props]);
   return { className, props: cleanProps };
 }
 function registerClassInjector(registry, component, keys, injector) {
-  registry[component] ??= [];
-  const wrapped = (props) => injector(props);
-  registry[component] = [...registry[component], { fn: wrapped, keys }];
+  if (!registry.has(component)) {
+    registry.set(component, []);
+  }
+  const wrapped = (props) => {
+    const picked = Object.fromEntries(keys.map((k) => [k, props[k]]));
+    return injector(picked);
+  };
+  registry.get(component).push({
+    fn: wrapped,
+    keys
+  });
 }
 
-export { ClassNameInjectionProvider, registerClassInjector, useInjectedClassName };
+export { ClassNameInjectionProvider, registerClassInjector, useClassNameInjection };
 //# sourceMappingURL=useClassNameInjection.js.map

package/dist-es/useClassNameInjection.js.map

@@ -1 +1 @@
-{"version":3,"file":"useClassNameInjection.js","sources":["../src/useClassNameInjection.tsx"],"sourcesContent":["import { clsx } from \"clsx\";\nimport { createContext, useContext, useMemo } from \"react\";\n\nexport type ClassNameInjector<Props, Keys extends keyof Props> = (\n  props: Pick<Props, Keys>,\n) => string | undefined;\n\ninterface ClassNameInjectorEntry<Props> {\n  fn: (props: Props) => string | undefined;\n  keys: (keyof Props)[];\n}\n\nexport type ClassNameInjectionRegistry = Record<\n  string,\n  // biome-ignore lint/suspicious/noExplicitAny: refer to ClassNameInjector which derives it's entry type based on the Props\n  ClassNameInjectorEntry<any>[]\n>;\n\nconst InjectionContext = createContext<ClassNameInjectionRegistry | null>(null);\n\nexport type ClassNameInjectionProviderProps = {\n  children: React.ReactNode;\n  value?: ClassNameInjectionRegistry;\n};\n\nexport function ClassNameInjectionProvider({\n  children,\n  value,\n}: ClassNameInjectionProviderProps) {\n  const registry = useMemo(() => value ?? {}, [value]);\n  return (\n    <InjectionContext.Provider value={registry}>\n      {children}\n    </InjectionContext.Provider>\n  );\n}\n\ntype PropsWithClassName = { className?: string } & Record<string, any>;\n\nexport function useInjectedClassName<Props extends PropsWithClassName>(\n  component: string,\n  props: Props,\n): { className: string; props: Omit<Props, \"className\"> } {\n  const { className: classNameProp, ...restProps } = props;\n  const registry = useContext(InjectionContext);\n\n  if (!registry) {\n    return {\n      className: classNameProp || \"\",\n      props: restProps as Omit<Props, \"className\">,\n    };\n  }\n\n  const entries = registry[component] ?? [];\n  const injected = entries.map((e) => e.fn(restProps)).filter(Boolean);\n  const className = clsx(classNameProp, injected);\n\n  const cleanProps = { ...restProps } as Omit<Props, \"className\">;\n  for (const entry of entries) {\n    for (const key of entry.keys) {\n      delete (cleanProps as any)[key];\n    }\n  }\n\n  return { className, props: cleanProps };\n}\n\nexport function registerClassInjector<Props, Keys extends keyof Props>(\n  registry: ClassNameInjectionRegistry,\n  component: string,\n  keys: Keys[],\n  injector: ClassNameInjector<Props, Keys>,\n) {\n  registry[component] ??= [];\n  const wrapped = (props: Props) => injector(props as Props);\n  registry[component] = [...registry[component], { fn: wrapped, keys }];\n}\n"],"names":[],"mappings":";;;;AAkBA,MAAM,gBAAA,GAAmB,cAAiD,IAAI,CAAA;AAOvE,SAAS,0BAAA,CAA2B;AAAA,EACzC,QAAA;AAAA,EACA;AACF,CAAA,EAAoC;AAClC,EAAA,MAAM,QAAA,GAAW,QAAQ,MAAM,KAAA,IAAS,EAAC,EAAG,CAAC,KAAK,CAAC,CAAA;AACnD,EAAA,2BACG,gBAAA,CAAiB,QAAA,EAAjB,EAA0B,KAAA,EAAO,UAC/B,QAAA,EACH,CAAA;AAEJ;AAIO,SAAS,oBAAA,CACd,WACA,KAAA,EACwD;AACxD,EAAA,MAAM,EAAE,SAAA,EAAW,aAAA,EAAe,GAAG,WAAU,GAAI,KAAA;AACnD,EAAA,MAAM,QAAA,GAAW,WAAW,gBAAgB,CAAA;AAE5C,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,OAAO;AAAA,MACL,WAAW,aAAA,IAAiB,EAAA;AAAA,MAC5B,KAAA,EAAO;AAAA,KACT;AAAA,EACF;AAEA,EAAA,MAAM,OAAA,GAAU,QAAA,CAAS,SAAS,CAAA,IAAK,EAAC;AACxC,EAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,EAAA,CAAG,SAAS,CAAC,CAAA,CAAE,MAAA,CAAO,OAAO,CAAA;AACnE,EAAA,MAAM,SAAA,GAAY,IAAA,CAAK,aAAA,EAAe,QAAQ,CAAA;AAE9C,EAAA,MAAM,UAAA,GAAa,EAAE,GAAG,SAAA,EAAU;AAClC,EAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,IAAA,KAAA,MAAW,GAAA,IAAO,MAAM,IAAA,EAAM;AAC5B,MAAA,OAAQ,WAAmB,GAAG,CAAA;AAAA,IAChC;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,SAAA,EAAW,KAAA,EAAO,UAAA,EAAW;AACxC;AAEO,SAAS,qBAAA,CACd,QAAA,EACA,SAAA,EACA,IAAA,EACA,QAAA,EACA;AACA,EAAA,QAAA,CAAS,SAAS,MAAM,EAAC;AACzB,EAAA,MAAM,OAAA,GAAU,CAAC,KAAA,KAAiB,QAAA,CAAS,KAAc,CAAA;AACzD,EAAA,QAAA,CAAS,SAAS,CAAA,GAAI,CAAC,GAAG,QAAA,CAAS,SAAS,CAAA,EAAG,EAAE,EAAA,EAAI,OAAA,EAAS,IAAA,EAAM,CAAA;AACtE;;;;"}
+{"version":3,"file":"useClassNameInjection.js","sources":["../src/useClassNameInjection.tsx"],"sourcesContent":["import { clsx } from \"clsx\";\nimport { createContext, useContext, useEffect, useMemo } from \"react\";\n\n/**\n * Extensible map of supported components → their props.\n * @salt-ds/core must augment this with the components that support the API,\n * using the same key string that the component passes to useClassNameInjection,\n * e.g., \"saltButton\": ButtonProps.\n */\nexport type ComponentPropMap = {};\n\n/** Component key type: only keys declared in ComponentPropMap are allowed. */\ntype SupportedComponent = keyof ComponentPropMap extends never\n  ? string\n  : keyof ComponentPropMap;\n\nexport type ClassNameInjector<Props, Keys extends keyof Props> = (\n  props: Pick<Props, Keys>,\n) => string | undefined;\n\ninterface ClassNameInjectorEntry {\n  fn: (props: unknown) => string | undefined;\n  keys: string[];\n}\n\nexport type ClassNameInjectionRegistry = Map<\n  SupportedComponent,\n  ClassNameInjectorEntry[]\n>;\n\nconst EMPTY_REGISTRY: ClassNameInjectionRegistry = new Map();\nconst InjectionContext =\n  createContext<ClassNameInjectionRegistry>(EMPTY_REGISTRY);\n\nexport type ClassNameInjectionProviderProps = {\n  children: React.ReactNode;\n  value?: ClassNameInjectionRegistry;\n};\n\nlet hasWarnedExperimentalOnce = false;\n\nexport function ClassNameInjectionProvider({\n  children,\n  value,\n}: ClassNameInjectionProviderProps) {\n  const registry = useMemo(() => value ?? EMPTY_REGISTRY, [value]);\n\n  useEffect(() => {\n    if (!hasWarnedExperimentalOnce && process.env.NODE_ENV !== \"production\") {\n      // eslint-disable-next-line no-console\n      console.warn(\n        \"Salt ClassNameInjectionProvider is experimental and subject to change. JPM users: only recommended in non-production environments or with prior permission from the Salt team.\",\n      );\n      hasWarnedExperimentalOnce = true;\n    }\n  }, []);\n\n  return (\n    <InjectionContext.Provider value={registry}>\n      {children}\n    </InjectionContext.Provider>\n  );\n}\n\ntype PropsWithClassName = { className?: string } & Record<string, any>;\n\n/**\n * Return the className created by the registry and a props object with injector keys stripped.\n * Only components declared in ComponentPropMap can call this at compile time.\n */\nexport function useClassNameInjection<Props extends PropsWithClassName>(\n  component: SupportedComponent,\n  props: Props,\n): { className: string | undefined; props: Omit<Props, \"className\"> } {\n  const registry = useContext(InjectionContext);\n  const entries = registry.get(component) ?? [];\n\n  const deps = useMemo(\n    () =>\n      entries.length\n        ? entries.flatMap((e) => e.keys.map((k) => (props as any)[k]))\n        : [],\n    [entries, props],\n  );\n\n  // Compute injected classes provided through ClassNameInjectionRegistry\n  const injected = useMemo(() => {\n    const { className: _ignore, ...restProps } = props as any;\n    if (!entries.length) return [];\n    return entries\n      .map((e) => e.fn(restProps))\n      .filter((v): v is string => v != null);\n  }, [entries, deps, props]);\n\n  // Merge original className with injected classes\n  const className = useMemo(\n    () => clsx((props as any).className, injected) || undefined,\n    [props, injected],\n  );\n\n  // Create a cleaned props object by stripping keys used by injectors, to avoid DOM errors with unknown attributes\n  const cleanProps = useMemo(() => {\n    const { className: _ignore, ...restProps } = props as any;\n    if (!entries.length) {\n      return restProps as Omit<Props, \"className\">;\n    }\n    const copy = { ...restProps } as Omit<Props, \"className\">;\n    for (const entry of entries) {\n      for (const key of entry.keys) {\n        if (Object.hasOwn(copy, key)) {\n          delete (copy as any)[key];\n        }\n      }\n    }\n    return copy;\n  }, [entries, deps, props]);\n\n  return { className, props: cleanProps };\n}\n\n/**\n * Register a class injector for a supported component name.\n * - Keys must be valid string keys for that component’s props (as declared in ComponentPropMap).\n * - Injector receives only the declared keys (Pick<PropsOf<C>, Keys>).\n */\nexport function registerClassInjector<\n  Props extends Record<string, any>,\n  Keys extends Extract<keyof Props, string>,\n>(\n  registry: ClassNameInjectionRegistry,\n  component: SupportedComponent,\n  keys: Keys[],\n  injector: ClassNameInjector<Props, Keys>,\n) {\n  if (!registry.has(component)) {\n    registry.set(component, []);\n  }\n\n  const wrapped = (props: Record<string, any>) => {\n    const picked = Object.fromEntries(keys.map((k) => [k, props[k]])) as Pick<\n      Props,\n      Keys\n    >;\n    return injector(picked);\n  };\n\n  registry.get(component)!.push({\n    fn: wrapped as (props: unknown) => string | undefined,\n    keys: keys as string[],\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist-types/useClassNameInjection.d.ts

@@ -1,9 +1,18 @@
+/**
+ * Extensible map of supported components → their props.
+ * @salt-ds/core must augment this with the components that support the API,
+ * using the same key string that the component passes to useClassNameInjection,
+ * e.g., "saltButton": ButtonProps.
+ */
+export type ComponentPropMap = {};
+/** Component key type: only keys declared in ComponentPropMap are allowed. */
+type SupportedComponent = keyof ComponentPropMap extends never ? string : keyof ComponentPropMap;
 export type ClassNameInjector<Props, Keys extends keyof Props> = (props: Pick<Props, Keys>) => string | undefined;
-interface ClassNameInjectorEntry<Props> {
-    fn: (props: Props) => string | undefined;
-    keys: (keyof Props)[];
+interface ClassNameInjectorEntry {
+    fn: (props: unknown) => string | undefined;
+    keys: string[];
 }
-export type ClassNameInjectionRegistry = Record<string, ClassNameInjectorEntry<any>[]>;
+export type ClassNameInjectionRegistry = Map<SupportedComponent, ClassNameInjectorEntry[]>;
 export type ClassNameInjectionProviderProps = {
     children: React.ReactNode;
     value?: ClassNameInjectionRegistry;
@@ -12,9 +21,18 @@ export declare function ClassNameInjectionProvider({ children, value, }: ClassNa
 type PropsWithClassName = {
     className?: string;
 } & Record<string, any>;
-export declare function useInjectedClassName<Props extends PropsWithClassName>(component: string, props: Props): {
-    className: string;
+/**
+ * Return the className created by the registry and a props object with injector keys stripped.
+ * Only components declared in ComponentPropMap can call this at compile time.
+ */
+export declare function useClassNameInjection<Props extends PropsWithClassName>(component: SupportedComponent, props: Props): {
+    className: string | undefined;
     props: Omit<Props, "className">;
 };
-export declare function registerClassInjector<Props, Keys extends keyof Props>(registry: ClassNameInjectionRegistry, component: string, keys: Keys[], injector: ClassNameInjector<Props, Keys>): void;
+/**
+ * Register a class injector for a supported component name.
+ * - Keys must be valid string keys for that component’s props (as declared in ComponentPropMap).
+ * - Injector receives only the declared keys (Pick<PropsOf<C>, Keys>).
+ */
+export declare function registerClassInjector<Props extends Record<string, any>, Keys extends Extract<keyof Props, string>>(registry: ClassNameInjectionRegistry, component: SupportedComponent, keys: Keys[], injector: ClassNameInjector<Props, Keys>): void;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salt-ds/styles",
-  "version": "0.0.0-snapshot-20260109210611",
+  "version": "0.0.0-snapshot-20260112210403",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",