@warp-ds/elements 2.9.2-next.1 → 2.10.0-next.10

package/dist/docs/link/link.md

@@ -4,14 +4,107 @@
 
 Buttons are used to perform actions, with different visuals for different needs.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/buttons-link--docs)
-
 ## Usage
 
+**Do:**
+
+- Use the `<w-link>` component when you need a link that looks like a button.
+
+**Do Not:**
+
+- Use the `<w-link>` component when you need a link that looks like a link. In that case, use the native `<a>` tag.
+- Use the `<w-link>` component when you need a button that looks like a button. In that case, use the native `<w-button>` tag.
+
+The following table illustrates use cases and which element to use for the purpose.
+
+| If desired behaviour is | and desired styling is | then use     |
+| ----------------------- | ---------------------- | ------------ |
+| link                    | button                 | `<w-link>`   |
+| button                  | button                 | `<w-button>` |
+| link                    | link                   | `<a>`        |
+| button                  | link                   | `<w-button>` |
+
 ## Accessibility
 
 ## Examples
 
+### Primary
+
+<elements-example>
+
+```html
+<w-link variant="primary" href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Secondary
+
+This is the default appearance.
+
+<elements-example>
+
+```html
+<w-link href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Negative
+
+<elements-example>
+
+```html
+<w-link variant="negative" href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Utility
+
+<elements-example>
+
+```html
+<w-link variant="utility" href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Quiet
+
+<elements-example>
+
+```html
+<w-link variant="quiet" href="#">Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Small
+
+All variants can be small.
+
+<elements-example>
+
+```html
+<w-link href="#" small>Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+### Full width
+
+
+<elements-example>
+
+```html
+<w-link href="#" full-width>Go to the top of this page</w-link>
+```
+
+</elements-example>
+
+## Styling API
+
 ## `<w-link>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -20,77 +113,73 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| autofocus | `boolean` | `false` | - |
-| disabled | `boolean` | `false` | - |
-| full-width | `boolean` | `false` | - |
-| href | `string` | `-` | - |
-| rel | `string` | `-` | - |
-| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
-| small | `boolean` | `false` | - |
-| target | `string` | `-` | - |
-| variant | [`ButtonVariant`](#buttonvariant) | `-` | - |
+| autofocus | `boolean` | `false` | Focus the link after it is rendered |
+| disabled | `boolean` | `false` | Applies disabled styling, but you need to disable clicks on your own. |
+| full-width | `boolean` | `false` | Makes the link take up the full width of its parent |
+| href | `string` | `-` | The URL the link points to |
+| rel | `string` | `-` | Relationship of the linked URL. |
+| small | `boolean` | `false` | Render a smaller version |
+| target | `string` | `-` | Where to display the linked URL (e.g. `_blank`) |
+| variant | [`ButtonVariant`](#buttonvariant) | `-` | Visual style for the link/button. |
 
 ### Property Details
 
 #### autofocus
 
-
+Focus the link after it is rendered
 
 - Type: `boolean`
 - Default: `false`
 
 #### disabled
 
+Applies disabled styling, but you need to disable clicks on your own.
 
+The component renders an `<a>` element; `disabled` affects styling, but does not inherently prevent navigation. If you need to fully disable interaction, omit `href` and/or prevent default click behavior.
 
 - Type: `boolean`
 - Default: `false`
 
 #### full-width
 
-
+Makes the link take up the full width of its parent
 
 - Type: `boolean`
 - Default: `false`
 
 #### href
 
-
+The URL the link points to
 
 - Type: `string`
 - Default: `-`
 
 #### rel
 
+Relationship of the linked URL.
 
+If `target="_blank"` and `rel` is not provided, the component uses `noopener`.
 
 - Type: `string`
 - Default: `-`
 
-#### shadowRootOptions (JS only)
-
-
-
-- Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
-
 #### small
 
-
+Render a smaller version
 
 - Type: `boolean`
 - Default: `false`
 
 #### target
 
-
+Where to display the linked URL (e.g. `_blank`)
 
 - Type: `string`
 - Default: `-`
 
 #### variant
 
-
+Visual style for the link/button.
 
 - Type: [`ButtonVariant`](#buttonvariant)
 - Default: `-`

package/dist/docs/link/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/link/usage.md

@@ -1 +1,19 @@
 ## Usage
+
+**Do:**
+
+- Use the `<w-link>` component when you need a link that looks like a button.
+
+**Do Not:**
+
+- Use the `<w-link>` component when you need a link that looks like a link. In that case, use the native `<a>` tag.
+- Use the `<w-link>` component when you need a button that looks like a button. In that case, use the native `<w-button>` tag.
+
+The following table illustrates use cases and which element to use for the purpose.
+
+| If desired behaviour is | and desired styling is | then use     |
+| ----------------------- | ---------------------- | ------------ |
+| link                    | button                 | `<w-link>`   |
+| button                  | button                 | `<w-button>` |
+| link                    | link                   | `<a>`        |
+| button                  | link                   | `<w-button>` |

package/dist/docs/modal/api.md

@@ -0,0 +1,51 @@
+## `<w-modal>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| content-id | `string` | `-` | - |
+| ignore-backdrop-clicks | `boolean` | `false` | Ignores clicks to the backdrop when set |
+| show | `boolean` | `false` | Controls if the modal should show or hide. |
+
+### Property Details
+
+#### content-id
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### ignore-backdrop-clicks
+
+Ignores clicks to the backdrop when set
+
+- Type: `boolean`
+- Default: `false`
+
+#### show
+
+Controls if the modal should show or hide.
+
+You can also call the `open()` and `close()` methods.
+
+- Type: `boolean`
+- Default: `false`
+
+### Events
+
+#### hidden
+
+
+
+- Type: `CustomEvent`
+#### shown
+
+
+
+- Type: `CustomEvent`
+
+

package/dist/docs/modal/examples.md

@@ -0,0 +1,67 @@
+## Examples
+
+
+
+### With a titlebar
+
+<elements-example>
+
+```html
+<div>
+  <w-button aria-haspopup='dialog'>
+    Open a modal
+  </w-button>
+  <w-modal>
+    <w-modal-header
+      slot='header'
+      title='An example modal'
+    ></w-modal-header>
+    <div slot='content'>
+      <w-button variant='utility' small>
+        Toggle back button
+      </w-button>
+      <p>
+        I bomb atomically, Socrates' philosophies and hypotheses...
+      </p>
+      <p>
+        First I'm gonna getcha, once I gotcha, I gat-cha...
+      </p>
+    </div>
+    <w-modal-footer slot='footer'>
+      <w-button variant='primary'>
+        OK
+      </w-button>
+    </w-modal-footer>
+  </w-modal>
+</div>
+```
+
+</elements-example>
+
+### With an image at the top
+
+<elements-example>
+
+```html
+<w-button aria-haspopup="dialog" commandfor="my-modal" command="show-modal">
+    Open a modal
+</w-button>
+<w-modal id="my-modal">
+    <w-modal-header slot="header" title="Look a doggo!">
+        <img
+        slot="top"
+        class="h-[256] w-full object-cover"
+        src="/pages/public/unocssmusical.jpeg"
+        alt="AI-generated picture of a band in colourful setup"
+        >
+    </w-modal-header>
+    <div slot="content">
+        <p>I bomb atomically, Socrates' philosophies and hypotheses...</p>
+    </div>
+    <w-modal-footer slot="footer">
+        <w-button variant="primary" id="modal-close-button-two">OK</w-button>
+    </w-modal-footer>
+</w-modal>
+```
+
+</elements-example>

package/dist/docs/modal/modal.md

@@ -0,0 +1,240 @@
+# Modal (w-modal)
+
+## Description
+
+Modals (or dialogs) display important information that users need to acknowledge.
+
+## Usage
+
+To creat a modal you need three different components:
+
+- `<w-modal>` - the parent component.
+- `<w-modal-header>` - for the title and close button.
+- `<w-modal-footer>` - for the actions such as Cancel and Confirm.
+
+### JavaScript API
+
+To open and close the modal using JavaScript, get a reference to the `<w-modal>` and call `open()` and `close()` respectively.
+
+
+<elements-example>
+
+```html
+<w-button data-testid="js-example-show" aria-haspopup="dialog">Show me some lyrics</w-button>
+<w-modal data-testid="js-example-modal">
+    <w-modal-header slot="header" title="Triumph by Wu Tang Clan"></w-modal-header>
+    <div slot="content">
+        <p>
+        My beats travel like a vortex through your spine, to the top of your
+        cerebral cortex. The rebel, I make more noise than heavy metal. Now,
+        lo and behold, another deadly episode, bound to catch another charge
+        when I explode Perpendicular to the square we stay in gold like
+        Flair, escape from your dragon's lair in particular. Handcuffed in
+        the back of a bus, forty of us. Slammin a hype verse til ya head
+        burst. Handcuffed in the back of a bus, forty of us. I bomb
+        atomically Socrates' philosophies and hypothesis can't define how I
+        be dropping these mockeries. I be that insane one from the psycho
+        ward, I'm on the trigger, plus I got the Wu-Tang sword. Step through
+        your section with the Force like Luke Skywalker, rhyme author,
+        orchestrate mind torture.
+        </p>
+    </div>
+    <w-modal-footer slot="footer">
+        <div class="flex gap-16">
+            <w-button variant="secondary" data-testid="js-example-cancel">Cancel</w-button>
+            <w-button variant="primary" data-testid="js-example-confirm">Confirm</w-button>
+        </div>
+    </w-modal-footer>
+</w-modal>
+
+<script>
+const modal = document.querySelector('w-modal[data-testid="js-example-modal"]');
+
+const openButton = document.querySelector('w-button[data-testid="js-example-show"]');
+const confirmButton = document.querySelector('w-button[data-testid="js-example-confirm"]');
+const cancelButton = document.querySelector('w-button[data-testid="js-example-cancel"]');
+
+openButton.addEventListener('click', () => modal.open());
+confirmButton.addEventListener('click', () => modal.close());
+cancelButton.addEventListener('click', () => modal.close());
+</script>
+```
+
+</elements-example>
+
+### Invoker Commands
+
+In [supported browsers](https://caniuse.com/?search=commandfor) (or [if you include the polyfill](https://github.com/keithamus/invokers-polyfill)) you can use the [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API) to potentially skip JavaScript alltogether.
+
+The available commands for `<w-modal>` are:
+
+- `--show-modal`
+- `--close`
+- `--confirm`
+
+<elements-example>
+
+```html
+<w-button commandfor="invoker-modal" command="--show-modal" aria-haspopup="dialog">Show me some lyrics</w-button>
+<w-modal id="invoker-modal">
+    <w-modal-header slot="header" title="Triumph by Wu Tang Clan"></w-modal-header>
+    <div slot="content">
+        <p>
+        First I'm gonna getcha, once I gotcha, I gat-cha, You could never
+        capture the Method Man's stature. So uhh, tic toc and keep ticking,
+        while I get you flipping off what I'm kicking. Yes, the rhythm, the
+        rebel, alone in my level heat it up past the boiling point of metal.
+        Shackling the masses with drastic rap tactics, graphic displays melt
+        the steel like blacksmiths. My beats travel like a vortex through
+        your spine, to the top of your cerebral cortex. Yes, the rhythm, the
+        rebel, alone in my level heat it up past the boiling point of metal.
+        Small change, they putting shame in the game. Murderous material,
+        made by a madman, it's the mic wrecker, Inspector, bad man.
+        </p>
+    </div>
+    <w-modal-footer slot="footer">
+        <div class="flex gap-16">
+            <w-button variant="secondary" commandfor="invoker-modal" command="--close">Dope</w-button>
+            <w-button variant="primary" commandfor="invoker-modal" command="--confirm">Dope</w-button>
+        </div>
+    </w-modal-footer>
+</w-modal>
+```
+
+</elements-example>
+
+Since `--confirm` and `--cancel` both close the modal, but mean different things, listen for the `command` event on `w-modal` to do stuff on the `--confirm` event, such as submit a response to an API. You can listen for the other commands as well (including `--show-modal`) if you need to add tracking events for example.
+
+```ts
+const modal = document.querySelector('w-modal');
+
+modal.addEventListener('command', function (event: CommandEvent) {
+    if (event.command === '--confirm') {
+        console.log("Doing stuff!");
+    }
+});
+```
+
+## Accessibility
+
+## Examples
+
+
+
+### With a titlebar
+
+<elements-example>
+
+```html
+<div>
+  <w-button aria-haspopup='dialog'>
+    Open a modal
+  </w-button>
+  <w-modal>
+    <w-modal-header
+      slot='header'
+      title='An example modal'
+    ></w-modal-header>
+    <div slot='content'>
+      <w-button variant='utility' small>
+        Toggle back button
+      </w-button>
+      <p>
+        I bomb atomically, Socrates' philosophies and hypotheses...
+      </p>
+      <p>
+        First I'm gonna getcha, once I gotcha, I gat-cha...
+      </p>
+    </div>
+    <w-modal-footer slot='footer'>
+      <w-button variant='primary'>
+        OK
+      </w-button>
+    </w-modal-footer>
+  </w-modal>
+</div>
+```
+
+</elements-example>
+
+### With an image at the top
+
+<elements-example>
+
+```html
+<w-button aria-haspopup="dialog" commandfor="my-modal" command="show-modal">
+    Open a modal
+</w-button>
+<w-modal id="my-modal">
+    <w-modal-header slot="header" title="Look a doggo!">
+        <img
+        slot="top"
+        class="h-[256] w-full object-cover"
+        src="/pages/public/unocssmusical.jpeg"
+        alt="AI-generated picture of a band in colourful setup"
+        >
+    </w-modal-header>
+    <div slot="content">
+        <p>I bomb atomically, Socrates' philosophies and hypotheses...</p>
+    </div>
+    <w-modal-footer slot="footer">
+        <w-button variant="primary" id="modal-close-button-two">OK</w-button>
+    </w-modal-footer>
+</w-modal>
+```
+
+</elements-example>
+
+## Styling API
+
+## `<w-modal>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| content-id | `string` | `-` | - |
+| ignore-backdrop-clicks | `boolean` | `false` | Ignores clicks to the backdrop when set |
+| show | `boolean` | `false` | Controls if the modal should show or hide. |
+
+### Property Details
+
+#### content-id
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### ignore-backdrop-clicks
+
+Ignores clicks to the backdrop when set
+
+- Type: `boolean`
+- Default: `false`
+
+#### show
+
+Controls if the modal should show or hide.
+
+You can also call the `open()` and `close()` methods.
+
+- Type: `boolean`
+- Default: `false`
+
+### Events
+
+#### hidden
+
+
+
+- Type: `CustomEvent`
+#### shown
+
+
+
+- Type: `CustomEvent`
+
+

package/dist/docs/modal/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/modal/usage.md

@@ -0,0 +1,110 @@
+## Usage
+
+To creat a modal you need three different components:
+
+- `<w-modal>` - the parent component.
+- `<w-modal-header>` - for the title and close button.
+- `<w-modal-footer>` - for the actions such as Cancel and Confirm.
+
+### JavaScript API
+
+To open and close the modal using JavaScript, get a reference to the `<w-modal>` and call `open()` and `close()` respectively.
+
+
+<elements-example>
+
+```html
+<w-button data-testid="js-example-show" aria-haspopup="dialog">Show me some lyrics</w-button>
+<w-modal data-testid="js-example-modal">
+    <w-modal-header slot="header" title="Triumph by Wu Tang Clan"></w-modal-header>
+    <div slot="content">
+        <p>
+        My beats travel like a vortex through your spine, to the top of your
+        cerebral cortex. The rebel, I make more noise than heavy metal. Now,
+        lo and behold, another deadly episode, bound to catch another charge
+        when I explode Perpendicular to the square we stay in gold like
+        Flair, escape from your dragon's lair in particular. Handcuffed in
+        the back of a bus, forty of us. Slammin a hype verse til ya head
+        burst. Handcuffed in the back of a bus, forty of us. I bomb
+        atomically Socrates' philosophies and hypothesis can't define how I
+        be dropping these mockeries. I be that insane one from the psycho
+        ward, I'm on the trigger, plus I got the Wu-Tang sword. Step through
+        your section with the Force like Luke Skywalker, rhyme author,
+        orchestrate mind torture.
+        </p>
+    </div>
+    <w-modal-footer slot="footer">
+        <div class="flex gap-16">
+            <w-button variant="secondary" data-testid="js-example-cancel">Cancel</w-button>
+            <w-button variant="primary" data-testid="js-example-confirm">Confirm</w-button>
+        </div>
+    </w-modal-footer>
+</w-modal>
+
+<script>
+const modal = document.querySelector('w-modal[data-testid="js-example-modal"]');
+
+const openButton = document.querySelector('w-button[data-testid="js-example-show"]');
+const confirmButton = document.querySelector('w-button[data-testid="js-example-confirm"]');
+const cancelButton = document.querySelector('w-button[data-testid="js-example-cancel"]');
+
+openButton.addEventListener('click', () => modal.open());
+confirmButton.addEventListener('click', () => modal.close());
+cancelButton.addEventListener('click', () => modal.close());
+</script>
+```
+
+</elements-example>
+
+### Invoker Commands
+
+In [supported browsers](https://caniuse.com/?search=commandfor) (or [if you include the polyfill](https://github.com/keithamus/invokers-polyfill)) you can use the [Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API) to potentially skip JavaScript alltogether.
+
+The available commands for `<w-modal>` are:
+
+- `--show-modal`
+- `--close`
+- `--confirm`
+
+<elements-example>
+
+```html
+<w-button commandfor="invoker-modal" command="--show-modal" aria-haspopup="dialog">Show me some lyrics</w-button>
+<w-modal id="invoker-modal">
+    <w-modal-header slot="header" title="Triumph by Wu Tang Clan"></w-modal-header>
+    <div slot="content">
+        <p>
+        First I'm gonna getcha, once I gotcha, I gat-cha, You could never
+        capture the Method Man's stature. So uhh, tic toc and keep ticking,
+        while I get you flipping off what I'm kicking. Yes, the rhythm, the
+        rebel, alone in my level heat it up past the boiling point of metal.
+        Shackling the masses with drastic rap tactics, graphic displays melt
+        the steel like blacksmiths. My beats travel like a vortex through
+        your spine, to the top of your cerebral cortex. Yes, the rhythm, the
+        rebel, alone in my level heat it up past the boiling point of metal.
+        Small change, they putting shame in the game. Murderous material,
+        made by a madman, it's the mic wrecker, Inspector, bad man.
+        </p>
+    </div>
+    <w-modal-footer slot="footer">
+        <div class="flex gap-16">
+            <w-button variant="secondary" commandfor="invoker-modal" command="--close">Dope</w-button>
+            <w-button variant="primary" commandfor="invoker-modal" command="--confirm">Dope</w-button>
+        </div>
+    </w-modal-footer>
+</w-modal>
+```
+
+</elements-example>
+
+Since `--confirm` and `--cancel` both close the modal, but mean different things, listen for the `command` event on `w-modal` to do stuff on the `--confirm` event, such as submit a response to an API. You can listen for the other commands as well (including `--show-modal`) if you need to add tracking events for example.
+
+```ts
+const modal = document.querySelector('w-modal');
+
+modal.addEventListener('command', function (event: CommandEvent) {
+    if (event.command === '--confirm') {
+        console.log("Doing stuff!");
+    }
+});
+```