@spaced-out/ui-design-system 0.6.36 → 0.6.37

package/lib/hooks/useInteractionModality/useInteractionModality.js

@@ -0,0 +1,111 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useInteractionModality = exports.startInteractionModalityTracking = exports.getInteractionModality = void 0;
+var _react = require("react");
+/*
+ * Input modality is a property of the SESSION, not of any one component, so it
+ * lives in module scope rather than in state that each consumer would have to
+ * thread around. This is the same shape the platform itself uses: `:focus-visible`
+ * is implemented by the engine tracking the last interaction globally.
+ *
+ * Reach for this only when CSS cannot answer the question — `:focus-visible` is
+ * the right tool whenever the element you need to style is the one that was
+ * interacted with. This exists for the case where it is NOT: a popup deciding
+ * whether to show a keyboard cursor has to know how its TRIGGER was operated,
+ * and the trigger's own `:focus-visible` cannot be trusted for that, because
+ * browsers always match it on text inputs (typing is expected there) — so an
+ * input-triggered popup would always look keyboard-opened.
+ */
+let currentModality = 'pointer';
+let listening = false;
+const subscribers = new Set();
+
+// Keys that navigate even when chorded with a modifier — Cmd+Down is "jump to
+// the end" on macOS and the menus honour it as such.
+const NAVIGATION_KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown', 'Tab', 'Enter', ' ']);
+const MODIFIER_KEYS = new Set(['Shift', 'Meta', 'Alt', 'Control']);
+const set = modality => {
+  if (currentModality === modality) {
+    return;
+  }
+  currentModality = modality;
+  subscribers.forEach(notify => notify(modality));
+};
+const handleKeyDown = event => {
+  // A modifier pressed on its own — Shift held for a click, say — is not an
+  // interaction, and a chorded shortcut (Cmd+C, Ctrl+S) is a command rather than
+  // navigation. Neither should make the session look keyboard-driven. A chorded
+  // NAVIGATION key (Cmd+Down) does count: it moves the highlight.
+  if (MODIFIER_KEYS.has(event.key)) {
+    return;
+  }
+  if ((event.metaKey || event.altKey || event.ctrlKey) && !NAVIGATION_KEYS.has(event.key)) {
+    return;
+  }
+  set('keyboard');
+};
+const handlePointerDown = () => set('pointer');
+
+/**
+ * Begin tracking. Idempotent, and session-scoped by design: the listeners live
+ * for the life of the page, so there is nothing to tear down.
+ *
+ * Tracking has to start BEFORE the thing that wants the answer exists. The
+ * interesting question is "how was the popup that just mounted opened?", and the
+ * keypress that opened it happened while the popup did not yet exist — so a
+ * component reading this on mount is always too late to have attached the
+ * listener itself. Whatever renders earlier and knows a popup may follow — a
+ * menu trigger — primes it.
+ *
+ * It is not primed on import. Attaching document listeners is a side effect, and
+ * a consumer that has not opted into any of this should get none: an app merely
+ * importing a component from this package must not start listening to its
+ * keyboard. Capture phase, so the modality is recorded before any component
+ * handler reacts to the same event.
+ */
+const startInteractionModalityTracking = () => {
+  if (typeof document === 'undefined' || listening) {
+    return;
+  }
+  listening = true;
+  document.addEventListener('keydown', handleKeyDown, true);
+  document.addEventListener('pointerdown', handlePointerDown, true);
+};
+exports.startInteractionModalityTracking = startInteractionModalityTracking;
+const subscribe = notify => {
+  startInteractionModalityTracking();
+  subscribers.add(notify);
+  return () => {
+    subscribers.delete(notify);
+  };
+};
+
+/**
+ * How the user last interacted with the page, read imperatively.
+ *
+ * Use this when the answer is needed during render or in an effect rather than
+ * as reactive state — for example a popup deciding on mount whether it was opened
+ * by keyboard, where re-rendering on later modality changes would be wrong.
+ */
+const getInteractionModality = () => currentModality;
+
+/**
+ * How the user last interacted with the page, as reactive state. Re-renders the
+ * caller when the user switches between keyboard and pointer.
+ */
+exports.getInteractionModality = getInteractionModality;
+const useInteractionModality = function () {
+  let enabled = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : true;
+  const [modality, setModality] = (0, _react.useState)(() => getInteractionModality());
+  (0, _react.useEffect)(() => {
+    if (!enabled) {
+      return;
+    }
+    return subscribe(setModality);
+  }, [enabled]);
+  return enabled ? modality : 'pointer';
+};
+exports.useInteractionModality = useInteractionModality;

package/lib/utils/click-away/click-away.d.ts

@@ -16,6 +16,19 @@ export interface ClickAwayRefType {
 }
 export interface ClickAwayProps<TTrigger extends HTMLElement = HTMLButtonElement, TBoundary extends HTMLElement = HTMLDivElement> {
     closeOnEscapeKeypress?: boolean;
+    /**
+     * Return focus to whatever had it before the popup opened, when the popup
+     * closes with focus still inside it (Escape, a selection, Tab past the edge).
+     * A click elsewhere on the page is exempt: focus belongs where the user
+     * clicked.
+     *
+     * Off by default. It is only wanted where something moves focus INTO the
+     * popup — otherwise focus never left the trigger and there is nothing to
+     * restore, and calling `focus()` on a trigger that already has it can be
+     * enough to disturb a consumer (a field that opens its own menu on focus
+     * would reopen the popup that just closed).
+     */
+    restoreFocusOnClose?: boolean;
     children: (props: ChildProps<TTrigger, TBoundary>) => React.ReactNode;
     onChange?: (isOpen: boolean) => unknown;
     clickAwayRef?: React.RefObject<ClickAwayRefType | null>;
@@ -56,11 +69,14 @@ export declare class ClickAway<TTrigger extends HTMLElement = HTMLButtonElement,
     el: HTMLElement | null | undefined;
     boundaryRef: BoundaryRefType<TBoundary>;
     triggerRef: TriggerRefType<TTrigger>;
+    previouslyFocused: HTMLElement | null;
+    closedByOutsideClick: boolean;
     componentDidMount(): void;
     componentDidUpdate(_prevProps: Readonly<ClickAwayProps<TTrigger, TBoundary>>, prevState: Readonly<ClickAwayState>): void;
     componentWillUnmount(): void;
     render(): React.ReactNode;
     handleOpenClick: () => void;
+    restoreFocus: () => void;
     handleCloseClick: (evt: MouseEvent) => void;
     handleCloseOnEscapeKeypress: (evt?: KeyboardEvent) => void;
     forceClose: () => void;

package/lib/utils/click-away/click-away.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"click-away.d.ts","sourceRoot":"","sources":["../../../src/utils/click-away/click-away.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"click-away.d.ts","sourceRoot":"","sources":["../../../src/utils/click-away/click-away.ts"],"names":[],"mappings":"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"}

package/lib/utils/click-away/click-away.js

@@ -24,6 +24,17 @@ class ClickAway extends React.Component {
   el = null;
   boundaryRef = /*#__PURE__*/React.createRef();
   triggerRef = /*#__PURE__*/React.createRef();
+  // Element that had focus right before the popup opened. Restored on close so
+  // keyboard focus returns to the trigger (Escape, a selection, Tab past the
+  // popup's edge) — the job FloatingFocusManager's returnFocus does for the
+  // dropdown family until they move onto this.
+  previouslyFocused = null;
+  // Set by handleCloseClick for the close that follows. A click on the page is
+  // the user moving on: focus belongs wherever they clicked (or on <body>), and
+  // pulling it back onto the trigger would re-run the trigger's own focus
+  // handling — a Typeahead opens its menu on focus, so it would reopen the very
+  // popup the click dismissed.
+  closedByOutsideClick = false;
   componentDidMount() {
     if (this.el) {
       this.setState({
@@ -49,6 +60,12 @@ class ClickAway extends React.Component {
           capture: true
         });
         window.document.removeEventListener('keyup', this.handleCloseOnEscapeKeypress);
+        if (this.closedByOutsideClick || !this.props.restoreFocusOnClose) {
+          this.previouslyFocused = null;
+        } else {
+          this.restoreFocus();
+        }
+        this.closedByOutsideClick = false;
       }
     }
   }
@@ -92,11 +109,42 @@ class ClickAway extends React.Component {
     if (this.el) {
       pageBottom = this.pageBottom();
     }
+
+    // Capture the focused element before opening (still the trigger at this
+    // point, before the popup mounts and moves focus into itself) so it can be
+    // restored on close.
+    if (this.props.restoreFocusOnClose && !this.state.isOpen && typeof window.document !== 'undefined') {
+      this.previouslyFocused = window.document.activeElement;
+    }
     this.setState({
       isOpen: !this.state.isOpen,
       pageBottom
     }, this.handleOnChange);
   };
+
+  // Return focus to the trigger when the popup closes — but only if focus was
+  // lost to the document body (the focused popup element was unmounted). If the
+  // user moved focus elsewhere (e.g. clicked another control), leave it there.
+  restoreFocus = () => {
+    const previous = this.previouslyFocused;
+    this.previouslyFocused = null;
+    if (typeof window.document === 'undefined') {
+      return;
+    }
+    const active = window.document.activeElement;
+    const focusLost = !active || active === window.document.body;
+    if (!focusLost) {
+      return;
+    }
+    // `previouslyFocused` is <body> whenever the opening click did not land on a
+    // natively focusable element — notably Safari and Firefox on macOS, which do
+    // not focus a <button> on click. Restoring it would be a no-op that strands
+    // focus at the top of the document, so fall back to the trigger itself.
+    const target = previous && previous !== window.document.body ? previous : this.triggerRef.current;
+    if (target && window.document.contains(target)) {
+      target.focus();
+    }
+  };
   handleCloseClick = evt => {
     if (evt.target instanceof Node && this.props.containsNestedFloatingPortals && this.boundaryRef.current?.parentElement && (this.boundaryRef.current.parentElement === evt.target || this.boundaryRef.current.parentElement.contains(evt.target))) {
       return;
@@ -107,6 +155,7 @@ class ClickAway extends React.Component {
     if (evt.target instanceof Node && this.triggerRef && (this.triggerRef.current === evt.target || this.triggerRef.current?.contains(evt.target))) {
       return;
     }
+    this.closedByOutsideClick = true;
     this.setState({
       isOpen: false
     }, this.handleOnChange);

package/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaced-out/genesis-mcp",
-  "version": "1.0.50",
+  "version": "1.0.52",
   "description": "MCP server for Genesis UI Design System - provides AI assistants with access to components, hooks, and design tokens",
   "type": "module",
   "main": "index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaced-out/ui-design-system",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "Sense UI components library",
   "author": {
     "name": "Spaced Out"