terra_ui_components 0.0.112__tar.gz → 0.0.118__tar.gz

{terra_ui_components-0.0.112 → terra_ui_components-0.0.118}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: terra_ui_components
-Version: 0.0.112
+Version: 0.0.118
 Summary: NASA Terra UI Components Library
 License-File: LICENSE.md
 Requires-Python: >=3.8

{terra_ui_components-0.0.112 → terra_ui_components-0.0.118}/docs/_includes/default.njk

@@ -136,17 +136,6 @@
                 <a href="https://github.com/nasa/terra-ui-components" title="View Terra UI Components on GitHub" class="top-nav__icon-link">
                     <sl-icon name="github"></sl-icon>
                 </a>
-                <!--
-                <terra-dropdown id="environment-selector" placement="bottom-end" distance="3" hover>
-                    <terra-button slot="trigger" size="medium" variant="text" caret="" title="Environment" data-optional="" data-valid="" data-user-valid="">
-                        <span id="environment-display">UAT</span>
-                    </terra-button>
-                    <terra-menu role="menu">
-                        <terra-menu-item type="checkbox" value="uat" tabindex="-1" role="menuitemcheckbox" aria-checked="true" aria-disabled="false" checked="">UAT</terra-menu-item>
-                        <terra-menu-item type="checkbox" value="prod" tabindex="-1" role="menuitemcheckbox" aria-checked="false" aria-disabled="false">PROD</terra-menu-item>
-                    </terra-menu>
-                </terra-dropdown>
-                -->
                 <terra-dropdown id="theme-selector" placement="bottom-end" distance="3" hover>
                     <terra-button slot="trigger" size="medium" variant="text" caret="" title="Press \ to toggle" data-optional="" data-valid="" data-user-valid="">
                         <sl-icon class="only-light" name="sun-fill" aria-hidden="true" library="default"></sl-icon>

{terra_ui_components-0.0.112 → terra_ui_components-0.0.118}/docs/eleventy.config.cjs

@@ -51,10 +51,13 @@ module.exports = function (eleventyConfig) {
     allComponents.forEach(component => {
         // Get section from markdown front matter, default to "Components"
         const section = componentSectionMap[component.tagName] || 'Components'
-        if (!componentsBySection[section]) {
-            componentsBySection[section] = []
+
+        if (section !== 'Hidden') {
+            if (!componentsBySection[section]) {
+                componentsBySection[section] = []
+            }
+            componentsBySection[section].push(component)
         }
-        componentsBySection[section].push(component)
     })
 
     // Sort components within each section

terra_ui_components-0.0.118/docs/pages/components/breadcrumb.md

@@ -0,0 +1,31 @@
+---
+meta:
+    title: Breadcrumb
+    description: A single breadcrumb item used inside `terra-breadcrumbs`.
+layout: component
+sidebarSection: Hidden
+---
+
+```html:preview
+<terra-breadcrumb current>Current page</terra-breadcrumb>
+```
+
+## Examples
+
+### Link vs. current page
+
+Use `href` for navigable ancestors in the path and set `current` on the last breadcrumb to indicate the current page.
+
+```html:preview
+<terra-breadcrumbs>
+    <terra-breadcrumb href="/">Home</terra-breadcrumb>
+    <terra-breadcrumb href="/section">Section</terra-breadcrumb>
+    <terra-breadcrumb current>Current page</terra-breadcrumb>
+</terra-breadcrumbs>
+```
+
+When `current` is set, the underlying element will receive `aria-current="page"` for accessibility.
+
+For accessibility, your app should always set `current` on exactly one breadcrumb in each `terra-breadcrumbs` trail (typically the last one). Leaving out `current` will still render visually, but assistive technologies won’t know which page in the trail is active.
+
+[component-metadata:terra-breadcrumb]

terra_ui_components-0.0.118/docs/pages/components/breadcrumbs.md

@@ -0,0 +1,52 @@
+---
+meta:
+    title: Breadcrumbs
+    description: Breadcrumbs show visitors where the current page sits in the site hierarchy and let them navigate back to higher-level pages.
+layout: component
+---
+
+```html:preview
+<terra-breadcrumbs>
+    <terra-breadcrumb href="/">Home</terra-breadcrumb>
+    <terra-breadcrumb href="/section">Section</terra-breadcrumb>
+    <terra-breadcrumb current>Current page</terra-breadcrumb>
+</terra-breadcrumbs>
+```
+
+## Examples
+
+### Basic breadcrumbs
+
+Use `terra-breadcrumbs` with one or more `terra-breadcrumb` items to show the path to the current page.
+
+```html:preview
+<terra-breadcrumbs>
+    <terra-breadcrumb href="/">Home</terra-breadcrumb>
+    <terra-breadcrumb href="/missions">Missions</terra-breadcrumb>
+    <terra-breadcrumb current>Artemis</terra-breadcrumb>
+</terra-breadcrumbs>
+```
+
+Always mark the last breadcrumb as current in your app:
+
+-   This ensures the current page is styled correctly.
+-   It also applies `aria-current="page"` to the active breadcrumb for screen readers. Omitting `current` means assistive technologies can’t reliably identify the current location.
+
+### With longer hierarchies
+
+Breadcrumbs should not display more than three levels of hierarchy. For deeper pages, replace the earlier levels with an ellipsis breadcrumb that you manage in your application.
+
+```html:preview
+<terra-breadcrumbs style="--terra-breadcrumbs-separator: '/';">
+    <terra-breadcrumb>...</terra-breadcrumb>
+    <terra-breadcrumb href="/missions">Missions</terra-breadcrumb>
+    <terra-breadcrumb current>Artemis</terra-breadcrumb>
+</terra-breadcrumbs>
+```
+
+In this example, your application is responsible for:
+
+-   **Truncation logic**: choosing when to show the `...` breadcrumb and which levels to omit.
+-   **Current page**: setting `current` on the last breadcrumb, which applies `aria-current="page"` for accessibility.
+
+[component-metadata:terra-breadcrumbs]

{terra_ui_components-0.0.112 → terra_ui_components-0.0.118}/docs/pages/components/data-subsetter.md

@@ -11,9 +11,7 @@ The `<terra-data-subsetter>` component provides a complete UI for subsetting and
 
 ```html:preview
 <div style="height: 200px;">
-    <terra-dialog id="my-dialog" width="80%">
-        <terra-data-subsetter collection-entry-id="OMAERO_003"></terra-data-subsetter>
-    </terra-dialog>
+    <terra-data-subsetter collection-entry-id="OMAERO_003" dialog="my-dialog"></terra-data-subsetter>
     <terra-button for-dialog="my-dialog">
         Open Subsetter
     </terra-button>
@@ -60,13 +58,13 @@ The `<terra-data-subsetter>` component provides a complete UI for subsetting and
 
 ```html:preview
 <div style="height: 200px;">
-    <terra-dialog id="my-dialog">
-        <terra-data-subsetter collection-entry-id="OMAERO_003"></terra-data-subsetter>
-    </terra-dialog>
+    <terra-data-subsetter collection-entry-id="OMAERO_003" dialog="my-dialog"></terra-data-subsetter>
     <terra-button for-dialog="my-dialog">
         Open Subsetter
     </terra-button>
 </div>
+
+
 ```
 
 ## Best Practices

terra_ui_components-0.0.118/docs/pages/components/dialog.md

@@ -0,0 +1,329 @@
+---
+meta:
+    title: Dialog
+    description: 'Dialogs, sometimes called "modals", appear above the page and require the user''s immediate attention.'
+layout: component
+---
+
+<!-- cspell:dictionaries lorem-ipsum -->
+
+```html:preview
+<terra-dialog label="Dialog" class="dialog-overview">
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <terra-button slot="footer" variant="primary">Close</terra-button>
+</terra-dialog>
+
+<terra-button>Open Dialog</terra-button>
+
+<script>
+  const dialog = document.querySelector('.dialog-overview');
+  const openButton = dialog.nextElementSibling;
+  const closeButton = dialog.querySelector('terra-button[slot="footer"]');
+
+  openButton.addEventListener('click', () => dialog.show());
+  closeButton.addEventListener('click', () => dialog.hide());
+</script>
+```
+
+```jsx:react
+import { useState } from 'react';
+import TerraButton from '@nasa-terra/components/dist/react/button';
+import TerraDialog from '@nasa-terra/components/dist/react/dialog';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <TerraDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <TerraButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </TerraButton>
+      </TerraDialog>
+
+      <TerraButton onClick={() => setOpen(true)}>Open Dialog</TerraButton>
+    </>
+  );
+};
+```
+
+## Examples
+
+### Custom Width
+
+Use the `--width` custom property to set the dialog's width.
+
+```html:preview
+<terra-dialog label="Dialog" class="dialog-width" style="--width: 50vw;">
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <terra-button slot="footer" variant="primary">Close</terra-button>
+</terra-dialog>
+
+<terra-button>Open Dialog</terra-button>
+
+<script>
+  const dialog = document.querySelector('.dialog-width');
+  const openButton = dialog.nextElementSibling;
+  const closeButton = dialog.querySelector('terra-button[slot="footer"]');
+
+  openButton.addEventListener('click', () => dialog.show());
+  closeButton.addEventListener('click', () => dialog.hide());
+</script>
+```
+
+{% raw %}
+
+```jsx:react
+import { useState } from 'react';
+import TerraButton from '@nasa-terra/components/dist/react/button';
+import TerraDialog from '@nasa-terra/components/dist/react/dialog';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <TerraDialog label="Dialog" open={open} style={{ '--width': '50vw' }} onSlAfterHide={() => setOpen(false)}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <TerraButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </TerraButton>
+      </TerraDialog>
+
+      <TerraButton onClick={() => setOpen(true)}>Open Dialog</TerraButton>
+    </>
+  );
+};
+```
+
+{% endraw %}
+
+### Scrolling
+
+By design, a dialog's height will never exceed that of the viewport. As such, dialogs will not scroll with the page ensuring the header and footer are always accessible to the user.
+
+```html:preview
+<terra-dialog label="Dialog" class="dialog-scrolling">
+  <div style="height: 150vh; border: dashed 2px var(--terra-color-neutral-200); padding: 0 1rem;">
+    <p>Scroll down and give it a try! 👇</p>
+  </div>
+  <terra-button slot="footer" variant="primary">Close</terra-button>
+</terra-dialog>
+
+<terra-button>Open Dialog</terra-button>
+
+<script>
+  const dialog = document.querySelector('.dialog-scrolling');
+  const openButton = dialog.nextElementSibling;
+  const closeButton = dialog.querySelector('terra-button[slot="footer"]');
+
+  openButton.addEventListener('click', () => dialog.show());
+  closeButton.addEventListener('click', () => dialog.hide());
+</script>
+```
+
+{% raw %}
+
+```jsx:react
+import { useState } from 'react';
+import TerraButton from '@nasa-terra/components/dist/react/button';
+import TerraDialog from '@nasa-terra/components/dist/react/dialog';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <TerraDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        <div
+          style={{
+            height: '150vh',
+            border: 'dashed 2px var(--terra-color-neutral-200)',
+            padding: '0 1rem'
+          }}
+        >
+          <p>Scroll down and give it a try! 👇</p>
+        </div>
+
+        <TerraButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </TerraButton>
+      </TerraDialog>
+
+      <TerraButton onClick={() => setOpen(true)}>Open Dialog</TerraButton>
+    </>
+  );
+};
+```
+
+{% endraw %}
+
+### Header Actions
+
+The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
+
+```html:preview
+<terra-dialog label="Dialog" class="dialog-header-actions">
+  <terra-button class="new-window" slot="header-actions">Open</terra-button>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <terra-button slot="footer" variant="primary">Close</terra-button>
+</terra-dialog>
+
+<terra-button>Open Dialog</terra-button>
+
+<script>
+  const dialog = document.querySelector('.dialog-header-actions');
+  const openButton = dialog.nextElementSibling;
+  const closeButton = dialog.querySelector('terra-button[slot="footer"]');
+  const newWindowButton = dialog.querySelector('.new-window');
+
+  openButton.addEventListener('click', () => dialog.show());
+  closeButton.addEventListener('click', () => dialog.hide());
+  newWindowButton.addEventListener('click', () => window.open(location.href));
+</script>
+```
+
+```jsx:react
+import { useState } from 'react';
+import TerraButton from '@nasa-terra/components/dist/react/button';
+import TerraDialog from '@nasa-terra/components/dist/react/dialog';
+import SlIconButton from '@nasa-terra/components/dist/react/icon-button';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <TerraDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        <SlIconButton
+          class="new-window"
+          slot="header-actions"
+          name="box-arrow-up-right"
+          onClick={() => window.open(location.href)}
+        />
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <TerraButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </TerraButton>
+      </TerraDialog>
+
+      <TerraButton onClick={() => setOpen(true)}>Open Dialog</TerraButton>
+    </>
+  );
+};
+```
+
+### Preventing the Dialog from Closing
+
+By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the [[Escape]] key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
+
+To keep the dialog open in such cases, you can cancel the `terra-request-close` event. When canceled, the dialog will remain open and pulse briefly to draw the user's attention to it.
+
+You can use `event.detail.source` to determine what triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or [[Escape]] to dismiss it.
+
+```html:preview
+<terra-dialog label="Dialog" class="dialog-deny-close">
+  This dialog will not close when you click on the overlay.
+  <terra-button slot="footer" variant="primary">Close</terra-button>
+</terra-dialog>
+
+<terra-button>Open Dialog</terra-button>
+
+<script>
+  const dialog = document.querySelector('.dialog-deny-close');
+  const openButton = dialog.nextElementSibling;
+  const closeButton = dialog.querySelector('terra-button[slot="footer"]');
+
+  openButton.addEventListener('click', () => dialog.show());
+  closeButton.addEventListener('click', () => dialog.hide());
+
+  // Prevent the dialog from closing when the user clicks on the overlay
+  dialog.addEventListener('terra-request-close', event => {
+    if (event.detail.source === 'overlay') {
+      event.preventDefault();
+    }
+  });
+</script>
+```
+
+```jsx:react
+import { useState } from 'react';
+import TerraButton from '@nasa-terra/components/dist/react/button';
+import TerraDialog from '@nasa-terra/components/dist/react/dialog';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  // Prevent the dialog from closing when the user clicks on the overlay
+  function handleRequestClose(event) {
+    if (event.detail.source === 'overlay') {
+      event.preventDefault();
+    }
+  }
+
+  return (
+    <>
+      <TerraDialog label="Dialog" open={open} onSlRequestClose={handleRequestClose} onSlAfterHide={() => setOpen(false)}>
+        This dialog will not close when you click on the overlay.
+        <TerraButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </TerraButton>
+      </TerraDialog>
+
+      <TerraButton onClick={() => setOpen(true)}>Open Dialog</TerraButton>
+    </>
+  );
+};
+```
+
+### Customizing Initial Focus
+
+By default, the dialog's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the dialog. If you want a different element to have focus, add the `autofocus` attribute to it as shown below.
+
+```html:preview
+<terra-dialog label="Dialog" class="dialog-focus">
+  <terra-input autofocus placeholder="I will have focus when the dialog is opened"></terra-input>
+  <terra-button slot="footer" variant="primary">Close</terra-button>
+</terra-dialog>
+
+<terra-button>Open Dialog</terra-button>
+
+<script>
+  const dialog = document.querySelector('.dialog-focus');
+  const input = dialog.querySelector('terra-input');
+  const openButton = dialog.nextElementSibling;
+  const closeButton = dialog.querySelector('terra-button[slot="footer"]');
+
+  openButton.addEventListener('click', () => dialog.show());
+  closeButton.addEventListener('click', () => dialog.hide());
+</script>
+```
+
+```jsx:react
+import { useState } from 'react';
+import TerraButton from '@nasa-terra/components/dist/react/button';
+import TerraDialog from '@nasa-terra/components/dist/react/dialog';
+import TerraInput from '@nasa-terra/components/dist/react/input';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <TerraDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        <TerraInput autofocus placeholder="I will have focus when the dialog is opened" />
+        <TerraButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </TerraButton>
+      </TerraDialog>
+
+      <TerraButton onClick={() => setOpen(true)}>Open Dialog</TerraButton>
+    </>
+  );
+};
+```
+
+:::tip
+You can further customize initial focus behavior by canceling the `terra-initial-focus` event and setting focus yourself inside the event handler.
+:::

{terra_ui_components-0.0.112 → terra_ui_components-0.0.118}/docs/pages/components/menu-item.md

@@ -3,6 +3,7 @@ meta:
     title: Menu Item
     description: Menu items provide options for the user to pick from in a menu.
 layout: component
+sidebarSection: Hidden
 ---
 
 # Menu Item

{terra_ui_components-0.0.112 → terra_ui_components-0.0.118}/docs/pages/components/plot-toolbar.md

@@ -3,6 +3,7 @@ meta:
     title: Plot Toolbar
     description:
 layout: component
+sidebarSection: Hidden
 ---
 
 ```html:preview

{terra_ui_components-0.0.112 → terra_ui_components-0.0.118}/docs/pages/components/radio-group.md

@@ -3,7 +3,7 @@ meta:
     title: Radio Group
     description: Radio groups are used to group multiple radio buttons so they function as a single form control.
 layout: component
-sidebarSection: Elements
+sidebarSection: Hidden
 ---
 
 ```html:preview

terra_ui_components-0.0.118/docs/pages/components/site-header.md

@@ -0,0 +1,86 @@
+---
+meta:
+    title: Site Header
+    description: Site headers provide a consistent navigation structure at the top of pages.
+layout: component
+---
+
+```html:preview
+<terra-site-header site-name="Terra UI"></terra-site-header>
+```
+
+## Examples
+
+### Basic Header
+
+A basic header with just the site name.
+
+```html:preview
+<terra-site-header site-name="My Site"></terra-site-header>
+```
+
+### Header with Navigation
+
+A header with navigation in the center slot.
+
+```html:preview
+<terra-site-header site-name="Terra UI">
+    <terra-site-navigation slot="center">
+        <terra-dropdown placement="bottom-start" distance="3" hover>
+            <terra-button slot="trigger" size="medium" variant="text" caret>
+                Data
+            </terra-button>
+            <terra-menu role="menu">
+                <terra-menu-item value="catalog">
+                    <a href="#">Data Catalog</a>
+                </terra-menu-item>
+                <terra-menu-item value="alerts">
+                    <a href="#">Data Alerts</a>
+                </terra-menu-item>
+            </terra-menu>
+        </terra-dropdown>
+        <terra-dropdown placement="bottom-start" distance="3" hover>
+            <terra-button slot="trigger" size="medium" variant="text" caret>
+                Topics
+            </terra-button>
+            <terra-menu role="menu">
+                <terra-menu-item value="atmosphere">
+                    <a href="#">Atmosphere</a>
+                </terra-menu-item>
+                <terra-menu-item value="ocean">
+                    <a href="#">Ocean</a>
+                </terra-menu-item>
+            </terra-menu>
+        </terra-dropdown>
+    </terra-site-navigation>
+</terra-site-header>
+```
+
+### Custom Title Slot
+
+You can customize the title slot with a link or other content.
+
+```html:preview
+<terra-site-header>
+    <a slot="title" href="/" style="text-decoration: none; color: inherit;">Terra UI</a>
+    <terra-site-navigation slot="center">
+        <terra-dropdown placement="bottom-start" distance="3" hover>
+            <terra-button slot="trigger" size="medium" variant="text" caret>
+                About
+            </terra-button>
+            <terra-menu role="menu">
+                <terra-menu-item value="overview">
+                    <a href="#">Overview</a>
+                </terra-menu-item>
+            </terra-menu>
+        </terra-dropdown>
+    </terra-site-navigation>
+    <div slot="right" style="display: flex; align-items: center; gap: var(--terra-spacing-small);">
+        <button type="button" style="background: transparent; border: none; color: var(--terra-color-spacesuit-white); cursor: pointer; padding: var(--terra-spacing-2x-small);">
+            <terra-icon name="search" library="heroicons"></terra-icon>
+        </button>
+    </div>
+</terra-site-header>
+```
+
+[component-metadata:terra-site-header]