@cjaye/react-meta-state 0.1.0

package/dist/addon/index.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+const csf = require('storybook/internal/csf');
+const addon_preview = require('./preview.cjs');
+require('react/jsx-runtime');
+require('react');
+require('../shared/react-meta-state.C5ASg9b-.cjs');
+require('../shared/react-meta-state.BXhLgGzA.cjs');
+
+const index = () => csf.definePreviewAddon(addon_preview);
+
+module.exports = index;

package/dist/addon/index.d.mts

@@ -0,0 +1,5 @@
+import * as storybook_internal_csf from 'storybook/internal/csf';
+
+declare const _default: () => storybook_internal_csf.PreviewAddon<storybook_internal_csf.AddonTypes>;
+
+export { _default as default };

package/dist/addon/index.mjs

@@ -0,0 +1,10 @@
+import { definePreviewAddon } from 'storybook/internal/csf';
+import preview from './preview.mjs';
+import 'react/jsx-runtime';
+import 'react';
+import '../shared/react-meta-state.C3o6Eh_L.mjs';
+import '../shared/react-meta-state.BjE3OmFW.mjs';
+
+const index = () => definePreviewAddon(preview);
+
+export { index as default };

package/dist/addon/manager.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+const jsxRuntime = require('react/jsx-runtime');
+const state = require('../shared/react-meta-state.C5ASg9b-.cjs');
+const managerApi = require('storybook/manager-api');
+const helpers = require('../shared/react-meta-state.C6XVhRdK.cjs');
+const react = require('react');
+const icons = require('@storybook/icons');
+const components = require('storybook/internal/components');
+
+const MetaStateTool = react.memo(({ api }) => {
+  const [globals, updateGlobals] = managerApi.useGlobals();
+  const data = react.useMemo(() => globals[state.TOOL_ID] ?? {}, [globals]);
+  const options = react.useMemo(() => helpers.keysOf(state.DEFAULT_COMPONENT_STATE).map((k) => ({ title: k, value: k })), []);
+  const updateState = react.useCallback((state$1 = {}) => {
+    updateGlobals({ [state.TOOL_ID]: state$1 });
+  }, [updateGlobals]);
+  react.useEffect(() => {
+    void api.setAddonShortcut(state.ADDON_ID, {
+      label: "Meta States",
+      defaultShortcut: ["alt", "M"],
+      actionName: "outline",
+      showInMenu: true,
+      action: () => updateState({})
+    });
+  }, [api, updateState]);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    components.Select,
+    {
+      resetLabel: "Reset meta states",
+      onReset: updateState,
+      icon: /* @__PURE__ */ jsxRuntime.jsx(icons.ButtonIcon, {}),
+      ariaLabel: "Meta States",
+      tooltip: "Apply meta states",
+      options,
+      value: helpers.keysOf(data).filter((x) => !!data[x]),
+      multiSelect: true,
+      onChange: (selected) => {
+        updateState(helpers.entriesOf(state.DEFAULT_COMPONENT_STATE).reduce((v, [k]) => ({ ...v, [k]: selected.includes(k) }), {}));
+      }
+    },
+    state.TOOL_ID
+  );
+});
+
+function renderLabel(item) {
+  if (item.type !== "story" && item.type !== "docs") {
+    return;
+  }
+  if (item.title.startsWith(state.ADDON_ID)) {
+    return /* @__PURE__ */ jsxRuntime.jsxs("span", { children: [
+      "\u{1F31F}",
+      item.name
+    ] });
+  }
+}
+
+managerApi.addons.register(state.ADDON_ID, (api) => {
+  managerApi.addons.add(state.TOOL_ID, {
+    type: managerApi.types.TOOL,
+    title: "React Meta State",
+    match: ({ viewMode }) => viewMode === "story",
+    render: () => /* @__PURE__ */ jsxRuntime.jsx(MetaStateTool, { api })
+  });
+  managerApi.addons.setConfig({
+    sidebar: { renderLabel }
+  });
+});

package/dist/addon/manager.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/addon/manager.mjs

@@ -0,0 +1,66 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { T as TOOL_ID, A as ADDON_ID, D as DEFAULT_COMPONENT_STATE } from '../shared/react-meta-state.C3o6Eh_L.mjs';
+import { useGlobals, addons, types } from 'storybook/manager-api';
+import { k as keysOf, e as entriesOf } from '../shared/react-meta-state.CzzhN3TK.mjs';
+import { memo, useMemo, useCallback, useEffect } from 'react';
+import { ButtonIcon } from '@storybook/icons';
+import { Select } from 'storybook/internal/components';
+
+const MetaStateTool = memo(({ api }) => {
+  const [globals, updateGlobals] = useGlobals();
+  const data = useMemo(() => globals[TOOL_ID] ?? {}, [globals]);
+  const options = useMemo(() => keysOf(DEFAULT_COMPONENT_STATE).map((k) => ({ title: k, value: k })), []);
+  const updateState = useCallback((state = {}) => {
+    updateGlobals({ [TOOL_ID]: state });
+  }, [updateGlobals]);
+  useEffect(() => {
+    void api.setAddonShortcut(ADDON_ID, {
+      label: "Meta States",
+      defaultShortcut: ["alt", "M"],
+      actionName: "outline",
+      showInMenu: true,
+      action: () => updateState({})
+    });
+  }, [api, updateState]);
+  return /* @__PURE__ */ jsx(
+    Select,
+    {
+      resetLabel: "Reset meta states",
+      onReset: updateState,
+      icon: /* @__PURE__ */ jsx(ButtonIcon, {}),
+      ariaLabel: "Meta States",
+      tooltip: "Apply meta states",
+      options,
+      value: keysOf(data).filter((x) => !!data[x]),
+      multiSelect: true,
+      onChange: (selected) => {
+        updateState(entriesOf(DEFAULT_COMPONENT_STATE).reduce((v, [k]) => ({ ...v, [k]: selected.includes(k) }), {}));
+      }
+    },
+    TOOL_ID
+  );
+});
+
+function renderLabel(item) {
+  if (item.type !== "story" && item.type !== "docs") {
+    return;
+  }
+  if (item.title.startsWith(ADDON_ID)) {
+    return /* @__PURE__ */ jsxs("span", { children: [
+      "\u{1F31F}",
+      item.name
+    ] });
+  }
+}
+
+addons.register(ADDON_ID, (api) => {
+  addons.add(TOOL_ID, {
+    type: types.TOOL,
+    title: "React Meta State",
+    match: ({ viewMode }) => viewMode === "story",
+    render: () => /* @__PURE__ */ jsx(MetaStateTool, { api })
+  });
+  addons.setConfig({
+    sidebar: { renderLabel }
+  });
+});

package/dist/addon/preview.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+const jsxRuntime = require('react/jsx-runtime');
+const react = require('react');
+const state = require('../shared/react-meta-state.C5ASg9b-.cjs');
+const parse = require('../shared/react-meta-state.BXhLgGzA.cjs');
+
+const preview = {
+  decorators: [
+    (Story, { globals, canvasElement }) => {
+      const canvas = canvasElement;
+      const data = react.useMemo(() => globals[state.TOOL_ID] ?? {}, [globals]);
+      react.useEffect(() => {
+        canvas.querySelectorAll("[data-rms]").forEach((el) => {
+          el.setAttribute("data-rms", parse.toJson(data));
+        });
+      }, [data, canvas]);
+      return /* @__PURE__ */ jsxRuntime.jsx(Story, {});
+    }
+  ],
+  initialGlobals: {
+    [state.TOOL_ID]: {}
+  }
+};
+
+module.exports = preview;

package/dist/addon/preview.d.mts

@@ -0,0 +1,5 @@
+import { ProjectAnnotations, Renderer } from 'storybook/internal/types';
+
+declare const preview: ProjectAnnotations<Renderer>;
+
+export { preview as default };

package/dist/addon/preview.mjs

@@ -0,0 +1,24 @@
+import { jsx } from 'react/jsx-runtime';
+import { useMemo, useEffect } from 'react';
+import { T as TOOL_ID } from '../shared/react-meta-state.C3o6Eh_L.mjs';
+import { t as toJson } from '../shared/react-meta-state.BjE3OmFW.mjs';
+
+const preview = {
+  decorators: [
+    (Story, { globals, canvasElement }) => {
+      const canvas = canvasElement;
+      const data = useMemo(() => globals[TOOL_ID] ?? {}, [globals]);
+      useEffect(() => {
+        canvas.querySelectorAll("[data-rms]").forEach((el) => {
+          el.setAttribute("data-rms", toJson(data));
+        });
+      }, [data, canvas]);
+      return /* @__PURE__ */ jsx(Story, {});
+    }
+  ],
+  initialGlobals: {
+    [TOOL_ID]: {}
+  }
+};
+
+export { preview as default };

package/dist/index.cjs

@@ -0,0 +1,298 @@
+'use strict';
+
+const helpers = require('./shared/react-meta-state.C6XVhRdK.cjs');
+const react = require('react');
+const state = require('./shared/react-meta-state.C5ASg9b-.cjs');
+const parse = require('./shared/react-meta-state.BXhLgGzA.cjs');
+
+function mergeArr(target, source) {
+  const merged = [...target];
+  for (const item of source) {
+    if (!merged.includes(item)) {
+      merged.push(item);
+    }
+  }
+  return merged;
+}
+function deepMerge(target, source) {
+  if (!helpers.isObj(target)) {
+    return source;
+  }
+  if (!helpers.isObj(source)) {
+    return target;
+  }
+  const obj = { ...target };
+  for (const key in source) {
+    const t = target[key];
+    const s = source[key];
+    if (!(key in target) || target[key] === void 0) {
+      obj[key] = s;
+      continue;
+    }
+    if (helpers.isArr(s)) {
+      obj[key] = helpers.isArr(t) ? mergeArr(t, s) : s;
+      continue;
+    }
+    if (helpers.isObj(s)) {
+      obj[key] = helpers.isObj(t) ? deepMerge(t, s) : s;
+      continue;
+    }
+    obj[key] = s ?? t;
+  }
+  return obj;
+}
+function deepMergeAll(...objects) {
+  return objects.reduce((v, x) => deepMerge(v, x), {});
+}
+
+async function wait(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function useComponentState(options) {
+  const {
+    ref: parentRef,
+    stateDefinition = state.DEFAULT_COMPONENT_STATE,
+    onStateChange,
+    stateOverride
+  } = options ?? {};
+  const refs = react.useRef({});
+  const states = react.useRef({});
+  const listeners = react.useRef({});
+  const observers = react.useRef({});
+  const refreshTimes = react.useRef({});
+  const queuedState = react.useRef({});
+  const overrides = react.useRef({});
+  const [finalState, setFinalState] = react.useState({});
+  const getAttributeState = react.useCallback((key) => {
+    const attributeState = refs.current[key]?.getAttribute("data-rms");
+    return attributeState === "" ? {} : parse.fromJson(attributeState ?? "{}");
+  }, []);
+  const normaliseState = react.useCallback((state) => {
+    if (state.focus) {
+      state.focusWithin = true;
+    }
+    if (state.disabled) {
+      state.focus = state.focusWithin = state.active = state.selected = false;
+    }
+    return state;
+  }, []);
+  const refresh = react.useCallback(async (key = "default") => {
+    normaliseState(queuedState.current[key]);
+    const attributeState = getAttributeState(key);
+    const allStates = normaliseState(deepMergeAll(
+      states.current[key],
+      queuedState.current[key] ?? {},
+      overrides.current?.[key] ?? {},
+      attributeState
+    ));
+    if (helpers.keysOf(allStates).every((k) => allStates[k] === states.current[key]?.[k])) {
+      queuedState.current[key] = {};
+      return;
+    }
+    const rt = refreshTimes.current[key] ?? 0;
+    if (!!rt) return;
+    const rt2 = refreshTimes.current[key] = Date.now();
+    const delay = Math.max(rt2 + 8 - Date.now(), 0);
+    if (!!delay) {
+      void await wait(delay);
+    }
+    refreshTimes.current[key] = 0;
+    const el = refs.current[key];
+    const innerState = deepMerge(
+      states.current[key],
+      queuedState.current[key] ?? {}
+    );
+    const newState = normaliseState(deepMergeAll(
+      innerState,
+      overrides.current?.[key] ?? {},
+      attributeState
+    ));
+    const prevState = states.current[key];
+    queuedState.current[key] = {};
+    if (helpers.keysOf(newState).every((k) => newState[k] === states.current[key]?.[k])) return;
+    states.current[key] = innerState;
+    setFinalState((s) => ({ ...s, [key]: newState }));
+    helpers.keysOf(stateDefinition).forEach((k) => el.classList[newState[k] ? "add" : "remove"](k));
+    onStateChange?.(newState, key);
+    if (helpers.isIn(el, "disabled") && el.disabled !== newState.disabled) {
+      el.disabled = !!newState.disabled;
+    }
+    if (newState.focus && el !== document.activeElement && !prevState.focus) {
+      el.focus();
+    }
+    if (!newState.focus && el === document.activeElement && prevState.focus) {
+      el.blur();
+    }
+  }, [getAttributeState, normaliseState, onStateChange, stateDefinition]);
+  const updateState = react.useCallback((patch, key = "default") => {
+    queuedState.current[key] = deepMerge(queuedState.current[key] ?? {}, patch);
+    void refresh(key);
+  }, [refresh]);
+  const getRef = react.useCallback((node, key = "default") => {
+    const ref = refs.current[key];
+    const observer = observers.current[key];
+    if (helpers.isFunc(parentRef)) {
+      parentRef?.(node);
+    } else if (helpers.isIn(parentRef, "current")) {
+      parentRef.current = node;
+    }
+    if (ref && node && ref !== node) {
+      const l2 = listeners.current[key];
+      observer.disconnect();
+      document.removeEventListener("pointerup", l2.pointerup);
+      node.removeEventListener("pointerdown", l2.pointerdown);
+      node.removeEventListener("pointerleave", l2.pointerleave);
+      node.removeEventListener("pointerenter", l2.pointerenter);
+      node.removeEventListener("focus", l2.focus);
+      node.removeEventListener("focusin", l2.focusin);
+      node.removeEventListener("focusout", l2.focusout);
+      delete listeners.current[key];
+      delete refs.current[key];
+      delete states.current[key];
+      delete observers.current[key];
+    }
+    if (!node || ref === node) return;
+    refs.current[key] = node;
+    listeners.current[key] = {
+      pointerup: () => {
+        if (!helpers.isIn(stateDefinition, "pressed")) return;
+        updateState({ pressed: false }, key);
+      },
+      pointerdown: () => {
+        if (!helpers.isIn(stateDefinition, "pressed")) return;
+        updateState({ pressed: true }, key);
+      },
+      pointerleave: () => {
+        if (!helpers.isIn(stateDefinition, "hover")) return;
+        updateState({ hover: false }, key);
+      },
+      pointerenter: () => {
+        if (!helpers.isIn(stateDefinition, "hover")) return;
+        updateState({ hover: true }, key);
+      },
+      focus: () => {
+        if (!helpers.isIn(stateDefinition, "focus")) return;
+        updateState({ focus: true }, key);
+      },
+      focusin: () => {
+        if (!helpers.isIn(stateDefinition, "focusWithin")) return;
+        updateState({ focusWithin: true }, key);
+      },
+      focusout: () => {
+        const active = document.activeElement;
+        let shouldFocusWithinOut = false;
+        if (helpers.isIn(stateDefinition, "focusWithin")) {
+          if (!refs.current[key]?.contains(active) && refs.current[key] !== active && refs.current[key] !== active) {
+            shouldFocusWithinOut = true;
+          }
+        }
+        if (helpers.isIn(stateDefinition, "focus")) {
+          updateState({ focus: false, focusWithin: shouldFocusWithinOut ? false : void 0 }, key);
+        }
+      }
+    };
+    const l = listeners.current[key];
+    const obs = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (mutation.type === "attributes" && mutation.attributeName === "data-rms") {
+          return updateState({}, key);
+        }
+        if (mutation.type === "attributes" && mutation.attributeName === "class") {
+          const target = mutation.target;
+          const oldClasses = mutation.oldValue?.split(" ") ?? [];
+          const newClasses = target.classList.value.split(" ");
+          const added = newClasses.filter((x) => !oldClasses.includes(x) && helpers.isIn(stateDefinition, x) && !states.current[key]?.[x]);
+          const removed = oldClasses.filter((x) => !newClasses.includes(x) && helpers.isIn(stateDefinition, x) && !!states.current[key]?.[x]);
+          updateState({
+            ...added.reduce((a, v) => ({ ...a, [v]: true }), {}),
+            ...removed.reduce((a, v) => ({ ...a, [v]: false }), {})
+          }, key);
+          return;
+        }
+        const el = mutation.target;
+        if (!helpers.isIn(el, "disabled") || mutation.type !== "attributes" || mutation.attributeName !== "disabled" || el.disabled === states.current[key]?.disabled || !helpers.isIn(stateDefinition, "disabled")) {
+          return;
+        }
+        const attributeState = getAttributeState(key);
+        if (el.disabled) {
+          if (attributeState.disabled === false || overrides.current?.[key]?.disabled === false) {
+            el.disabled = false;
+            return;
+          }
+          updateState({ disabled: true }, key);
+        } else {
+          if (attributeState.disabled === true || overrides.current?.[key]?.disabled === true) {
+            el.disabled = true;
+            return;
+          }
+          updateState({ disabled: false }, key);
+        }
+      }
+    });
+    document.addEventListener("pointerup", l.pointerup);
+    node.addEventListener("pointerdown", l.pointerdown);
+    node.addEventListener("pointerleave", l.pointerleave);
+    node.addEventListener("pointerenter", l.pointerenter);
+    node.addEventListener("focus", l.focus);
+    node.addEventListener("focusin", l.focusin);
+    node.addEventListener("focusout", l.focusout);
+    node.setAttribute("data-rms", "");
+    obs.observe(node, {
+      attributes: true,
+      attributeOldValue: true,
+      attributeFilter: ["disabled", "class", "data-rms"]
+    });
+    const s = {};
+    if (helpers.isIn(stateDefinition, "focus")) {
+      s.focus = node === document.activeElement;
+    }
+    if (helpers.isIn(stateDefinition, "focusWithin")) {
+      s.focusWithin = node === document.activeElement || node.contains(document.activeElement);
+    }
+    if (helpers.isIn(stateDefinition, "disabled")) {
+      s.disabled = helpers.isIn(node, "disabled") && !!node.disabled;
+    }
+    observers.current[key] = obs;
+    states.current[key] ??= {};
+    queuedState.current[key] = deepMergeAll(
+      stateDefinition ?? {},
+      queuedState.current[key] ?? {},
+      s ?? {}
+    );
+    void refresh(key);
+  }, [parentRef, stateDefinition, refresh, updateState, getAttributeState]);
+  react.useEffect(() => {
+    const o = overrides.current;
+    const changedKeys = [];
+    helpers.entriesOf(stateOverride ?? {}).forEach(([k, v]) => {
+      helpers.entriesOf(v).forEach(([kk, vv]) => {
+        if (o?.[kk]?.[k] !== vv && !changedKeys.includes(kk)) {
+          changedKeys.push(kk);
+        }
+        o[kk] = o[kk] ?? {};
+        o[kk][k] = vv;
+      });
+    });
+    if (!changedKeys.length) return;
+    changedKeys.forEach((key) => {
+      const newState = deepMerge(
+        queuedState.current[key],
+        o?.[key] ?? {}
+      );
+      if (helpers.keysOf(newState).every((k) => newState[k] === states.current[key]?.[k])) {
+        return;
+      }
+      queuedState.current[key] = newState;
+      void refresh(key);
+    });
+  }, [stateOverride]);
+  return {
+    ref: getRef,
+    refs,
+    state: finalState,
+    updateState
+  };
+}
+
+exports.useComponentState = useComponentState;

package/dist/index.d.mts

@@ -0,0 +1,39 @@
+import * as react from 'react';
+import { ElementType, ComponentPropsWithRef, PropsWithChildren, Ref } from 'react';
+
+type Key = string | number | symbol;
+type Obj<T = unknown, K extends Key = string> = Record<K, T>;
+
+type ComponentState<T extends Obj<boolean | undefined> = Obj<boolean | undefined>> = Obj<boolean | undefined> & {
+    selected?: boolean | undefined;
+    hover?: boolean | undefined;
+    focusWithin?: boolean | undefined;
+    focus?: boolean | undefined;
+    pressed?: boolean | undefined;
+    active?: boolean | undefined;
+    highlighted?: boolean | undefined;
+    disabled?: boolean | undefined;
+} & {
+    [K in keyof T]?: boolean | undefined;
+};
+interface ComponentStateProps<S extends ComponentState = ComponentState, E extends Ref<HTMLElement | SVGElement> = Ref<HTMLElement | SVGElement>> {
+    stateDefinition?: ComponentState<S>;
+    stateOverride?: {
+        [K in keyof ComponentState<S>]: Obj<boolean | undefined>;
+    };
+    onStateChange?: (state: ComponentState<S>, key: string) => void;
+    ref?: E;
+}
+type BaseProps<T = {}, O extends keyof (T extends ElementType ? ComponentPropsWithRef<T> : PropsWithChildren<T>) = never, S extends ComponentState = never> = Omit<(T extends ElementType ? ComponentPropsWithRef<T> : PropsWithChildren<T>), O> & (S extends never ? {} : {
+    stateProps?: ComponentStateProps<S, T extends ElementType ? ComponentPropsWithRef<T>["ref"] : Ref<HTMLElement | SVGElement>>;
+});
+
+declare function useComponentState<S extends Obj<boolean | undefined> = ComponentState>(options?: ComponentStateProps<S>): {
+    ref: (node: HTMLElement | SVGElement | null, key?: string) => void;
+    refs: react.MutableRefObject<Obj<HTMLElement | SVGElement | null>>;
+    state: Obj<ComponentState<S>>;
+    updateState: <S_1 extends Obj<boolean | undefined> = Obj<boolean | undefined>>(patch: Partial<ComponentState<S_1>>, key?: string) => void;
+};
+
+export { useComponentState };
+export type { BaseProps, ComponentState, ComponentStateProps };

package/dist/index.mjs

@@ -0,0 +1,296 @@
+import { i as isObj, a as isArr, k as keysOf, b as isIn, c as isFunc, e as entriesOf } from './shared/react-meta-state.CzzhN3TK.mjs';
+import { useRef, useState, useCallback, useEffect } from 'react';
+import { D as DEFAULT_COMPONENT_STATE } from './shared/react-meta-state.C3o6Eh_L.mjs';
+import { f as fromJson } from './shared/react-meta-state.BjE3OmFW.mjs';
+
+function mergeArr(target, source) {
+  const merged = [...target];
+  for (const item of source) {
+    if (!merged.includes(item)) {
+      merged.push(item);
+    }
+  }
+  return merged;
+}
+function deepMerge(target, source) {
+  if (!isObj(target)) {
+    return source;
+  }
+  if (!isObj(source)) {
+    return target;
+  }
+  const obj = { ...target };
+  for (const key in source) {
+    const t = target[key];
+    const s = source[key];
+    if (!(key in target) || target[key] === void 0) {
+      obj[key] = s;
+      continue;
+    }
+    if (isArr(s)) {
+      obj[key] = isArr(t) ? mergeArr(t, s) : s;
+      continue;
+    }
+    if (isObj(s)) {
+      obj[key] = isObj(t) ? deepMerge(t, s) : s;
+      continue;
+    }
+    obj[key] = s ?? t;
+  }
+  return obj;
+}
+function deepMergeAll(...objects) {
+  return objects.reduce((v, x) => deepMerge(v, x), {});
+}
+
+async function wait(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function useComponentState(options) {
+  const {
+    ref: parentRef,
+    stateDefinition = DEFAULT_COMPONENT_STATE,
+    onStateChange,
+    stateOverride
+  } = options ?? {};
+  const refs = useRef({});
+  const states = useRef({});
+  const listeners = useRef({});
+  const observers = useRef({});
+  const refreshTimes = useRef({});
+  const queuedState = useRef({});
+  const overrides = useRef({});
+  const [finalState, setFinalState] = useState({});
+  const getAttributeState = useCallback((key) => {
+    const attributeState = refs.current[key]?.getAttribute("data-rms");
+    return attributeState === "" ? {} : fromJson(attributeState ?? "{}");
+  }, []);
+  const normaliseState = useCallback((state) => {
+    if (state.focus) {
+      state.focusWithin = true;
+    }
+    if (state.disabled) {
+      state.focus = state.focusWithin = state.active = state.selected = false;
+    }
+    return state;
+  }, []);
+  const refresh = useCallback(async (key = "default") => {
+    normaliseState(queuedState.current[key]);
+    const attributeState = getAttributeState(key);
+    const allStates = normaliseState(deepMergeAll(
+      states.current[key],
+      queuedState.current[key] ?? {},
+      overrides.current?.[key] ?? {},
+      attributeState
+    ));
+    if (keysOf(allStates).every((k) => allStates[k] === states.current[key]?.[k])) {
+      queuedState.current[key] = {};
+      return;
+    }
+    const rt = refreshTimes.current[key] ?? 0;
+    if (!!rt) return;
+    const rt2 = refreshTimes.current[key] = Date.now();
+    const delay = Math.max(rt2 + 8 - Date.now(), 0);
+    if (!!delay) {
+      void await wait(delay);
+    }
+    refreshTimes.current[key] = 0;
+    const el = refs.current[key];
+    const innerState = deepMerge(
+      states.current[key],
+      queuedState.current[key] ?? {}
+    );
+    const newState = normaliseState(deepMergeAll(
+      innerState,
+      overrides.current?.[key] ?? {},
+      attributeState
+    ));
+    const prevState = states.current[key];
+    queuedState.current[key] = {};
+    if (keysOf(newState).every((k) => newState[k] === states.current[key]?.[k])) return;
+    states.current[key] = innerState;
+    setFinalState((s) => ({ ...s, [key]: newState }));
+    keysOf(stateDefinition).forEach((k) => el.classList[newState[k] ? "add" : "remove"](k));
+    onStateChange?.(newState, key);
+    if (isIn(el, "disabled") && el.disabled !== newState.disabled) {
+      el.disabled = !!newState.disabled;
+    }
+    if (newState.focus && el !== document.activeElement && !prevState.focus) {
+      el.focus();
+    }
+    if (!newState.focus && el === document.activeElement && prevState.focus) {
+      el.blur();
+    }
+  }, [getAttributeState, normaliseState, onStateChange, stateDefinition]);
+  const updateState = useCallback((patch, key = "default") => {
+    queuedState.current[key] = deepMerge(queuedState.current[key] ?? {}, patch);
+    void refresh(key);
+  }, [refresh]);
+  const getRef = useCallback((node, key = "default") => {
+    const ref = refs.current[key];
+    const observer = observers.current[key];
+    if (isFunc(parentRef)) {
+      parentRef?.(node);
+    } else if (isIn(parentRef, "current")) {
+      parentRef.current = node;
+    }
+    if (ref && node && ref !== node) {
+      const l2 = listeners.current[key];
+      observer.disconnect();
+      document.removeEventListener("pointerup", l2.pointerup);
+      node.removeEventListener("pointerdown", l2.pointerdown);
+      node.removeEventListener("pointerleave", l2.pointerleave);
+      node.removeEventListener("pointerenter", l2.pointerenter);
+      node.removeEventListener("focus", l2.focus);
+      node.removeEventListener("focusin", l2.focusin);
+      node.removeEventListener("focusout", l2.focusout);
+      delete listeners.current[key];
+      delete refs.current[key];
+      delete states.current[key];
+      delete observers.current[key];
+    }
+    if (!node || ref === node) return;
+    refs.current[key] = node;
+    listeners.current[key] = {
+      pointerup: () => {
+        if (!isIn(stateDefinition, "pressed")) return;
+        updateState({ pressed: false }, key);
+      },
+      pointerdown: () => {
+        if (!isIn(stateDefinition, "pressed")) return;
+        updateState({ pressed: true }, key);
+      },
+      pointerleave: () => {
+        if (!isIn(stateDefinition, "hover")) return;
+        updateState({ hover: false }, key);
+      },
+      pointerenter: () => {
+        if (!isIn(stateDefinition, "hover")) return;
+        updateState({ hover: true }, key);
+      },
+      focus: () => {
+        if (!isIn(stateDefinition, "focus")) return;
+        updateState({ focus: true }, key);
+      },
+      focusin: () => {
+        if (!isIn(stateDefinition, "focusWithin")) return;
+        updateState({ focusWithin: true }, key);
+      },
+      focusout: () => {
+        const active = document.activeElement;
+        let shouldFocusWithinOut = false;
+        if (isIn(stateDefinition, "focusWithin")) {
+          if (!refs.current[key]?.contains(active) && refs.current[key] !== active && refs.current[key] !== active) {
+            shouldFocusWithinOut = true;
+          }
+        }
+        if (isIn(stateDefinition, "focus")) {
+          updateState({ focus: false, focusWithin: shouldFocusWithinOut ? false : void 0 }, key);
+        }
+      }
+    };
+    const l = listeners.current[key];
+    const obs = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (mutation.type === "attributes" && mutation.attributeName === "data-rms") {
+          return updateState({}, key);
+        }
+        if (mutation.type === "attributes" && mutation.attributeName === "class") {
+          const target = mutation.target;
+          const oldClasses = mutation.oldValue?.split(" ") ?? [];
+          const newClasses = target.classList.value.split(" ");
+          const added = newClasses.filter((x) => !oldClasses.includes(x) && isIn(stateDefinition, x) && !states.current[key]?.[x]);
+          const removed = oldClasses.filter((x) => !newClasses.includes(x) && isIn(stateDefinition, x) && !!states.current[key]?.[x]);
+          updateState({
+            ...added.reduce((a, v) => ({ ...a, [v]: true }), {}),
+            ...removed.reduce((a, v) => ({ ...a, [v]: false }), {})
+          }, key);
+          return;
+        }
+        const el = mutation.target;
+        if (!isIn(el, "disabled") || mutation.type !== "attributes" || mutation.attributeName !== "disabled" || el.disabled === states.current[key]?.disabled || !isIn(stateDefinition, "disabled")) {
+          return;
+        }
+        const attributeState = getAttributeState(key);
+        if (el.disabled) {
+          if (attributeState.disabled === false || overrides.current?.[key]?.disabled === false) {
+            el.disabled = false;
+            return;
+          }
+          updateState({ disabled: true }, key);
+        } else {
+          if (attributeState.disabled === true || overrides.current?.[key]?.disabled === true) {
+            el.disabled = true;
+            return;
+          }
+          updateState({ disabled: false }, key);
+        }
+      }
+    });
+    document.addEventListener("pointerup", l.pointerup);
+    node.addEventListener("pointerdown", l.pointerdown);
+    node.addEventListener("pointerleave", l.pointerleave);
+    node.addEventListener("pointerenter", l.pointerenter);
+    node.addEventListener("focus", l.focus);
+    node.addEventListener("focusin", l.focusin);
+    node.addEventListener("focusout", l.focusout);
+    node.setAttribute("data-rms", "");
+    obs.observe(node, {
+      attributes: true,
+      attributeOldValue: true,
+      attributeFilter: ["disabled", "class", "data-rms"]
+    });
+    const s = {};
+    if (isIn(stateDefinition, "focus")) {
+      s.focus = node === document.activeElement;
+    }
+    if (isIn(stateDefinition, "focusWithin")) {
+      s.focusWithin = node === document.activeElement || node.contains(document.activeElement);
+    }
+    if (isIn(stateDefinition, "disabled")) {
+      s.disabled = isIn(node, "disabled") && !!node.disabled;
+    }
+    observers.current[key] = obs;
+    states.current[key] ??= {};
+    queuedState.current[key] = deepMergeAll(
+      stateDefinition ?? {},
+      queuedState.current[key] ?? {},
+      s ?? {}
+    );
+    void refresh(key);
+  }, [parentRef, stateDefinition, refresh, updateState, getAttributeState]);
+  useEffect(() => {
+    const o = overrides.current;
+    const changedKeys = [];
+    entriesOf(stateOverride ?? {}).forEach(([k, v]) => {
+      entriesOf(v).forEach(([kk, vv]) => {
+        if (o?.[kk]?.[k] !== vv && !changedKeys.includes(kk)) {
+          changedKeys.push(kk);
+        }
+        o[kk] = o[kk] ?? {};
+        o[kk][k] = vv;
+      });
+    });
+    if (!changedKeys.length) return;
+    changedKeys.forEach((key) => {
+      const newState = deepMerge(
+        queuedState.current[key],
+        o?.[key] ?? {}
+      );
+      if (keysOf(newState).every((k) => newState[k] === states.current[key]?.[k])) {
+        return;
+      }
+      queuedState.current[key] = newState;
+      void refresh(key);
+    });
+  }, [stateOverride]);
+  return {
+    ref: getRef,
+    refs,
+    state: finalState,
+    updateState
+  };
+}
+
+export { useComponentState };

package/dist/package.json

@@ -0,0 +1,121 @@
+{
+    "name": "@cjaye/react-meta-state",
+    "version": "0.1.0",
+    "description": "",
+    "keywords": [],
+    "license": "MIT",
+    "author": "Charles Jaye",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/c-jaye/react-meta-state.git"
+    },
+    "private": false,
+    "type": "module",
+    "scripts": {
+        "clean": "del-cli --force \"**/package-lock.json\" \"**/storybook-static\" \"**/test-results.xml\" \"**/debug-storybook.log\" \"**/node_modules\" \"**/dist\" \"**/verdaccio/storage\" \"**/verdaccio/htpasswd\" \"**/verdaccio/config.yaml\"",
+        "postinstall": "pnpm run postinstall:playwright && pnpm run postinstall:verdaccio",
+        "postinstall:playwright": "pnpx playwright install --with-deps",
+        "postinstall:verdaccio": "chmod +x verdaccio/init verdaccio/login",
+        "build": "pnpm run test && pnpm run build:bundle",
+        "build:storybook": "storybook build",
+        "build:bundle": "unbuild",
+        "dev": "npm run build:bundle && concurrently \"pnpm run dev:storybook\" \"pnpm run dev:verdaccio\"",
+        "dev:storybook": "storybook dev -p 6006 -c ./playground/.storybook",
+        "dev:verdaccio": "verdaccio --listen 30333",
+        "lint": "tsc -b && pnpm run lint:check",
+        "lint:check": "pnpm eslint .",
+        "lint:fix": "pnpm eslint . --fix",
+        "test": "pnpm run lint && pnpm run test:unit",
+        "test:unit": "vitest --no-watch",
+        "prepublishOnly": "del-cli --force \"**/dist\" && pnpm run build",
+        "publish:verdaccio": "verdaccio/init || true && verdaccio/login && pnpm publish --access public --tag latest --no-git-checks --registry http://localhost:30333",
+        "publish:chromatic": "pnpx chromatic@latest --project-token",
+        "publish:npm": "pnpm publish --access public --tag latest --no-git-checks --registry registry.npmjs.org",
+        "publish:npm:login": "pnpm adduser --registry registry.npmjs.org --userconfig .npmrc"
+    },
+    "packageManager": "pnpm@10.31.0",
+    "engines": {
+        "node": ">=22.17.1"
+    },
+    "main": "./dist/index.mjs",
+    "types": "./dist/index.d.mts",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.mts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.cjs",
+            "default": "./dist/index.mjs"
+        },
+        "./addon": {
+            "types": "./dist/addon/index.d.mts",
+            "import": "./dist/addon/index.mjs",
+            "require": "./dist/addon/index.cjs",
+            "default": "./dist/addon/index.mjs"
+        },
+        "./addon/preview": {
+            "types": "./dist/addon/preview.d.mts",
+            "import": "./dist/addon/preview.mjs",
+            "require": "./dist/addon/preview.cjs",
+            "default": "./dist/addon/preview.mjs"
+        },
+        "./addon/manager": {
+            "types": "./dist/addon/manager.d.mts",
+            "import": "./dist/addon/manager.mjs",
+            "require": "./dist/addon/manager.cjs",
+            "default": "./dist/addon/manager.mjs"
+        },
+        "./package.json": "./package.json"
+    },
+    "os": [
+        "darwin",
+        "linux",
+        "win32"
+    ],
+    "dependencies": {
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1"
+    },
+    "peerDependencies": {
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1",
+        "storybook": "^10.3.3"
+    },
+    "devDependencies": {
+        "@chromatic-com/storybook": "^5.0.1",
+        "@storybook/addon-a11y": "^10.2.16",
+        "@storybook/addon-designs": "^11.1.2",
+        "@storybook/addon-vitest": "^10.2.16",
+        "@storybook/react-vite": "^10.2.16",
+        "@stylistic/eslint-plugin": "^5.10.0",
+        "@types/react": "^18.3.28",
+        "@types/react-dom": "^18.3.7",
+        "@vitejs/plugin-react-swc": "^4.3.0",
+        "@vitest/browser": "^4.0.18",
+        "@vitest/browser-playwright": "^4.0.18",
+        "@vitest/coverage-v8": "^4.0.18",
+        "classnames": "^2.5.1",
+        "concurrently": "^9.2.1",
+        "del-cli": "^7.0.0",
+        "eslint": "^9.39.4",
+        "eslint-import-resolver-typescript": "^4.4.4",
+        "eslint-plugin-import-x": "^4.16.1",
+        "eslint-plugin-react-hooks": "^7.0.1",
+        "eslint-plugin-storybook": "10.3.3",
+        "globals": "^17.4.0",
+        "jiti": "^2.6.1",
+        "playwright": "^1.58.2",
+        "sass-embedded": "^1.97.3",
+        "storybook": "^10.2.16",
+        "storybook-addon-pseudo-states": "^10.2.16",
+        "tinyglobby": "^0.2.15",
+        "typescript": "~5.9.3",
+        "typescript-eslint": "^8.56.1",
+        "unbuild": "^3.6.1",
+        "verdaccio": "^6.3.1",
+        "vite-tsconfig-paths": "^6.1.1",
+        "vitest": "^4.0.18"
+    }
+}

package/dist/shared/react-meta-state.BXhLgGzA.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+function fromJson(json) {
+  return JSON.parse(json);
+}
+function toJson(json) {
+  return JSON.stringify(json);
+}
+
+exports.fromJson = fromJson;
+exports.toJson = toJson;

package/dist/shared/react-meta-state.BjE3OmFW.mjs

@@ -0,0 +1,8 @@
+function fromJson(json) {
+  return JSON.parse(json);
+}
+function toJson(json) {
+  return JSON.stringify(json);
+}
+
+export { fromJson as f, toJson as t };

package/dist/shared/react-meta-state.C3o6Eh_L.mjs

@@ -0,0 +1,14 @@
+const ADDON_ID = "react-meta-state";
+const TOOL_ID = `${ADDON_ID}/tool`;
+const DEFAULT_COMPONENT_STATE = {
+  selected: false,
+  hover: false,
+  focusWithin: false,
+  focus: false,
+  pressed: false,
+  active: false,
+  highlighted: false,
+  disabled: false
+};
+
+export { ADDON_ID as A, DEFAULT_COMPONENT_STATE as D, TOOL_ID as T };

package/dist/shared/react-meta-state.C5ASg9b-.cjs

@@ -0,0 +1,18 @@
+'use strict';
+
+const ADDON_ID = "react-meta-state";
+const TOOL_ID = `${ADDON_ID}/tool`;
+const DEFAULT_COMPONENT_STATE = {
+  selected: false,
+  hover: false,
+  focusWithin: false,
+  focus: false,
+  pressed: false,
+  active: false,
+  highlighted: false,
+  disabled: false
+};
+
+exports.ADDON_ID = ADDON_ID;
+exports.DEFAULT_COMPONENT_STATE = DEFAULT_COMPONENT_STATE;
+exports.TOOL_ID = TOOL_ID;

package/dist/shared/react-meta-state.C6XVhRdK.cjs

@@ -0,0 +1,27 @@
+'use strict';
+
+function keysOf(obj) {
+  return Object.keys(obj);
+}
+function entriesOf(obj) {
+  return Object.entries(obj);
+}
+function isIn(obj, key) {
+  return !!obj && key in obj && obj[key] !== void 0;
+}
+function isArr(value) {
+  return Array.isArray(value);
+}
+function isObj(value) {
+  return !!value && !isArr(value) && typeof value === "object";
+}
+function isFunc(value) {
+  return typeof value === "function";
+}
+
+exports.entriesOf = entriesOf;
+exports.isArr = isArr;
+exports.isFunc = isFunc;
+exports.isIn = isIn;
+exports.isObj = isObj;
+exports.keysOf = keysOf;

package/dist/shared/react-meta-state.CzzhN3TK.mjs

@@ -0,0 +1,20 @@
+function keysOf(obj) {
+  return Object.keys(obj);
+}
+function entriesOf(obj) {
+  return Object.entries(obj);
+}
+function isIn(obj, key) {
+  return !!obj && key in obj && obj[key] !== void 0;
+}
+function isArr(value) {
+  return Array.isArray(value);
+}
+function isObj(value) {
+  return !!value && !isArr(value) && typeof value === "object";
+}
+function isFunc(value) {
+  return typeof value === "function";
+}
+
+export { isArr as a, isIn as b, isFunc as c, entriesOf as e, isObj as i, keysOf as k };

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@cjaye/react-meta-state",
+  "version": "0.1.0",
+  "description": "",
+  "keywords": [],
+  "license": "MIT",
+  "author": "Charles Jaye",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/c-jaye/react-meta-state.git"
+  },
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=22.17.1"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    },
+    "./addon": {
+      "types": "./dist/addon/index.d.mts",
+      "import": "./dist/addon/index.mjs",
+      "require": "./dist/addon/index.cjs",
+      "default": "./dist/addon/index.mjs"
+    },
+    "./addon/preview": {
+      "types": "./dist/addon/preview.d.mts",
+      "import": "./dist/addon/preview.mjs",
+      "require": "./dist/addon/preview.cjs",
+      "default": "./dist/addon/preview.mjs"
+    },
+    "./addon/manager": {
+      "types": "./dist/addon/manager.d.mts",
+      "import": "./dist/addon/manager.mjs",
+      "require": "./dist/addon/manager.cjs",
+      "default": "./dist/addon/manager.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "storybook": "^10.3.3"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^5.0.1",
+    "@storybook/addon-a11y": "^10.2.16",
+    "@storybook/addon-designs": "^11.1.2",
+    "@storybook/addon-vitest": "^10.2.16",
+    "@storybook/react-vite": "^10.2.16",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react-swc": "^4.3.0",
+    "@vitest/browser": "^4.0.18",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
+    "classnames": "^2.5.1",
+    "concurrently": "^9.2.1",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.16.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-storybook": "10.3.3",
+    "globals": "^17.4.0",
+    "jiti": "^2.6.1",
+    "playwright": "^1.58.2",
+    "sass-embedded": "^1.97.3",
+    "storybook": "^10.2.16",
+    "storybook-addon-pseudo-states": "^10.2.16",
+    "tinyglobby": "^0.2.15",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "unbuild": "^3.6.1",
+    "verdaccio": "^6.3.1",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "clean": "del-cli --force \"**/package-lock.json\" \"**/storybook-static\" \"**/test-results.xml\" \"**/debug-storybook.log\" \"**/node_modules\" \"**/dist\" \"**/verdaccio/storage\" \"**/verdaccio/htpasswd\" \"**/verdaccio/config.yaml\"",
+    "postinstall": "pnpm run postinstall:playwright && pnpm run postinstall:verdaccio",
+    "postinstall:playwright": "pnpx playwright install --with-deps",
+    "postinstall:verdaccio": "chmod +x verdaccio/init verdaccio/login",
+    "build": "pnpm run test && pnpm run build:bundle",
+    "build:storybook": "storybook build",
+    "build:bundle": "unbuild",
+    "dev": "npm run build:bundle && concurrently \"pnpm run dev:storybook\" \"pnpm run dev:verdaccio\"",
+    "dev:storybook": "storybook dev -p 6006 -c ./playground/.storybook",
+    "dev:verdaccio": "verdaccio --listen 30333",
+    "lint": "tsc -b && pnpm run lint:check",
+    "lint:check": "pnpm eslint .",
+    "lint:fix": "pnpm eslint . --fix",
+    "test": "pnpm run lint && pnpm run test:unit",
+    "test:unit": "vitest --no-watch",
+    "publish:verdaccio": "verdaccio/init || true && verdaccio/login && pnpm publish --access public --tag latest --no-git-checks --registry http://localhost:30333",
+    "publish:chromatic": "pnpx chromatic@latest --project-token",
+    "publish:npm": "pnpm publish --access public --tag latest --no-git-checks --registry registry.npmjs.org",
+    "publish:npm:login": "pnpm adduser --registry registry.npmjs.org --userconfig .npmrc"
+  }
+}