feat: added new modal title and description components

Author: thejackshelton

.changeset/eight-spiders-brake.md

@@ -0,0 +1,61 @@
+---
+'@qwik-ui/headless': patch
+---
+
+fix: modal does not close unless the dialog backdrop is clicked (including dangling content)
+
+fix: polyfilled popovers render correctly inside of modals.
+
+fix: nested modals will now close the current modal when the backdrop is clicked.
+
+fix: nested modals will now close the current modal when the escape key is pressed.
+
+fix: select does not execute code until interaction (including core).
+
+tests: larger test suite for modals.
+
+deprecated: `ModalHeader`, `ModalContent`, `ModalFooter` have been deprecated, as they do not pose significant a11y advantages.
+
+feat: Two new Modal component pieces. `ModalTitle` and `ModalDescription`. These help give our modal an accessible name and supporting description (optional).
+
+feat: Modal now uses the following CSS as a default inside of an @layer
+
+```css
+@layer qwik-ui {
+  /* browsers automatically set an interesting max-width and max-height for dialogs 
+    https://twitter.com/t3dotgg/status/1774350919133691936
+  */
+  dialog:modal {
+    max-width: unset;
+    max-height: unset;
+  }
+}
+```
+
+The default browser styles:
+
+![alt text](image.png)
+
+Make it difficult to style a dialog element full-screen, which has led to some confusion recently both in this repo and across the web. The above change strips the responsible browser styles from the dialog eleemnt (which is used by Qwik UI's modal component).
+
+> For more info, feel free to check out the link in the code snippet above.
+
+> Note: In the future, we intend to use the dot notation for the `Modal` component.
+
+> Note: In the future, we intend to change the modal API to include a trigger. The proposed API is as follows:
+
+### Syntax Proposal
+
+```tsx
+<Modal.Root>
+  <Modal.Trigger>Trigger</Modal.Trigger>
+  <Modal.Content>
+    {' '}
+    {/*  This is the current <Modal /> */}
+    <Modal.Title>Edit Profile</Modal.Title>
+    <Modal.Description>You can update your profile here.</Modal.Description>
+  </Modal.Content>
+</Modal.Root>
+```
+
+Let us know your thoughts on this potential API change in the Qwik UI discord!

.changeset/image.png

@@ -1,5 +1,5 @@
 import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
-import { Modal } from '@qwik-ui/headless';
+import { Modal, ModalTitle, ModalDescription } from '@qwik-ui/headless';
 import styles from '../snippets/modal.css?inline';
 
 export default component$(() => {
@@ -12,7 +12,29 @@ export default component$(() => {
         Open Modal
       </button>
       <Modal class="modal" bind:show={isOpen}>
-        Modal Content
+        <ModalTitle>Edit Profile</ModalTitle>
+        <ModalDescription>
+          You can update your profile here. Hit the save button when finished.
+        </ModalDescription>
+        <label for="name">Name</label>
+        <input
+          class="mt-2 rounded-base bg-background px-4 py-[10px] text-foreground"
+          id="name"
+          type="text"
+          placeholder="John Doe"
+        />
+        <label for="email">Email</label>
+        <input id="email" type="text" placeholder="[email protected]" />
+        <footer>
+          <button onClick$={() => (isOpen.value = false)}>Cancel</button>
+          <button onClick$={() => (isOpen.value = false)}>Save Changes</button>
+        </footer>
+        <button
+          onClick$={() => (isOpen.value = false)}
+          class="absolute right-6 top-[26px]"
+        >
+          Close
+        </button>
       </Modal>
     </>
   );

apps/website/src/routes/docs/headless/modal/examples/hero.tsx

@@ -2,3 +2,5 @@ export * from './modal';
 export * from './modal-content';
 export * from './modal-footer';
 export * from './modal-header';
+export * from './modal-title';
+export * from './modal-description';

packages/kit-headless/src/components/modal/index.ts

@@ -0,0 +1,8 @@
+import { createContextId } from '@builder.io/qwik';
+
+export const modalContextId = createContextId<ModalContext>('qui-modal');
+
+export type ModalContext = {
+  // core state
+  localId: string;
+};

packages/kit-headless/src/components/modal/modal-context.tsx

@@ -0,0 +1,14 @@
+import { Slot, component$, useContext } from '@builder.io/qwik';
+import { modalContextId } from './modal-context';
+
+export const ModalDescription = component$(() => {
+  const context = useContext(modalContextId);
+
+  const descriptionId = `${context.localId}-description`;
+
+  return (
+    <p id={descriptionId}>
+      <Slot />
+    </p>
+  );
+});

packages/kit-headless/src/components/modal/modal-description.tsx

@@ -0,0 +1,14 @@
+import { Slot, component$, useContext } from '@builder.io/qwik';
+import { modalContextId } from './modal-context';
+
+export const ModalTitle = component$(() => {
+  const context = useContext(modalContextId);
+
+  const titleId = `${context.localId}-title`;
+
+  return (
+    <h2 id={titleId}>
+      <Slot />
+    </h2>
+  );
+});

packages/kit-headless/src/components/modal/modal-title.tsx

@@ -8,7 +8,15 @@ export function createTestDriver<T extends DriverLocator>(rootLocator: T) {
   };
 
   const getTrigger = () => {
-    return rootLocator.getByRole('button');
+    return rootLocator.getByRole('button', { name: 'Open Modal' });
+  };
+
+  const getTitle = () => {
+    return rootLocator.getByRole('heading');
+  };
+
+  const getDescription = () => {
+    return rootLocator.getByRole('paragraph');
   };
 
   const openModal = async () => {
@@ -24,5 +32,7 @@ export function createTestDriver<T extends DriverLocator>(rootLocator: T) {
     getModal,
     getTrigger,
     openModal,
+    getTitle,
+    getDescription,
   };
 }

packages/kit-headless/src/components/modal/modal.driver.ts

@@ -256,3 +256,31 @@ test.describe('Nested Modals', () => {
     await expect(d.getModal()).toBeVisible();
   });
 });
+
+test.describe('A11y', () => {
+  test(`GIVEN a modal
+        WHEN the modal is rendered
+        THEN it should have an accessible name`, async ({ page }) => {
+    const { driver: d } = await setup(page, 'hero');
+
+    await d.openModal();
+
+    const titleId = await d.getTitle().getAttribute('id');
+
+    await expect(d.getModal()).toHaveAttribute('aria-labelledby', `${titleId}`);
+  });
+
+  test(`GIVEN a modal
+        WHEN an optional description is added
+        THEN the modal's aria-describedby should point to the description`, async ({
+    page,
+  }) => {
+    const { driver: d } = await setup(page, 'hero');
+
+    await d.openModal();
+
+    const descriptionId = await d.getDescription().getAttribute('id');
+
+    await expect(d.getModal()).toHaveAttribute('aria-describedby', `${descriptionId}`);
+  });
+});

packages/kit-headless/src/components/modal/modal.test.ts

@@ -9,8 +9,12 @@ import {
   useStyles$,
   useTask$,
   sync$,
+  useId,
+  useContextProvider,
 } from '@builder.io/qwik';
 
+import { ModalContext, modalContextId } from './modal-context';
+
 import styles from './modal.css?inline';
 import { useModal } from './use-modal';
 
@@ -34,6 +38,7 @@ export const Modal = component$((props: ModalProps) => {
   } = useModal();
 
   const modalRef = useSignal<HTMLDialogElement>();
+  const localId = useId();
 
   const { 'bind:show': showSig } = props;
 
@@ -97,9 +102,18 @@ export const Modal = component$((props: ModalProps) => {
     }
   });
 
+  const context: ModalContext = {
+    localId,
+  };
+
+  useContextProvider(modalContextId, context);
+
   return (
     <dialog
       {...props}
+      id={`${localId}-root`}
+      aria-labelledby={`${localId}-title`}
+      aria-describedby={`${localId}-description`}
       data-state={showSig.value ? 'open' : 'closed'}
       role={props.alert === true ? 'alertdialog' : 'dialog'}
       ref={modalRef}