Defining core composables for Modals

[onmax]

What is this?

I have a proposal for the modal components (dialogue, alert, popover...). As this is a big change, I think it is better to discuss it first, improve it and then work on it.

Warning
The code provided in this discussion has not been extensively tested, but you can check out the idea and how it works in the Popover in this commit (which for now it works for the basic cases)

Composables

useEmitCancelableEvent

Implementation

We create an event and emit it. If the user calls e.preventDefault() on this event, the callback will not be called.

Usage

    useEmitCancelableEvent(emit, "pointer-down-outside", hidePopover, e);
    useEmitCancelableEvent(emit, "escape-key-down", hidePopover, e);

useEventListener

Implementation

This will allow us to listen to events. Additionally, you can add a flag called disabled which will automatically remove the listener when it is false and re-enable it when it is true.

Usage

const disabled = computed(() => !open.value);

useEventListener(
  document.documentElement,
  "click",
  (e) => {
    useEmitCancelableEvent(emit, "pointer-down-outside", hidePopover, e);
  },
  { disabled, exclude: [primitiveElement, triggerElement] } // The exlcude will ignore the event
);

useEventListener(
  document.documentElement,
  "keydown",
  (e) => {
    if (e.key !== "Escape") return;
    useEmitCancelableEvent(emit, "escape-key-down", hidePopover, e);
  },
  { disabled }
);

useModalInteraction

Implementation

It will handle the events that might occur when the modal opens or closes. Basically, the default behaviour with modals is:

1. When the modal opens: Automatically focus the user on any focusable element.
2. When the modal closes: Focus on the triggerable element.

Both of these events should be optional, and the user can cancel them. This composable basically handles that case and also locks the body if it is required.

Other options/features can be added to this composable whenever the modal is open/closed in the future

Usage

useModalInteraction(primitiveElement, { open, triggerElement }, emit);

useFocusOutside

I haven't done anything related to this, but basically, detect when focus goes out and otherwise emit a cancelable event and close the modal.

useInjected

Not related specifically to modals, but to the whole package.

Implementation

Automatically inject values and return them as JSON. An error will be thrown if the key doesn't exist.

This composable works super well, and will remove so many injectedValue?. and make the code more readable everywhere.

Usage

const { open, triggerElement, hidePopover, dataState, contentId } = useInjected(POPOVER_INJECTION_KEY);

[zernonia]

Nicely done on these composable! I have some comment here ya

1. In order for useEmitCancelableEvent, we need await nextTicket() for domain flush, then the defaultPrevented will be correct. Checkout playground
2. I think we can rename useEmitCancelableEvent, It's not quite explicit enough what it does 😬
3. I think it is better to have DissmissableLayer (similar to RadixUI) instead of this useModalInteraction, since there are many components is using that.

[onmax]

Thanks for you answer 👍

1. I don't think we need to add await nextTick() for custom events.
   The function flow is event -> useEmitCancelableEvent -> emit event -> check if event has been prevented
   This is different to native events, and since out composable is only going to trigger custom events, I don't think we need it. Please correct me if I am wrong.
   Here the updated Playground

2. I agree, I don't really like the current name, but out of ideas 🙈

3. Sounds great. That composable is not really a composable, but not sure how to implement it. Would you mind to help with that?

[zernonia]

1. I dont think we should only consider triggering custom events, in NavigationMenuLink, it is a @click event where we need to be prevented. thus I think we should add nextTick to consider all cases.
2. Hahaha I can't think of a proper name too 😂