import { ArgsTable, Meta, Story } from "@storybook/addon-docs";
import { Button } from "@components/button";
import { ButtonGroup } from "@components/button";
import { Card } from "@components/card";
import { ComponentInfo, Preview, Tagline } from "@stories/components";
import { Content, Footer, Header, InnerContent, InnerFooter, InnerHeader } from "@components/placeholders";
import { ET, Planet, SpacePortrait, SpacePortraitHorizontal, TheMartian } from "./assets";
import { Heading, InnerHeading, Paragraph } from "@components/typography";
import { Illustration } from "@components/illustration";
import { Image } from "@components/image";
import { InnerModal, InnerModalTrigger, Modal, ModalTrigger } from "@components/modal";
import { TextLink } from "@components/link";

<Meta
    title="Components/Modal"
    id="modal"
/>

# Modal

<Tagline>A modal focus the user’s attention exclusively on one task or piece of information via a dialog that sits on top of the page content.</Tagline>

<ComponentInfo
    usage={"import { Modal, ModalTrigger, Heading, Header, Content, Footer, ModalTriggerContext, useModalTriggerContext } from \"@sharegate/orbit-ui\";"}
    ariaPath="dialogmodal"
    githubPath="/packages/components/src/modal/src"
/>

## Guidelines

### When to use

- To let a user interact with the application without jumping to a new page and interrupting the user's workflow.

### Content

- Provide enough information for the user to be able to take a decision in the spot, or a way to come back to the choice later.
- Not use complex layouts, modals are not pages. Consider using a page when a modal layout is getting too complex.
- Not rely on images or illustrations in order to provide essential information to the user.
- Not ask the user a question right above the button(s).

### Accessibility

- Make sure to autofocus on the first interactive element in the modal, except if it’s a destructive action as it could trigger unwanted behavior.
- Prioritize dismissible modals whenever possible in order to give control to the user.
- Use modals sparingly as it disrupt the user's flow.

### Modal vs Alert

If your modal has no way to be dismissed and requires the user to make a choice use an [Alert](?path=/docs/alert--default-story).

## Usage

### Default

A modal must have an heading and a content.

<Preview>
    <Story name="default">
        <ModalTrigger>
            <Button variant="secondary">Open</Button>
            <Modal>
                <Heading>Cloud City</Heading>
                <Content>
                    <Paragraph>Cloud City was a completely man-made tibanna gas mining colony staff hovering over the gas giant Bespin, occupied by millions of workers, tourists and support staff. Located in Bespin's Life Zone, the station had no need for airlocks or life support systems, with the atmosphere comprised mostly of oxygen and acceptable levels of gravity and temperature.</Paragraph>
                    <Paragraph>The station was situated 59,000 kilometers above Bespin's core, while its disk was approximately 16.2 kilometers in diameter. 36,000 repulsorlift engines and tractor beam generators kept the giant city floating above the planet. It contained 392 levels, along with platforms and rooms for residents and visitors.</Paragraph>
                </Content>
            </Modal>
        </ModalTrigger>
    </Story>
</Preview>

### Image

A modal can have a side banner [image](?path=/story/chromatic-image--default). Make sure the image has no essential information as it could be cropped in mobile view. Images should not prevent a user from seeing the close button, be conscious of this.

<Preview scope={{ SpacePortrait, SpacePortraitHorizontal }}>
    <Story name="image">
        <ModalTrigger>
            <Button variant="secondary">Open</Button>
            <Modal>
                <Image src={{ base: SpacePortraitHorizontal, sm: SpacePortrait }} alt="City over clouds" />
                <Heading>Cloud City</Heading>
                <Content>
                    <Paragraph>Cloud City was a completely man-made tibanna gas mining colony staff hovering over the gas giant Bespin, occupied by millions of workers, tourists and support staff. Located in Bespin's Life Zone, the station had no need for airlocks or life support systems, with the atmosphere comprised mostly of oxygen and acceptable levels of gravity and temperature.</Paragraph>
                    <Paragraph>The station was situated 59,000 kilometers above Bespin's core, while its disk was approximately 16.2 kilometers in diameter. 36,000 repulsorlift engines and tractor beam generators kept the giant city floating above the planet. It contained 392 levels, along with platforms and rooms for residents and visitors.</Paragraph>
                </Content>
            </Modal>
        </ModalTrigger>
    </Story>
</Preview>

Or an [illustration](?path=/docs/illustration--horizontal). Prefer 1:1 ratio for illustrations to prevent them to render a Modal too high on small resolutions, alternatively in mobile use another illustration that has a 1:1 ratio.

<Preview scope={{ Planet }}>
    <Story name="illustration centered">
        <ModalTrigger>
            <Button variant="secondary">Open</Button>
            <Modal>
                <Illustration backgroundColor="alias-accent-light">
                    <Image src={Planet} alt="Planet Logo" />
                </Illustration>
                <Heading>Cloud City</Heading>
                <Content>
                    <Paragraph>Cloud City was a completely man-made tibanna gas mining colony staff hovering over the gas giant Bespin, occupied by millions of workers, tourists and support staff. Located in Bespin's Life Zone, the station had no need for airlocks or life support systems, with the atmosphere comprised mostly of oxygen and acceptable levels of gravity and temperature.</Paragraph>
                    <Paragraph>The station was situated 59,000 kilometers above Bespin's core, while its disk was approximately 16.2 kilometers in diameter. 36,000 repulsorlift engines and tractor beam generators kept the giant city floating above the planet. It contained 392 levels, along with platforms and rooms for residents and visitors.</Paragraph>
                </Content>
            </Modal>
        </ModalTrigger>
    </Story>
</Preview>

### Choice

A modal can offer a choice between 2 options. Keep the copy not too long in order to help the user quickly make his choice.

<Preview scope={{ ET, TheMartian }}>
    <Story name="choice">
        <ModalTrigger>
            <Button variant="secondary">Open</Button>
            <Modal>
                <Heading>Which of the following movie is the greatest space movie?</Heading>
                <Content>
                    <Card>
                        <Image src={ET} alt="E.T. poster" />
                        <Heading>E.T.</Heading>
                        <Content>"E.T. phone home,"" mutters the titular character as he attempts to contact his home planet, and audiences around the world fell in love. The timeless story of an intimate friendship between a boy and his alien friend, “E.T.” has resonated with generations of families, and is widely considered one of the greatest films of all time.</Content>
                        <Button variant="secondary" >Choose</Button>
                    </Card>
                    <Card>
                        <Image src={TheMartian} alt="The Martian poster" />
                        <Heading>The Martian</Heading>
                        <Content>Based on the popular novel, “The Martian” is about mankind joining for a singular mission: save astronaut Mark Watney, who was abandoned on Mars after the rest of his crew made an emergency exit during a dust storm.</Content>
                        <Button variant="secondary" >Choose</Button>
                    </Card>
                </Content>
            </Modal>
        </ModalTrigger>
    </Story>
</Preview>

### Header

Use an header to provide additional information usually in the form of a link or a tooltip that provides more context to the task at hand. Links should open in a new window.

<Preview>
    <Story name="header">
        <ModalTrigger>
            <Button variant="secondary">Open</Button>
            <Modal>
                <Heading>Cloud City</Heading>
                <Header>
                    <TextLink href="https://en.wikipedia.org/wiki/Floating_cities_and_islands_in_fiction" external>Wikipedia</TextLink>
                </Header>
                <Content>
                    <Paragraph>Cloud City was a completely man-made tibanna gas mining colony staff hovering over the gas giant Bespin, occupied by millions of workers, tourists and support staff. Located in Bespin's Life Zone, the station had no need for airlocks or life support systems, with the atmosphere comprised mostly of oxygen and acceptable levels of gravity and temperature.</Paragraph>
                    <Paragraph>The station was situated 59,000 kilometers above Bespin's core, while its disk was approximately 16.2 kilometers in diameter. 36,000 repulsorlift engines and tractor beam generators kept the giant city floating above the planet. It contained 392 levels, along with platforms and rooms for residents and visitors.</Paragraph>
                </Content>
            </Modal>
        </ModalTrigger>
    </Story>
</Preview>

### Footer

Use a footer to provide trivial information about content present in the modal, like a step : 1/3.

<Preview>
    <Story name="footer">
        <ModalTrigger>
            <Button variant="secondary">Open</Button>
            <Modal>
                <Heading>Cloud City</Heading>
                <Content>
                    <Paragraph>Cloud City was a completely man-made tibanna gas mining colony staff hovering over the gas giant Bespin, occupied by millions of workers, tourists and support staff. Located in Bespin's Life Zone, the station had no need for airlocks or life support systems, with the atmosphere comprised mostly of oxygen and acceptable levels of gravity and temperature.</Paragraph>
                    <Paragraph>The station was situated 59,000 kilometers above Bespin's core, while its disk was approximately 16.2 kilometers in diameter. 36,000 repulsorlift engines and tractor beam generators kept the giant city floating above the planet. It contained 392 levels, along with platforms and rooms for residents and visitors.</Paragraph>
                </Content>
                <Footer>Copyright 2021</Footer>
            </Modal>
        </ModalTrigger>
    </Story>
</Preview>

### Buttons

A modal can have a single [button](?path=/docs/button--default-story). Use a primary [button](?path=/docs/button--default-story) to provide the main action.

<Preview>
    <Story name="button">
        <ModalTrigger>
            <Button variant="secondary">Open</Button>
            <Modal>
                <Heading>Cloud City</Heading>
                <Content>
                    <Paragraph>Cloud City was a completely man-made tibanna gas mining colony staff hovering over the gas giant Bespin, occupied by millions of workers, tourists and support staff. Located in Bespin's Life Zone, the station had no need for airlocks or life support systems, with the atmosphere comprised mostly of oxygen and acceptable levels of gravity and temperature.</Paragraph>
                    <Paragraph>The station was situated 59,000 kilometers above Bespin's core, while its disk was approximately 16.2 kilometers in diameter. 36,000 repulsorlift engines and tractor beam generators kept the giant city floating above the planet. It contained 392 levels, along with platforms and rooms for residents and visitors.</Paragraph>
                </Content>
                <Button>Choose</Button>
            </Modal>
        </ModalTrigger>
    </Story>
</Preview>

Or a [group of button](?path=/docs/button--default-story#button-group). A maximum of 3 buttons are allowed in a modal, when necessary. The secondary and tertiary actions should be using a secondary variant.

<Preview>
    <Story name="button group">
        <ModalTrigger>
            <Button variant="secondary">Open</Button>
            <Modal>
                <Heading>Cloud City</Heading>
                <Content>
                    <Paragraph>Cloud City was a completely man-made tibanna gas mining colony staff hovering over the gas giant Bespin, occupied by millions of workers, tourists and support staff. Located in Bespin's Life Zone, the station had no need for airlocks or life support systems, with the atmosphere comprised mostly of oxygen and acceptable levels of gravity and temperature.</Paragraph>
                    <Paragraph>The station was situated 59,000 kilometers above Bespin's core, while its disk was approximately 16.2 kilometers in diameter. 36,000 repulsorlift engines and tractor beam generators kept the giant city floating above the planet. It contained 392 levels, along with platforms and rooms for residents and visitors.</Paragraph>
                </Content>
                <ButtonGroup>
                    <Button variant="secondary">Select</Button>
                    <Button>Next</Button>
                </ButtonGroup>
            </Modal>
        </ModalTrigger>
    </Story>
</Preview>

### Modal context

A modal `isOpen` state or `close` function can be retrieved from `useModalTriggerContext`.

<Preview filePath="/modal/docs/ModalContext" />

### Dismissable

By default, a modal will dismiss on outside interactions and `esc` keydown. However, in some cases, you might want to force the user to explicitly dismiss the modal with a targeted call to action. This is what the dismissable prop is for.

You can set the `dismissable` prop to `false` and render a call to action which will manually dismiss the popover by calling a `close` function retrieved from the `useModalTriggerContext` hook.

> Inlining the call to `useModalTriggerContext` in `ModalTrigger` will not work.

<Preview filePath="/modal/docs/ModalCustomClose" />

### Controlled

The `open` state can be handled in controlled mode.

<Preview filePath="/modal/docs/ControlledModal" />

### Custom trigger

You don't have to use a `ModalTrigger` component if it doesn't fit your needs. A modal component can be used on it's own with any custom trigger which follow a few rules:

- The custom trigger provide a valid `<DialogTriggerContext>` with a `close` function.
- The custom trigger is responsible of show/hide the modal. This is usually done in combination with an [overlay](?path=/docs/overlay--page) component.

<Preview filePath="/modal/docs/CustomTrigger" />

## API

### ModalTrigger

<ComponentInfo
    usage={"import { ModalTrigger } from \"@sharegate/orbit-ui\";"}
    inherits={[InnerModalTrigger.defaultElement, "styled-component"]}
    compact
/>

<ArgsTable of={InnerModalTrigger} sort="alpha" />

### Modal

<ComponentInfo
    usage={"import { Modal } from \"@sharegate/orbit-ui\";"}
    slots={["image", "illustration", "heading", "header", "content", "footer", "button", "button-group"]}
    inherits={[InnerModal.defaultElement, "styled-component"]}
    compact
/>

<ArgsTable of={InnerModal} sort="alpha" />

### Heading

<ComponentInfo
    usage={"import { Heading } from \"@sharegate/orbit-ui\";"}
    inherits={[InnerHeading.defaultElement, "styled-component"]}
    compact
/>

<ArgsTable of={InnerHeading} sort="alpha" />

### Header

<ComponentInfo
    usage={"import { Header } from \"@sharegate/orbit-ui\";"}
    inherits={[InnerHeader.defaultElement, "styled-component"]}
    compact
/>

<ArgsTable of={InnerHeader} sort="alpha" />

### Content

<ComponentInfo
    usage={"import { Content } from \"@sharegate/orbit-ui\";"}
    inherits={[InnerContent.defaultElement, "styled-component"]}
    compact
/>

<ArgsTable of={InnerContent} sort="alpha" />

### Footer

<ComponentInfo
    usage={"import { Footer } from \"@sharegate/orbit-ui\";"}
    inherits={[InnerFooter.defaultElement, "styled-component"]}
    compact
/>

<ArgsTable of={InnerFooter} sort="alpha" />
