@kubex/zinc 0.0.2 → 1.0.0

package/docs/pages/components/tooltip.md

@@ -0,0 +1,242 @@
+---
+meta:
+  title: Tooltip
+  description: Tooltips display additional information based on a specific action.
+layout: component
+guidelines: |
+  ### Tooltip Basics
+  - Tooltips are for supplemental content
+  - Keep tooltip content simple — ideally with just one or two words or a short phrase
+
+  ### Tooltip Don'ts
+  - **Don't** put essential information in a tooltip
+  - **Don't** put interactive elements like buttons and links in a tooltip
+  - **Don't** include elements like images in a tooltip
+
+  ### When to Use a Tooltip
+  - Use to provide brief supplemental (but not essential) information on hover
+    - For example, a trash icon with the word "Delete" in a tooltip, to reinforce the purpose of the icon
+    - Or a disabled "Submit" button with the words "Complete required fields" in a tooltip, to remind people why the button is disabled
+
+  ### When to Use Something Else
+  - If the supplemental information requires the use of imagery, links, or other interactions, consider a [Popup](/components/popup) or [Drawer](/components/drawer)
+---
+
+## Examples
+
+### Basic Tooltip
+
+Tooltips appear when a user hovers or focuses an element. They provide contextual information about the element they are paired with.
+
+A tooltip's target is its _first child element_, so you should only wrap one element inside of the tooltip. If you need the tooltip to show up for multiple elements, nest them inside a container first.
+
+Tooltips use `display: contents` so they won't interfere with how elements are positioned in a flex or grid layout.
+
+```html:preview
+<zn-tooltip content="This is a tooltip">
+  <zn-button>Hover Me</zn-button>
+</zn-tooltip>
+```
+
+### Placement
+
+Use the `placement` attribute to set the preferred placement of the tooltip.
+
+:::tip
+**Note:** The default placement of tooltips in our Design System is `top`.
+:::
+
+```html:preview
+<div class="tooltip-placement-example">
+  <div class="tooltip-placement-example-row">
+    <zn-tooltip content="top-start" placement="top-start">
+      <zn-button></zn-button>
+    </zn-tooltip>
+
+    <zn-tooltip content="top" placement="top">
+      <zn-button></zn-button>
+    </zn-tooltip>
+
+    <zn-tooltip content="top-end" placement="top-end">
+      <zn-button></zn-button>
+    </zn-tooltip>
+  </div>
+
+  <div class="tooltip-placement-example-row">
+    <zn-tooltip content="left-start" placement="left-start">
+      <zn-button></zn-button>
+    </zn-tooltip>
+
+    <zn-tooltip content="right-start" placement="right-start">
+      <zn-button></zn-button>
+    </zn-tooltip>
+  </div>
+
+  <div class="tooltip-placement-example-row">
+    <zn-tooltip content="left" placement="left">
+      <zn-button></zn-button>
+    </zn-tooltip>
+
+    <zn-tooltip content="right" placement="right">
+      <zn-button></zn-button>
+    </zn-tooltip>
+  </div>
+
+  <div class="tooltip-placement-example-row">
+    <zn-tooltip content="left-end" placement="left-end">
+      <zn-button></zn-button>
+    </zn-tooltip>
+
+    <zn-tooltip content="right-end" placement="right-end">
+      <zn-button></zn-button>
+    </zn-tooltip>
+  </div>
+
+  <div class="tooltip-placement-example-row">
+    <zn-tooltip content="bottom-start" placement="bottom-start">
+      <zn-button></zn-button>
+    </zn-tooltip>
+
+    <zn-tooltip content="bottom" placement="bottom">
+      <zn-button></zn-button>
+    </zn-tooltip>
+
+    <zn-tooltip content="bottom-end" placement="bottom-end">
+      <zn-button></zn-button>
+    </zn-tooltip>
+  </div>
+</div>
+
+<style>
+  .tooltip-placement-example {
+    width: 250px;
+    margin: 1rem;
+  }
+
+  .tooltip-placement-example-row:after {
+    content: '';
+    display: table;
+    clear: both;
+  }
+
+  .tooltip-placement-example zn-button {
+    float: left;
+    width: 2.5rem;
+    margin-right: 0.25rem;
+    margin-bottom: 0.25rem;
+  }
+
+  .tooltip-placement-example-row:nth-child(1) zn-tooltip:first-child zn-button,
+  .tooltip-placement-example-row:nth-child(5) zn-tooltip:first-child zn-button {
+    margin-left: calc(40px + 0.25rem);
+  }
+
+  .tooltip-placement-example-row:nth-child(2) zn-tooltip:nth-child(2) zn-button,
+  .tooltip-placement-example-row:nth-child(3) zn-tooltip:nth-child(2) zn-button,
+  .tooltip-placement-example-row:nth-child(4) zn-tooltip:nth-child(2) zn-button {
+    margin-left: calc((40px * 3) + (0.25rem * 3));
+  }
+</style>
+```
+
+### Click Trigger
+
+Set the `trigger` attribute to `click` to toggle the tooltip on click instead of hover.
+
+```html:preview
+<zn-tooltip content="Click again to dismiss" trigger="click">
+  <zn-button>Click to Toggle</zn-button>
+</zn-tooltip>
+```
+
+### Manual Trigger
+
+Tooltips can be controlled programmatically by setting the `trigger` attribute to `manual`. Use the `open` attribute to control when the tooltip is shown.
+
+```html:preview
+<zn-button style="margin-right: 4rem;">Toggle Manually</zn-button>
+
+<zn-tooltip content="This is an avatar" trigger="manual" class="manual-tooltip">
+  <zn-avatar label="User"></zn-avatar>
+</zn-tooltip>
+
+<script>
+  const tooltip = document.querySelector('.manual-tooltip');
+  const toggle = tooltip.previousElementSibling;
+
+  toggle.addEventListener('click', () => (tooltip.open = !tooltip.open));
+</script>
+```
+
+### Removing Arrows
+
+You can control the size of tooltip arrows by overriding the `--zn-tooltip-arrow-size` design token. To remove them, set the value to `0` as shown below.
+
+:::warning
+**Note:** Tooltips without arrows are not the standard tooltip pattern in our Design System.
+:::
+
+```html:preview
+<zn-tooltip content="This is a tooltip" style="--zn-tooltip-arrow-size: 0;">
+  <zn-button>No Arrow</zn-button>
+</zn-tooltip>
+```
+
+<!-- To override it globally, set it in a root block in your stylesheet after the Shoelace stylesheet is loaded.
+
+```css
+:root {
+  --zn-tooltip-arrow-size: 0;
+}
+``` -->
+
+### HTML in Tooltips
+
+Use the `content` slot to create tooltips with HTML content. Tooltips are designed only for text and presentational elements. Avoid placing interactive content, such as buttons, links, and form controls, in a tooltip.
+
+```html:preview
+<zn-tooltip>
+  <div slot="content">I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!</div>
+
+  <zn-button>Hover me</zn-button>
+</zn-tooltip>
+```
+
+### Setting a Maximum Width
+
+Use the `--max-width` custom property to change the width the tooltip can grow to before wrapping occurs.
+
+:::warning
+**Note:** The default `max-width` for Design System tooltips is 240px (15rem). Please check with the design team before using this option to override this `max-width` setting.
+:::
+
+```html:preview
+<zn-tooltip style="--max-width: 80px;" content="This tooltip will wrap after only 80 pixels.">
+  <zn-button>Hover me</zn-button>
+</zn-tooltip>
+```
+
+### Hoisting
+
+Tooltips will be clipped if they're inside a container that has `overflow: auto|hidden|scroll`. The `hoist` attribute forces the tooltip to use a fixed positioning strategy, allowing it to break out of the container. In this case, the tooltip will be positioned relative to its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
+
+```html:preview
+<div class="tooltip-hoist">
+  <zn-tooltip content="This is a tooltip">
+    <zn-button>No Hoist</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="This is a tooltip" hoist>
+    <zn-button>Hoist</zn-button>
+  </zn-tooltip>
+</div>
+
+<style>
+  .tooltip-hoist {
+    position: relative;
+    border: solid 2px var(--zn-panel-border-color);
+    overflow: hidden;
+    padding: var(--zn-spacing-medium);
+  }
+</style>
+```

package/docs/pages/components/vertical-stepper.md

@@ -0,0 +1,22 @@
+---
+meta:
+  title: Vertical Stepper
+  description:
+layout: component
+---
+
+```html:preview
+<zn-vertical-stepper caption="Something" description="This is the description" first active></zn-vertical-stepper>
+<zn-vertical-stepper caption="Something" description="This is the description" active></zn-vertical-stepper>
+<zn-vertical-stepper caption="Something" description="This is the description" last></zn-vertical-stepper>
+```
+
+## Examples
+
+### First Example
+
+TODO
+
+### Second Example
+
+TODO

package/docs/pages/components/well.md

@@ -0,0 +1,13 @@
+---
+meta:
+  title: Well
+  description:
+layout: component
+---
+
+```html:preview
+<div>
+<zn-well icon="calendar_month">Triggers every <strong>5 minutes</strong></zn-well>
+<zn-well inline icon="calendar_month">Triggers every <strong>5 minutes</strong></zn-well>
+</div>
+```

package/docs/pages/getting-started/example-layout.md

@@ -0,0 +1,143 @@
+---
+meta:
+  title: Example Layout
+  description: This is an example layout using the new components
+fullWidth: true
+---
+
+# Expanded Example
+
+Most pages should be scaffolded in the following way. This layout is designed to be responsive and to work well on all
+devices. It is also designed to be easy to read and understand.
+
+`zn-sp` allows you to add space between elements. It is a shorthand for `zn-space`. It is a flex container that has a
+default gap of `--zn-spacing-medium`. by specifying `no-gap` you can remove the gap between elements. So that if the
+component you are using already includes padding or margin it will not be doubled up.
+
+```html:preview
+
+<zn-pane>
+  <zn-sp flush>
+    <zn-cols layout="1,1">
+      <zn-panel caption="Some Panel" description="Hello World">
+        <zn-sp divide no-gap>
+          <zn-item label="Full name">
+            <zn-inline-edit name="name" value="Margot Foster"></zn-inline-edit>
+          </zn-item>
+          <zn-item label="Full name">
+            Something
+            <zn-button icon="add" color="secondary" size="x-small" slot="actions" icon-size="20"></zn-button>
+          </zn-item>
+          <zn-item label="Full name">
+            Something
+            <zn-button color="transparent" size="x-small" slot="actions">Update</zn-button>
+          </zn-item>
+          <zn-item label="Selet Option">
+            <zn-inline-edit name="name" value="1"
+                            options="{&quot;1&quot;: &quot;Option 1&quot;,&quot;2&quot;: &quot;Option 2&quot;}"></zn-inline-edit>
+          </zn-item>
+        </zn-sp>
+      </zn-panel>
+
+      <zn-panel caption="Some Panel">
+        <zn-sp divide>
+          <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 1"
+                          value="This is awesome">
+          </zn-inline-edit>
+          <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 2"
+                          value="This is awesome">
+          </zn-inline-edit>
+        </zn-sp>
+      </zn-panel>
+    </zn-cols>
+
+    <zn-panel caption="Some Panel" tabbed>
+      <zn-tabs>
+        <zn-navbar slot="top">
+          <li tab>Customer</li>
+          <li tab="something-else">Something Else</li>
+        </zn-navbar>
+
+        <zn-sp id="" divide>
+          <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 1"
+                          value="This is awesome"></zn-inline-edit>
+          <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 2"
+                          value="This is awesome"></zn-inline-edit>
+        </zn-sp>
+
+        <zn-sp id="something-else" divide>
+          <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 3"
+                          value="This is not awesome">
+          </zn-inline-edit>
+          <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 4"
+                          value="This is not awesome">
+          </zn-inline-edit>
+        </zn-sp>
+      </zn-tabs>
+    </zn-panel>
+
+    <zn-panel caption="Some Panel">
+      <zn-sp divide>
+        <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 1"
+                        value="This is awesome"></zn-inline-edit>
+        <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 2"
+                        value="This is awesome"></zn-inline-edit>
+      </zn-sp>
+    </zn-panel>
+  </zn-sp>
+</zn-pane>
+```
+
+### Simple Panel Example
+
+Using `flush` on the panel allows you to remove all padding around the content, this is great for tables that you want
+to be full width.
+
+```html:preview
+
+<zn-container padded>
+  <zn-sp>
+    <zn-panel caption="Some Panel" flush>
+      <zn-sp divide flush>
+        <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 1" value=This is awesome></zn-inline-edit>
+        <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 2" value=This is awesome></zn-inline-edit>
+      </zn-sp>
+    </zn-panel>
+  </zn-sp>
+</zn-container>
+```
+
+
+### Sidebar Layout Example
+
+This is the standard way of scaffolding pages with a sidebar
+
+```html:preview
+
+<zn-sidebar>
+
+  <div slot="side">
+    <zn-sp divide flush>
+      <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 1" value="This is awesome">
+      </zn-inline-edit>
+      <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 2" value="This is awesome">
+      </zn-inline-edit>
+    </zn-sp>
+  </div>
+
+  <zn-container padded style="background: var(--zn-color-neutral-50);">
+    <zn-sp>
+      <zn-panel caption="Some Panel" flush>
+        <zn-sp divide flush>
+          <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 1" value="This is awesome">
+          </zn-inline-edit>
+          <zn-inline-edit padded inline style="background: var(--zn-color-red-100);" caption="Label 2" value="This is awesome">
+          </zn-inline-edit>
+        </zn-sp>
+      </zn-panel>
+    </zn-sp>
+  </zn-container>
+
+</zn-sidebar>
+
+```

package/docs/pages/getting-started/example-page.md

@@ -0,0 +1,83 @@
+---
+meta:
+  title: Example Page
+  description: An example of a full page in zinc with use of multiple nested tabs, in case you need to show multiple views of data.
+fullWidth: true
+---
+
+# Example Page
+
+An example of a full page in zinc with use of multiple nested tabs, in case you need to show multiple views of data.
+
+We have a primary set of tabs which uses just the `zn-navbar` component to show the navigation, and then a secondary
+set of tabs which uses the `zn-header` component to show the navigation in a more detailed way.
+
+:::tip
+**Note:** This is subject to change as defining the navigation and dropdown as attributes is not ideal, especially
+for SEO purposes. We should be slotting everything in as children of the components.
+:::
+
+```html:preview
+
+<style>
+  .code-preview__preview {
+    background-color: rgb(var(--zn-body)) !important;
+    padding: 0 25px 0 0;
+  }
+</style>
+
+<zn-tabs flush primary-caption="Navigation" secondary-caption="content">
+
+  <!-- This is the navigation for the first set of tabs -->
+  <zn-navbar slot="top"
+             highlight
+             navigation="[{&quot;title&quot;:&quot;John Doe&quot;,&quot;active&quot;:false,&quot;hintText&quot;:&quot;Overview&quot;,&quot;launchMode&quot;:&quot;page&quot;}]"
+             dropdown="[{&quot;tab&quot;:&quot;2&quot;,&quot;title&quot;:&quot;Some Actions&quot;,&quot;type&quot;:&quot;dropdown&quot;}]">
+  </zn-navbar>
+
+  <!-- This is the content of the first tab / default -->
+  <zn-tabs flush primary-caption="Navigation" secondary-caption="Content">
+
+    <!-- This is the Navigation/Header for the Inner set of tabs -->
+    <zn-header slot="top"
+               caption="Customer"
+               description="My Awesome Customer"
+               navigation="[{&quot;title&quot;:&quot;Overview&quot;}, {&quot;title&quot;:&quot;Details&quot;, &quot;tab&quot;:&quot;details&quot;}]">
+    </zn-header>
+
+    <!--This is the content of the first tab / default inside the first tab -->
+    <div>
+      <!-- This is where your page content would be defined -->
+      <zn-sp>
+        <zn-panel caption="Something">Data Points</zn-panel>
+        <zn-panel caption="Another Thing">Other Points</zn-panel>
+      </zn-sp>
+    </div>
+
+    <!--This is the content of the second tab inside the first tab -->
+    <div id="details">
+      <!-- This is where your page content would be defined -->
+      <zn-sp>
+        <zn-panel caption="Awesome">this is an example of the details tab</zn-panel>
+      </zn-sp>
+    </div>
+  </zn-tabs>
+
+  <!-- This is the content of the second tab -->
+  <div id="2">
+    <zn-pane>
+      <zn-header slot="top"
+                 caption="Customer"
+                 description="My Awesome Customer"
+                 navigation="[{&quot;title&quot;:&quot;Overview&quot;}, {&quot;title&quot;:&quot;Details&quot;, &quot;tab&quot;:&quot;details&quot;}]">
+      </zn-header>
+      <!-- This is where your page content would be defined -->
+      <zn-sp> <!-- Maybe zn-sp should be defaulted into the content? -->
+        <zn-panel caption="Number 2">Something Something Darkside</zn-panel>
+      </zn-sp>
+    </zn-pane>
+  </div>
+
+</zn-tabs>
+
+```