@protohiro/state-layers 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 protohiro.com
+
+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

@@ -0,0 +1,7 @@
+# @protohiro/state-layers
+
+React hooks for visual state layers on existing elements.
+
+This package provides CSS-first hooks like `useFocusRingLayer`, `useInvalidStateLayer`, and `useLoadingSheenLayer` without wrapper components or layout measurement.
+
+For workspace docs and demo usage, see the root [`README.md`](../../README.md).

package/dist/index.cjs

@@ -0,0 +1,474 @@
+"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, {
+  mergeRefs: () => mergeRefs,
+  useFocusRingLayer: () => useFocusRingLayer,
+  useInvalidStateLayer: () => useInvalidStateLayer,
+  useLoadingSheenLayer: () => useLoadingSheenLayer
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/runtime.ts
+var import_react = require("react");
+
+// src/styles.ts
+var STYLE_ELEMENT_ID = "protohiro-state-layers-styles";
+var STATE_LAYER_CSS = `
+.psl-anchor {
+  position: relative;
+}
+
+.psl-focus-ring,
+.psl-invalid,
+.psl-loading {
+  isolation: isolate;
+}
+
+.psl-focus-ring {
+  --psl-focus-ring-color: rgba(59, 130, 246, 0.9);
+  --psl-focus-ring-inset: 0px;
+  --psl-focus-ring-offset: 0px;
+  --psl-focus-ring-width: 2px;
+}
+
+.psl-focus-ring::before {
+  border-radius: inherit;
+  box-shadow: 0 0 0 var(--psl-focus-ring-width) var(--psl-focus-ring-color);
+  content: "";
+  inset: calc(var(--psl-focus-ring-inset) - var(--psl-focus-ring-offset));
+  opacity: 1;
+  pointer-events: none;
+  position: absolute;
+  transition: opacity 140ms ease, transform 140ms ease;
+  transform: scale(1);
+}
+
+.psl-invalid,
+.psl-loading {
+  --psl-invalid-color: rgba(239, 68, 68, 0.92);
+  --psl-invalid-inset: 0px;
+  --psl-invalid-shadow-width: 0px;
+  --psl-invalid-width: 0px;
+  --psl-invalid-opacity: 0;
+  --psl-invalid-visible-color: var(--psl-invalid-color);
+  --psl-loading-angle: 110deg;
+  --psl-loading-duration: 1400ms;
+  --psl-loading-intensity: 0;
+  --psl-loading-sheen-color: rgba(255, 255, 255, 0.9);
+}
+
+.psl-invalid::after,
+.psl-loading::after {
+  border-radius: inherit;
+  box-shadow: 0 0 0 var(--psl-invalid-shadow-width) var(--psl-invalid-visible-color);
+  content: "";
+  inset: var(--psl-invalid-inset);
+  opacity: var(--psl-invalid-opacity);
+  pointer-events: none;
+  position: absolute;
+}
+
+.psl-loading::after,
+.psl-invalid.psl-loading::after {
+  background-image: linear-gradient(
+    var(--psl-loading-angle),
+    transparent 0%,
+    transparent 45%,
+    var(--psl-loading-sheen-color) 50%,
+    transparent 100%
+  );
+  background-position: 200% 50%;
+  background-repeat: no-repeat;
+  background-size: 220% 100%;
+}
+
+.psl-loading:not(.psl-invalid)::after {
+  opacity: var(--psl-loading-intensity);
+}
+
+.psl-invalid.psl-loading::after {
+  opacity: var(--psl-invalid-opacity);
+}
+
+.psl-invalid:is(input, textarea, select) {
+  --psl-invalid-shadow-width: 0px;
+}
+
+.psl-invalid:is(input, textarea, select) {
+  outline: var(--psl-invalid-width-input, 0px) solid var(--psl-invalid-visible-color);
+  outline-offset: var(--psl-invalid-inset);
+}
+
+.psl-invalid {
+  --psl-invalid-shadow-width: var(--psl-invalid-width);
+  --psl-invalid-width-input: var(--psl-invalid-width);
+}
+
+.psl-loading::after {
+  animation: psl-loading-sheen var(--psl-loading-duration) linear infinite;
+}
+
+@keyframes psl-loading-sheen {
+  from {
+    background-position: 200% 50%;
+  }
+
+  to {
+    background-position: -120% 50%;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .psl-loading::after {
+    animation-duration: calc(var(--psl-loading-duration) * 2);
+  }
+}
+
+@supports (color: color-mix(in srgb, black 50%, white 50%)) {
+  .psl-focus-ring {
+    --psl-focus-ring-color: color-mix(in srgb, #3b82f6 78%, white 22%);
+  }
+
+  .psl-invalid,
+  .psl-loading {
+    --psl-invalid-color: color-mix(in srgb, #ef4444 82%, white 18%);
+    --psl-invalid-visible-color: color-mix(
+      in srgb,
+      var(--psl-invalid-color) calc(var(--psl-invalid-opacity) * 100%),
+      transparent
+    );
+  }
+
+  .psl-invalid:not(.psl-loading)::after {
+    opacity: 1;
+  }
+
+  .psl-loading::after,
+  .psl-invalid.psl-loading::after {
+    background-image: linear-gradient(
+      var(--psl-loading-angle),
+      transparent 0%,
+      color-mix(in srgb, var(--psl-loading-sheen-color) calc(var(--psl-loading-intensity) * 100%), transparent) 45%,
+      color-mix(in srgb, var(--psl-loading-sheen-color) calc(var(--psl-loading-intensity) * 100%), transparent) 55%,
+      transparent 100%
+    );
+    opacity: 1;
+  }
+}
+`;
+
+// src/runtime.ts
+var hasInjectedStyles = false;
+var anchorConsumers = /* @__PURE__ */ new WeakMap();
+var useIsomorphicLayoutEffect = typeof window === "undefined" ? import_react.useEffect : import_react.useLayoutEffect;
+var MISSING_ATTRIBUTE = "__psl_missing_attribute__";
+function ensureGlobalStyles() {
+  if (hasInjectedStyles || typeof document === "undefined") {
+    return;
+  }
+  const existing = document.getElementById(STYLE_ELEMENT_ID);
+  if (existing) {
+    hasInjectedStyles = true;
+    return;
+  }
+  const style = document.createElement("style");
+  style.id = STYLE_ELEMENT_ID;
+  style.textContent = STATE_LAYER_CSS;
+  document.head.appendChild(style);
+  hasInjectedStyles = true;
+}
+function mergeRefs(...refs) {
+  return (value) => {
+    for (const ref of refs) {
+      if (!ref) {
+        continue;
+      }
+      if (typeof ref === "function") {
+        ref(value);
+        continue;
+      }
+      ref.current = value;
+    }
+  };
+}
+function useMergedNodeRef(...refs) {
+  const [node, setNode] = (0, import_react.useState)(null);
+  const mergedRef = (0, import_react.useMemo)(() => mergeRefs(setNode, ...refs), refs);
+  return [node, mergedRef];
+}
+function addAnchorConsumer(element) {
+  const current = anchorConsumers.get(element);
+  if (!current) {
+    anchorConsumers.set(element, {
+      count: 1,
+      hadClass: element.classList.contains("psl-anchor")
+    });
+    element.classList.add("psl-anchor");
+    return;
+  }
+  anchorConsumers.set(element, {
+    ...current,
+    count: current.count + 1
+  });
+}
+function removeAnchorConsumer(element) {
+  const currentCount = anchorConsumers.get(element);
+  if (!currentCount) {
+    return;
+  }
+  if (currentCount.count === 1) {
+    anchorConsumers.delete(element);
+    if (!currentCount.hadClass) {
+      element.classList.remove("psl-anchor");
+    }
+    return;
+  }
+  anchorConsumers.set(element, {
+    ...currentCount,
+    count: currentCount.count - 1
+  });
+}
+function applyStateLayer(element, className, requireAnchor = true) {
+  const touchedVariables = /* @__PURE__ */ new Set();
+  const baselineAttributes = /* @__PURE__ */ new Map();
+  let currentAttributes = {};
+  let anchorApplied = false;
+  let isActive = false;
+  const sync = (nextVariables, nextActive, nextAttributes) => {
+    if (nextActive) {
+      element.classList.add(className);
+      if (requireAnchor && !anchorApplied && !element.style.position) {
+        addAnchorConsumer(element);
+        anchorApplied = true;
+      }
+    } else {
+      element.classList.remove(className);
+      if (anchorApplied) {
+        removeAnchorConsumer(element);
+        anchorApplied = false;
+      }
+    }
+    const nextVariableEntries = nextActive ? nextVariables : {};
+    for (const variable of Array.from(touchedVariables)) {
+      if (!(variable in nextVariableEntries) || nextVariableEntries[variable] == null) {
+        element.style.removeProperty(variable);
+        touchedVariables.delete(variable);
+      }
+    }
+    for (const [variable, value] of Object.entries(nextVariableEntries)) {
+      if (value == null) {
+        element.style.removeProperty(variable);
+        touchedVariables.delete(variable);
+      } else {
+        element.style.setProperty(variable, value);
+        touchedVariables.add(variable);
+      }
+    }
+    const nextAttributeEntries = nextActive ? nextAttributes ?? {} : {};
+    for (const name of Object.keys(currentAttributes)) {
+      if (!(name in nextAttributeEntries) || nextAttributeEntries[name] == null) {
+        const baselineValue = baselineAttributes.get(name);
+        if (baselineValue == null || baselineValue === MISSING_ATTRIBUTE) {
+          element.removeAttribute(name);
+        } else {
+          element.setAttribute(name, baselineValue);
+        }
+      }
+    }
+    for (const [name, value] of Object.entries(nextAttributeEntries)) {
+      if (!baselineAttributes.has(name)) {
+        baselineAttributes.set(name, element.getAttribute(name) ?? MISSING_ATTRIBUTE);
+      }
+      if (value == null) {
+        const baselineValue = baselineAttributes.get(name);
+        if (baselineValue == null || baselineValue === MISSING_ATTRIBUTE) {
+          element.removeAttribute(name);
+        } else {
+          element.setAttribute(name, baselineValue);
+        }
+      } else {
+        element.setAttribute(name, value);
+      }
+    }
+    currentAttributes = { ...nextAttributeEntries };
+    isActive = nextActive;
+  };
+  return {
+    update(nextVariables, nextActive, nextAttributes) {
+      sync(nextVariables, nextActive, nextAttributes);
+    },
+    cleanup() {
+      if (isActive) {
+        element.classList.remove(className);
+      }
+      if (anchorApplied) {
+        removeAnchorConsumer(element);
+      }
+      for (const variable of touchedVariables) {
+        element.style.removeProperty(variable);
+      }
+      for (const name of Object.keys(currentAttributes)) {
+        const baselineValue = baselineAttributes.get(name);
+        if (baselineValue == null || baselineValue === MISSING_ATTRIBUTE) {
+          element.removeAttribute(name);
+        } else {
+          element.setAttribute(name, baselineValue);
+        }
+      }
+      currentAttributes = {};
+      isActive = false;
+      anchorApplied = false;
+    }
+  };
+}
+function useStateLayer({
+  active = true,
+  className,
+  variables = {},
+  attributes,
+  requireAnchor = true
+}) {
+  const [node, ref] = useMergedNodeRef();
+  const layerRef = (0, import_react.useRef)(null);
+  useIsomorphicLayoutEffect(() => {
+    ensureGlobalStyles();
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    if (!node) {
+      return;
+    }
+    const layer = applyStateLayer(node, className, requireAnchor);
+    layerRef.current = layer;
+    layer.update(variables, active, attributes);
+    return () => {
+      layer.cleanup();
+      layerRef.current = null;
+    };
+  }, [className, node, requireAnchor]);
+  useIsomorphicLayoutEffect(() => {
+    layerRef.current?.update(variables, active, attributes);
+  }, [active, attributes, variables]);
+  return (0, import_react.useCallback)((nextNode) => {
+    ref(nextNode);
+  }, [ref]);
+}
+
+// src/hooks/useFocusRingLayer.ts
+var import_react2 = require("react");
+var useIsomorphicLayoutEffect2 = typeof window === "undefined" ? import_react2.useEffect : import_react2.useLayoutEffect;
+function readFocusVisible(node) {
+  if (typeof node.matches === "function") {
+    try {
+      return node.matches(":focus-visible");
+    } catch {
+      return document.activeElement === node;
+    }
+  }
+  return document.activeElement === node;
+}
+function useFocusRingLayer(options = {}) {
+  const { color, inset, offset, ref, visible, width } = options;
+  const [focusVisible, setFocusVisible] = (0, import_react2.useState)(Boolean(visible));
+  const [node, mergedRef] = useMergedNodeRef(ref);
+  useIsomorphicLayoutEffect2(() => {
+    if (visible != null) {
+      setFocusVisible(visible);
+      return;
+    }
+    if (!node) {
+      return;
+    }
+    setFocusVisible(readFocusVisible(node));
+  }, [node, visible]);
+  (0, import_react2.useEffect)(() => {
+    if (!node || visible != null) {
+      return;
+    }
+    const onFocus = () => {
+      setFocusVisible(readFocusVisible(node));
+    };
+    const onBlur = () => setFocusVisible(false);
+    node.addEventListener("focus", onFocus);
+    node.addEventListener("blur", onBlur);
+    return () => {
+      node.removeEventListener("focus", onFocus);
+      node.removeEventListener("blur", onBlur);
+    };
+  }, [node, visible]);
+  const layerRef = useStateLayer({
+    active: focusVisible,
+    className: "psl-focus-ring",
+    variables: {
+      "--psl-focus-ring-color": color,
+      "--psl-focus-ring-inset": inset,
+      "--psl-focus-ring-offset": offset,
+      "--psl-focus-ring-width": width
+    }
+  });
+  return (0, import_react2.useMemo)(() => {
+    return (nextNode) => {
+      mergedRef(nextNode);
+      layerRef(nextNode);
+    };
+  }, [layerRef, mergedRef]);
+}
+
+// src/hooks/useInvalidStateLayer.ts
+var import_react3 = require("react");
+function useInvalidStateLayer(options = {}) {
+  const { active = false, color, inset, opacity, ref, width } = options;
+  const layerRef = useStateLayer({
+    active,
+    className: "psl-invalid",
+    variables: {
+      "--psl-invalid-color": color,
+      "--psl-invalid-inset": inset,
+      "--psl-invalid-opacity": opacity == null ? void 0 : String(opacity),
+      "--psl-invalid-width": width
+    }
+  });
+  return (0, import_react3.useMemo)(() => mergeRefs(layerRef, ref), [layerRef, ref]);
+}
+
+// src/hooks/useLoadingSheenLayer.ts
+var import_react4 = require("react");
+function useLoadingSheenLayer(options = {}) {
+  const { active = false, angle, duration, intensity, ref, sheenColor } = options;
+  const layerRef = useStateLayer({
+    active,
+    className: "psl-loading",
+    variables: {
+      "--psl-loading-angle": angle,
+      "--psl-loading-duration": duration,
+      "--psl-loading-intensity": intensity == null ? void 0 : String(intensity),
+      "--psl-loading-sheen-color": sheenColor
+    }
+  });
+  return (0, import_react4.useMemo)(() => mergeRefs(layerRef, ref), [layerRef, ref]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  mergeRefs,
+  useFocusRingLayer,
+  useInvalidStateLayer,
+  useLoadingSheenLayer
+});

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+declare function mergeRefs<T>(...refs: Array<React.Ref<T> | undefined>): React.RefCallback<T>;
+
+type FocusRingLayerOptions<T extends HTMLElement> = {
+    color?: string;
+    inset?: string;
+    offset?: string;
+    visible?: boolean;
+    width?: string;
+    ref?: React.Ref<T>;
+};
+declare function useFocusRingLayer<T extends HTMLElement = HTMLElement>(options?: FocusRingLayerOptions<T>): React.RefCallback<T>;
+
+type InvalidStateLayerOptions<T extends HTMLElement> = {
+    active?: boolean;
+    color?: string;
+    inset?: string;
+    opacity?: number;
+    ref?: React.Ref<T>;
+    width?: string;
+};
+declare function useInvalidStateLayer<T extends HTMLElement = HTMLElement>(options?: InvalidStateLayerOptions<T>): React.RefCallback<T>;
+
+type LoadingSheenLayerOptions<T extends HTMLElement> = {
+    active?: boolean;
+    angle?: string;
+    duration?: string;
+    intensity?: number;
+    ref?: React.Ref<T>;
+    sheenColor?: string;
+};
+declare function useLoadingSheenLayer<T extends HTMLElement = HTMLElement>(options?: LoadingSheenLayerOptions<T>): React.RefCallback<T>;
+
+export { type FocusRingLayerOptions, type InvalidStateLayerOptions, type LoadingSheenLayerOptions, mergeRefs, useFocusRingLayer, useInvalidStateLayer, useLoadingSheenLayer };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+declare function mergeRefs<T>(...refs: Array<React.Ref<T> | undefined>): React.RefCallback<T>;
+
+type FocusRingLayerOptions<T extends HTMLElement> = {
+    color?: string;
+    inset?: string;
+    offset?: string;
+    visible?: boolean;
+    width?: string;
+    ref?: React.Ref<T>;
+};
+declare function useFocusRingLayer<T extends HTMLElement = HTMLElement>(options?: FocusRingLayerOptions<T>): React.RefCallback<T>;
+
+type InvalidStateLayerOptions<T extends HTMLElement> = {
+    active?: boolean;
+    color?: string;
+    inset?: string;
+    opacity?: number;
+    ref?: React.Ref<T>;
+    width?: string;
+};
+declare function useInvalidStateLayer<T extends HTMLElement = HTMLElement>(options?: InvalidStateLayerOptions<T>): React.RefCallback<T>;
+
+type LoadingSheenLayerOptions<T extends HTMLElement> = {
+    active?: boolean;
+    angle?: string;
+    duration?: string;
+    intensity?: number;
+    ref?: React.Ref<T>;
+    sheenColor?: string;
+};
+declare function useLoadingSheenLayer<T extends HTMLElement = HTMLElement>(options?: LoadingSheenLayerOptions<T>): React.RefCallback<T>;
+
+export { type FocusRingLayerOptions, type InvalidStateLayerOptions, type LoadingSheenLayerOptions, mergeRefs, useFocusRingLayer, useInvalidStateLayer, useLoadingSheenLayer };

package/dist/index.js

@@ -0,0 +1,444 @@
+// src/runtime.ts
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+
+// src/styles.ts
+var STYLE_ELEMENT_ID = "protohiro-state-layers-styles";
+var STATE_LAYER_CSS = `
+.psl-anchor {
+  position: relative;
+}
+
+.psl-focus-ring,
+.psl-invalid,
+.psl-loading {
+  isolation: isolate;
+}
+
+.psl-focus-ring {
+  --psl-focus-ring-color: rgba(59, 130, 246, 0.9);
+  --psl-focus-ring-inset: 0px;
+  --psl-focus-ring-offset: 0px;
+  --psl-focus-ring-width: 2px;
+}
+
+.psl-focus-ring::before {
+  border-radius: inherit;
+  box-shadow: 0 0 0 var(--psl-focus-ring-width) var(--psl-focus-ring-color);
+  content: "";
+  inset: calc(var(--psl-focus-ring-inset) - var(--psl-focus-ring-offset));
+  opacity: 1;
+  pointer-events: none;
+  position: absolute;
+  transition: opacity 140ms ease, transform 140ms ease;
+  transform: scale(1);
+}
+
+.psl-invalid,
+.psl-loading {
+  --psl-invalid-color: rgba(239, 68, 68, 0.92);
+  --psl-invalid-inset: 0px;
+  --psl-invalid-shadow-width: 0px;
+  --psl-invalid-width: 0px;
+  --psl-invalid-opacity: 0;
+  --psl-invalid-visible-color: var(--psl-invalid-color);
+  --psl-loading-angle: 110deg;
+  --psl-loading-duration: 1400ms;
+  --psl-loading-intensity: 0;
+  --psl-loading-sheen-color: rgba(255, 255, 255, 0.9);
+}
+
+.psl-invalid::after,
+.psl-loading::after {
+  border-radius: inherit;
+  box-shadow: 0 0 0 var(--psl-invalid-shadow-width) var(--psl-invalid-visible-color);
+  content: "";
+  inset: var(--psl-invalid-inset);
+  opacity: var(--psl-invalid-opacity);
+  pointer-events: none;
+  position: absolute;
+}
+
+.psl-loading::after,
+.psl-invalid.psl-loading::after {
+  background-image: linear-gradient(
+    var(--psl-loading-angle),
+    transparent 0%,
+    transparent 45%,
+    var(--psl-loading-sheen-color) 50%,
+    transparent 100%
+  );
+  background-position: 200% 50%;
+  background-repeat: no-repeat;
+  background-size: 220% 100%;
+}
+
+.psl-loading:not(.psl-invalid)::after {
+  opacity: var(--psl-loading-intensity);
+}
+
+.psl-invalid.psl-loading::after {
+  opacity: var(--psl-invalid-opacity);
+}
+
+.psl-invalid:is(input, textarea, select) {
+  --psl-invalid-shadow-width: 0px;
+}
+
+.psl-invalid:is(input, textarea, select) {
+  outline: var(--psl-invalid-width-input, 0px) solid var(--psl-invalid-visible-color);
+  outline-offset: var(--psl-invalid-inset);
+}
+
+.psl-invalid {
+  --psl-invalid-shadow-width: var(--psl-invalid-width);
+  --psl-invalid-width-input: var(--psl-invalid-width);
+}
+
+.psl-loading::after {
+  animation: psl-loading-sheen var(--psl-loading-duration) linear infinite;
+}
+
+@keyframes psl-loading-sheen {
+  from {
+    background-position: 200% 50%;
+  }
+
+  to {
+    background-position: -120% 50%;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .psl-loading::after {
+    animation-duration: calc(var(--psl-loading-duration) * 2);
+  }
+}
+
+@supports (color: color-mix(in srgb, black 50%, white 50%)) {
+  .psl-focus-ring {
+    --psl-focus-ring-color: color-mix(in srgb, #3b82f6 78%, white 22%);
+  }
+
+  .psl-invalid,
+  .psl-loading {
+    --psl-invalid-color: color-mix(in srgb, #ef4444 82%, white 18%);
+    --psl-invalid-visible-color: color-mix(
+      in srgb,
+      var(--psl-invalid-color) calc(var(--psl-invalid-opacity) * 100%),
+      transparent
+    );
+  }
+
+  .psl-invalid:not(.psl-loading)::after {
+    opacity: 1;
+  }
+
+  .psl-loading::after,
+  .psl-invalid.psl-loading::after {
+    background-image: linear-gradient(
+      var(--psl-loading-angle),
+      transparent 0%,
+      color-mix(in srgb, var(--psl-loading-sheen-color) calc(var(--psl-loading-intensity) * 100%), transparent) 45%,
+      color-mix(in srgb, var(--psl-loading-sheen-color) calc(var(--psl-loading-intensity) * 100%), transparent) 55%,
+      transparent 100%
+    );
+    opacity: 1;
+  }
+}
+`;
+
+// src/runtime.ts
+var hasInjectedStyles = false;
+var anchorConsumers = /* @__PURE__ */ new WeakMap();
+var useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+var MISSING_ATTRIBUTE = "__psl_missing_attribute__";
+function ensureGlobalStyles() {
+  if (hasInjectedStyles || typeof document === "undefined") {
+    return;
+  }
+  const existing = document.getElementById(STYLE_ELEMENT_ID);
+  if (existing) {
+    hasInjectedStyles = true;
+    return;
+  }
+  const style = document.createElement("style");
+  style.id = STYLE_ELEMENT_ID;
+  style.textContent = STATE_LAYER_CSS;
+  document.head.appendChild(style);
+  hasInjectedStyles = true;
+}
+function mergeRefs(...refs) {
+  return (value) => {
+    for (const ref of refs) {
+      if (!ref) {
+        continue;
+      }
+      if (typeof ref === "function") {
+        ref(value);
+        continue;
+      }
+      ref.current = value;
+    }
+  };
+}
+function useMergedNodeRef(...refs) {
+  const [node, setNode] = useState(null);
+  const mergedRef = useMemo(() => mergeRefs(setNode, ...refs), refs);
+  return [node, mergedRef];
+}
+function addAnchorConsumer(element) {
+  const current = anchorConsumers.get(element);
+  if (!current) {
+    anchorConsumers.set(element, {
+      count: 1,
+      hadClass: element.classList.contains("psl-anchor")
+    });
+    element.classList.add("psl-anchor");
+    return;
+  }
+  anchorConsumers.set(element, {
+    ...current,
+    count: current.count + 1
+  });
+}
+function removeAnchorConsumer(element) {
+  const currentCount = anchorConsumers.get(element);
+  if (!currentCount) {
+    return;
+  }
+  if (currentCount.count === 1) {
+    anchorConsumers.delete(element);
+    if (!currentCount.hadClass) {
+      element.classList.remove("psl-anchor");
+    }
+    return;
+  }
+  anchorConsumers.set(element, {
+    ...currentCount,
+    count: currentCount.count - 1
+  });
+}
+function applyStateLayer(element, className, requireAnchor = true) {
+  const touchedVariables = /* @__PURE__ */ new Set();
+  const baselineAttributes = /* @__PURE__ */ new Map();
+  let currentAttributes = {};
+  let anchorApplied = false;
+  let isActive = false;
+  const sync = (nextVariables, nextActive, nextAttributes) => {
+    if (nextActive) {
+      element.classList.add(className);
+      if (requireAnchor && !anchorApplied && !element.style.position) {
+        addAnchorConsumer(element);
+        anchorApplied = true;
+      }
+    } else {
+      element.classList.remove(className);
+      if (anchorApplied) {
+        removeAnchorConsumer(element);
+        anchorApplied = false;
+      }
+    }
+    const nextVariableEntries = nextActive ? nextVariables : {};
+    for (const variable of Array.from(touchedVariables)) {
+      if (!(variable in nextVariableEntries) || nextVariableEntries[variable] == null) {
+        element.style.removeProperty(variable);
+        touchedVariables.delete(variable);
+      }
+    }
+    for (const [variable, value] of Object.entries(nextVariableEntries)) {
+      if (value == null) {
+        element.style.removeProperty(variable);
+        touchedVariables.delete(variable);
+      } else {
+        element.style.setProperty(variable, value);
+        touchedVariables.add(variable);
+      }
+    }
+    const nextAttributeEntries = nextActive ? nextAttributes ?? {} : {};
+    for (const name of Object.keys(currentAttributes)) {
+      if (!(name in nextAttributeEntries) || nextAttributeEntries[name] == null) {
+        const baselineValue = baselineAttributes.get(name);
+        if (baselineValue == null || baselineValue === MISSING_ATTRIBUTE) {
+          element.removeAttribute(name);
+        } else {
+          element.setAttribute(name, baselineValue);
+        }
+      }
+    }
+    for (const [name, value] of Object.entries(nextAttributeEntries)) {
+      if (!baselineAttributes.has(name)) {
+        baselineAttributes.set(name, element.getAttribute(name) ?? MISSING_ATTRIBUTE);
+      }
+      if (value == null) {
+        const baselineValue = baselineAttributes.get(name);
+        if (baselineValue == null || baselineValue === MISSING_ATTRIBUTE) {
+          element.removeAttribute(name);
+        } else {
+          element.setAttribute(name, baselineValue);
+        }
+      } else {
+        element.setAttribute(name, value);
+      }
+    }
+    currentAttributes = { ...nextAttributeEntries };
+    isActive = nextActive;
+  };
+  return {
+    update(nextVariables, nextActive, nextAttributes) {
+      sync(nextVariables, nextActive, nextAttributes);
+    },
+    cleanup() {
+      if (isActive) {
+        element.classList.remove(className);
+      }
+      if (anchorApplied) {
+        removeAnchorConsumer(element);
+      }
+      for (const variable of touchedVariables) {
+        element.style.removeProperty(variable);
+      }
+      for (const name of Object.keys(currentAttributes)) {
+        const baselineValue = baselineAttributes.get(name);
+        if (baselineValue == null || baselineValue === MISSING_ATTRIBUTE) {
+          element.removeAttribute(name);
+        } else {
+          element.setAttribute(name, baselineValue);
+        }
+      }
+      currentAttributes = {};
+      isActive = false;
+      anchorApplied = false;
+    }
+  };
+}
+function useStateLayer({
+  active = true,
+  className,
+  variables = {},
+  attributes,
+  requireAnchor = true
+}) {
+  const [node, ref] = useMergedNodeRef();
+  const layerRef = useRef(null);
+  useIsomorphicLayoutEffect(() => {
+    ensureGlobalStyles();
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    if (!node) {
+      return;
+    }
+    const layer = applyStateLayer(node, className, requireAnchor);
+    layerRef.current = layer;
+    layer.update(variables, active, attributes);
+    return () => {
+      layer.cleanup();
+      layerRef.current = null;
+    };
+  }, [className, node, requireAnchor]);
+  useIsomorphicLayoutEffect(() => {
+    layerRef.current?.update(variables, active, attributes);
+  }, [active, attributes, variables]);
+  return useCallback((nextNode) => {
+    ref(nextNode);
+  }, [ref]);
+}
+
+// src/hooks/useFocusRingLayer.ts
+import { useEffect as useEffect2, useLayoutEffect as useLayoutEffect2, useMemo as useMemo2, useState as useState2 } from "react";
+var useIsomorphicLayoutEffect2 = typeof window === "undefined" ? useEffect2 : useLayoutEffect2;
+function readFocusVisible(node) {
+  if (typeof node.matches === "function") {
+    try {
+      return node.matches(":focus-visible");
+    } catch {
+      return document.activeElement === node;
+    }
+  }
+  return document.activeElement === node;
+}
+function useFocusRingLayer(options = {}) {
+  const { color, inset, offset, ref, visible, width } = options;
+  const [focusVisible, setFocusVisible] = useState2(Boolean(visible));
+  const [node, mergedRef] = useMergedNodeRef(ref);
+  useIsomorphicLayoutEffect2(() => {
+    if (visible != null) {
+      setFocusVisible(visible);
+      return;
+    }
+    if (!node) {
+      return;
+    }
+    setFocusVisible(readFocusVisible(node));
+  }, [node, visible]);
+  useEffect2(() => {
+    if (!node || visible != null) {
+      return;
+    }
+    const onFocus = () => {
+      setFocusVisible(readFocusVisible(node));
+    };
+    const onBlur = () => setFocusVisible(false);
+    node.addEventListener("focus", onFocus);
+    node.addEventListener("blur", onBlur);
+    return () => {
+      node.removeEventListener("focus", onFocus);
+      node.removeEventListener("blur", onBlur);
+    };
+  }, [node, visible]);
+  const layerRef = useStateLayer({
+    active: focusVisible,
+    className: "psl-focus-ring",
+    variables: {
+      "--psl-focus-ring-color": color,
+      "--psl-focus-ring-inset": inset,
+      "--psl-focus-ring-offset": offset,
+      "--psl-focus-ring-width": width
+    }
+  });
+  return useMemo2(() => {
+    return (nextNode) => {
+      mergedRef(nextNode);
+      layerRef(nextNode);
+    };
+  }, [layerRef, mergedRef]);
+}
+
+// src/hooks/useInvalidStateLayer.ts
+import { useMemo as useMemo3 } from "react";
+function useInvalidStateLayer(options = {}) {
+  const { active = false, color, inset, opacity, ref, width } = options;
+  const layerRef = useStateLayer({
+    active,
+    className: "psl-invalid",
+    variables: {
+      "--psl-invalid-color": color,
+      "--psl-invalid-inset": inset,
+      "--psl-invalid-opacity": opacity == null ? void 0 : String(opacity),
+      "--psl-invalid-width": width
+    }
+  });
+  return useMemo3(() => mergeRefs(layerRef, ref), [layerRef, ref]);
+}
+
+// src/hooks/useLoadingSheenLayer.ts
+import { useMemo as useMemo4 } from "react";
+function useLoadingSheenLayer(options = {}) {
+  const { active = false, angle, duration, intensity, ref, sheenColor } = options;
+  const layerRef = useStateLayer({
+    active,
+    className: "psl-loading",
+    variables: {
+      "--psl-loading-angle": angle,
+      "--psl-loading-duration": duration,
+      "--psl-loading-intensity": intensity == null ? void 0 : String(intensity),
+      "--psl-loading-sheen-color": sheenColor
+    }
+  });
+  return useMemo4(() => mergeRefs(layerRef, ref), [layerRef, ref]);
+}
+export {
+  mergeRefs,
+  useFocusRingLayer,
+  useInvalidStateLayer,
+  useLoadingSheenLayer
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@protohiro/state-layers",
+  "version": "0.1.1",
+  "description": "React hooks for visual state layers on existing elements.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/protohiro-com/state-layers.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/protohiro-com/state-layers#readme",
+  "bugs": {
+    "url": "https://github.com/protohiro-com/state-layers/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "pack:check": "npm pack --dry-run",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}