Proposal for Streamlining Zag.js with Enhanced Event and State Management

[kimik-hyum]

Hello Zag.js Community,

As a dedicated user of Zag.js, I've greatly appreciated its capabilities. However, I've also identified some areas where enhancements could streamline the library further. These include:

1. Installation Overhead: The necessity to install each UI component individually.
2. Mandatory Accessibility Code: Accessibility-related code is always included, even when not needed.
3. Redundant Event Handling: Frequent duplication of event handling code (like onClick, onFocus) across different UI components.
   To address these challenges, I propose an idea for a more dynamic approach to event handling and state management, which aligns with Zag.js's design philosophy but offers greater flexibility and efficiency.

Core Idea:
Introduce a system for detailed control over UI component states and event handling, without overwhelming developers with unneeded code or complexity. This system would include a foundational connect function, customizable event handlers, and an optimized state management approach.

Key Features:

Flexible Event Handlers:

A factory pattern (createEventHandler) for managing various events and performing context-specific actions.
An option for adding a delay to event handling for controlled state updates.

Optimized State Management:

Leveraging the existing useState hook, extending its capabilities through the connect function for enhanced functionality.

Customizable Component Props:

Allowing custom property generators to be injected into the connect function for adding necessary attributes based on the component's state and requirements.

Benefits:
Redundancy Reduction: This approach minimizes duplicated code, especially in event handling.
Selective Inclusion: Developers can choose what to include, reducing bloat, particularly regarding accessibility code.
Consistency and Flexibility: Maintains a consistent API while allowing versatile implementations.

Example Implementation:
Here is an example of how this concept could be implemented for a tab component:

import tabConnect from "../../util/tabConnect";
import { getTabListProps } from "../../util/tabAccessibility";

type Item = {
  value: string;
  label: string;
};

export default function Tab({ data }: { data: Item[] }) {
  const [value, send] = useState("tab1");
  const api = tabConnect(value, send, {
    getTabListProps,
  });
  const customHandlers = {
    onClick: (event: React.SyntheticEvent<HTMLElement>) => console.log("Clicked!"),
  };

  return (
    <div>
      <div {...api.getTabListProps}>
        {data.map((item) => {
          const isDisabled = item.value === "tab3";
          return (
            <button
              id={`tab-${item.value}`}
              disabled={isDisabled}
              {...api.createEventHandler(["onClick"], item.value, {
                customHandlers,
              })}
              {...api.getTabTriggerProps(item.value)}
              key={item.value}
            >
              {item.label}
            </button>
          );
        })}
      </div>
      {data.map((item) => (
        <div {...api.getContentProps(item.value)} key={item.value}>
          {item.label}
        </div>
      ))}
    </div>
  );
}

This example demonstrates the potential for a more modular and efficient way of handling component states and events in Zag.js.

In the example above, tabConnect was used only for the tab UI, but the simple UI operates based on connect, and the code that focuses only on implementation is as follows.

type EventType = keyof React.DOMAttributes<HTMLElement>;
type CreateEventHandlerOptions = {
  customHandlers?: Partial<
    Record<EventType, (event: React.SyntheticEvent<HTMLElement>) => void>
  >;
  delay?: number;
};

function connect<T>(
  value: T,
  send: (value: T) => void,
  multiple: boolean = false
) {
  const timeouts: Record<string, NodeJS.Timeout> = {};
  const createEventHandler = (
    eventTypes: EventType | EventType[],
    itemValue: string | boolean,
    options?: CreateEventHandlerOptions
  ) => {
    const { customHandlers, delay } = options || {};
    const handlers: Record<
      string,
      (event: React.SyntheticEvent<HTMLElement>) => void
    > = {};

    const eventList = Array.isArray(eventTypes) ? eventTypes : [eventTypes];
    const handleClick = (event: React.SyntheticEvent<HTMLElement>) => {
      const updateValue = () => {
        if (multiple && typeof itemValue === "string") {
          let newValue: string[];
          if (Array.isArray(value)) {
            if (value.includes(itemValue)) {
              newValue = value.filter((v) => v !== itemValue);
            } else {
              newValue = [...value, itemValue];
            }
          } else {
            newValue = [itemValue];
          }
          send(newValue as T);
        } else {
          send(itemValue as T);
        }
      };
      if (!!delay) {
        const eventId = `${event.type}-${String(itemValue)}`;
        clearTimeout(timeouts[eventId]);
        timeouts[eventId] = setTimeout(updateValue, delay);
      } else {
        updateValue();
      }
      customHandlers?.onClick?.(event);
    };

    eventList.forEach((eventType) => {
      handlers[eventType] = handleClick;
    });

    return handlers;
  };
  const getContentProps = (itemValue: string) => {
    let isHidden: boolean;

    if (multiple && Array.isArray(value)) {
      isHidden = !value.includes(itemValue);
    } else {
      isHidden = value !== itemValue;
    }

    return {
      hidden: isHidden,
    };
  };

  return { createEventHandler, getContentProps };
}

export default connect;

TabConnect using connect is as follows.

import connect from "./connect";

type TabConnectAPI = ReturnType<typeof connect> & {
  getTabTriggerProps: (itemValue: string) => Record<string, any>;
  getTabListProps?: Record<string, any>;
};

type TabConnectOptions = {
  getTabListProps?: (
    value: string,
    send: (value: string) => void
  ) => Record<string, any>;
};

function tabConnect(
  value: string,
  send: (value: string) => void,
  options?: TabConnectOptions
): TabConnectAPI {
  const baseProps = connect(value, send);

  const api: TabConnectAPI = {
    ...baseProps,
    getTabTriggerProps: (itemValue: string) => {
      const isSelected = value === itemValue;
      return {
        role: "tab",
        "aria-selected": isSelected,
        "data-value": itemValue,
        "aria-controls": `tab-content-${itemValue}`,
        tabIndex: isSelected ? 0 : -1,
      };
    },
    getTabListProps: options?.getTabListProps
      ? options.getTabListProps(value, send)
      : {},
  };

  return api;
}

export default tabConnect;

Please understand that the code is a mess, focusing only on implementation.

The above code provides basic accessibility to tabs, and when related accessibility to tabList is needed, use the code below:

import { getTabListProps } from "../../util/tabAccessibility";

...
const api = tabConnect(value, send, {
    getTabListProps,
  });

I thought it would be a good idea to not include it in the bundle when accessibility is not needed.

However, the code I wrote focuses only on implementing the idea, so the type, performance, and code quality may be low.

thank you

[deancochran]

I want to second the proposal here.

I have issues with state management. The tool I built utilizing zag.js has problems with focusing in and out of different components wrapped by Zag.js components. The state management solution we have devised is brute force and does not utilize Zag.js natively

[alfianandinugraha]

Yes, this is what happened to me too especially for standalone componen like DatePicker and ColorInput. Zag will treat them as content of popover so it will impact the accessibility