terra_ui_components 0.0.123__tar.gz → 0.0.131__tar.gz

terra_ui_components-0.0.131/AGENTS.md

@@ -0,0 +1,271 @@
+## Purpose
+
+This file contains **MANDATORY instructions** for AI coding assistants (like Claude, GPT, or Cursor Agents) working in this repo. **You MUST follow these guidelines.**
+
+Your main goals:
+
+-   **Help build, refactor, and debug Terra UI components** (Lit-based web components, React wrappers, and Python widgets).
+-   **ALWAYS use the existing documentation in `docs/` instead of re‑inventing APIs or behavior.**
+
+**REQUIRED:** When in doubt, **you MUST read existing docs and code rather than guessing.**
+
+---
+
+## Where to Read Documentation
+
+-   **Component docs (primary source)**
+    -   Markdown docs for each component live at `docs/pages/components/*.md`.
+    -   Examples:
+        -   `docs/pages/components/map.md`
+        -   `docs/pages/components/time-average-map.md`
+        -   `docs/pages/components/browse-variables.md`
+    -   These files usually contain:
+        -   Example HTML usage blocks (often fenced as ` ```html:preview `).
+        -   A `[component-metadata:terra-X]` tag; behavior is defined by the underlying component in `src/components/`.
+-   **Getting started / framework integration**
+    -   `docs/pages/getting-started/*.md` – overall usage, themes, installation, localization, etc.
+    -   `docs/pages/frameworks/*.md` – using Terra UI with React, Vue, Angular, etc.
+-   **Design tokens**
+    -   `docs/pages/tokens/*.md` – color, typography, spacing, etc. **You MUST use these as the single source of truth for design decisions.**
+
+**REQUIRED workflow when building or modifying a component:**
+
+1. **MUST read the relevant `docs/pages/components/<component>.md` first.**
+2. **MUST review its implementation in `src/components/<component>/<component>.component.ts` (and related controller/utility files).**
+3. **MUST ensure proper tests exist** in `src/components/<component>/<component>.test.ts` covering:
+    - Component rendering
+    - Property changes
+    - Event emission
+    - User interactions (clicks, keyboard navigation)
+    - Edge cases and error states
+    - Accessibility features
+4. **MUST keep the docs, implementation, and examples in sync when making behavior or API changes.**
+
+You can also consult the built documentation site under `_site/` (mirrors `docs/`), but prefer editing/reading the Markdown sources in `docs/`.
+
+---
+
+## Core Project Layout
+
+-   **Lit web components**
+    -   Source: `src/components/**`
+    -   Example complex components:
+        -   `time-average-map` – `src/components/time-average-map/*.ts`
+        -   `browse-variables` – `src/components/browse-variables/*.ts`
+-   **React wrappers**
+    -   `src/react/**` – React bindings around the web components.
+-   **Python widgets / Jupyter**
+    -   `src/terra_ui_components/**` – Python package for Jupyter widgets.
+    -   `notebooks/playground.ipynb` – example notebook using components.
+-   **Docs site**
+    -   Source: `docs/**`
+    -   Built site: `_site/**`
+-   **Build & tooling scripts**
+    -   `scripts/*.js` – Node build, theming, React wrapper generation, etc.
+    -   `scripts/plop/*.js|*.hbs` – code generators for new components/widgets.
+
+**REQUIRED:** When you need to understand how a feature works, **you MUST start from the component docs, then read the corresponding `src/components` files and any data services or utilities they depend on.**
+
+---
+
+## Common Commands (Node & Python)
+
+From the repo root:
+
+-   **Install JS deps**
+
+```bash
+npm install
+```
+
+-   **Run dev server (docs + components)**
+
+```bash
+npm start        # alias for `npm run serve`
+```
+
+This uses `node scripts/build.js --serve` and will:
+
+-   Build the components and docs
+-   Start a local dev server
+-   Auto-reload the browser for most source changes (no full HMR due to custom elements constraints)
+
+-   **Build for production**
+
+```bash
+npm run build          # builds Lit components, docs/assets, etc.
+```
+
+-   **Create a new component (scaffold)**
+
+```bash
+npm run create terra-my-component
+```
+
+This uses `plop` to scaffold:
+
+-   Component source files under `src/components/`
+-   Styles
+-   Jupyter widget support
+-   A docs page in `docs/pages/components/`
+-   **A test file (`*.test.ts`)** – **MUST implement comprehensive tests** before considering the component complete.
+
+After scaffolding, run `git status` to see all new/updated files and **update docs/examples as needed.**
+
+-   **Python / Jupyter dev workflow (using `uv`)**
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+npm run start:python   # launches Jupyter Lab via .venv
+```
+
+Then open `notebooks/playground.ipynb` to test components in Jupyter.
+
+---
+
+## Code Style & Conventions
+
+-   **Formatting**
+    -   **MUST use Prettier** with the shared config `@gesdisc/prettier-config`.
+    -   **MUST run `npm run prettier`** or rely on `lint-staged` hooks for staged `.ts` and `.js` files.
+-   **Languages & frameworks**
+    -   Core components are **Lit 3** web components in TypeScript (`lit` package).
+    -   Data-heavy UI uses utilities such as `leaflet`, `ol`, `plotly.js-dist-min`, `ag-grid-community`, etc. **MUST extend existing patterns rather than inventing new ones.**
+-   **Component naming**
+    -   Custom elements **MUST use** the `terra-` prefix: `terra-map`, `terra-time-average-map`, etc.
+    -   **MUST keep tag names stable**; if you must change them, **MUST update:**
+        -   Component implementation
+        -   Docs in `docs/pages/components/*.md`
+        -   Any React/Python wrappers and examples.
+-   **Structure**
+    -   For complex components, logic is often split into `*.component.ts` and `*.controller.ts` plus shared utilities.
+    -   **MUST use small, focused controllers and utilities** instead of bloating the component class.
+
+**REQUIRED:** When generating or modifying code, **you MUST match the patterns already used in similar components.** For example, if editing `time-average-map`, **MUST also inspect `map` and `time-series` components** to keep UX and API surface consistent.
+
+---
+
+## Testing & Quality
+
+**REQUIRED:** **ALL components MUST have comprehensive tests.** This is NOT optional.
+
+-   **Component Testing Requirements**
+
+    -   **MUST create or update test files** (`*.test.ts`) for every component you create or modify.
+    -   **MUST use `@open-wc/testing`** utilities (`fixture`, `expect`, `html`, `waitUntil`, etc.) following existing test patterns.
+    -   **MUST test:**
+        -   Component rendering
+        -   Property changes and attribute reflection
+        -   Event emission
+        -   User interactions (clicks, keyboard navigation, form inputs)
+        -   Edge cases and error states
+        -   Accessibility features (ARIA attributes, keyboard navigation, focus management)
+    -   **MUST follow existing test patterns** found in components like `accordion.test.ts`, `badge.test.ts`, etc.
+    -   **MUST ensure all tests pass** before considering work complete.
+
+-   **JS tests**
+
+```bash
+npm test            # web-test-runner, default group
+npm run test:watch  # watch mode
+```
+
+**MUST run tests when making ANY changes** to component behavior, properties, events, or data services.
+
+-   **Static checks**
+
+```bash
+npm run prettier:check
+npm run spellcheck
+```
+
+-   **Verification before publish (for maintainers)**
+
+```bash
+npm run verify      # prettier + build (placeholder for full test suite)
+```
+
+**REQUIRED:** If you introduce or modify tests, **MUST keep them aligned with web-test-runner** and **MUST follow existing test patterns** in the repo.
+
+---
+
+## Git & Repository Etiquette (for AI Agents)
+
+-   **Branching**
+    -   **MUST use feature branches** named like:
+        -   `feature/<short-description>`
+        -   `bugfix/<short-description>`
+        -   `docs/<component-or-topic>`
+    -   **MUST NOT commit directly to `main`** in automated workflows.
+-   **Commits**
+    -   **MUST use clear, imperative commit messages:**
+        -   `Add time-average-map zoom controls`
+        -   `Fix browse-variables search reset bug`
+-   **Merging vs. rebasing**
+    -   It's acceptable to use either:
+        -   **Rebase** small feature branches before opening a PR to keep history linear.
+        -   **Merge commits** are fine for human-maintained, multi-commit branches.
+    -   **STRICTLY PROHIBITED:** As an AI, **you MUST NOT perform `git push`, `git commit`, or branching commands** unless the user explicitly asks and understands the implications.
+
+**REQUIRED:** When suggesting git operations, **you MUST describe the commands for the human developer** instead of running them.
+
+---
+
+## Unexpected Behaviors / Project Quirks
+
+-   **No full HMR for web components**
+    -   The dev server can’t fully hot-reload custom elements due to browser limitations on re-defining tags.
+    -   Expect page reloads instead of fine-grained HMR when editing component code.
+-   **Docs generation**
+    -   The Eleventy-based docs (`@11ty/eleventy`) use front matter and custom shortcodes (e.g., `[component-metadata:terra-map]`).
+    -   **REQUIRED:** When editing docs, **MUST keep front matter and shortcode usage intact**; **MUST NOT convert to plain markdown headings only.**
+-   **Type definitions and metadata**
+    -   `dist/custom-elements.json`, `cdn/custom-elements.json`, and `web-types.json` are generated from source.
+    -   **PROHIBITED:** **MUST NOT hand-edit generated files**; **MUST update the relevant source code and rerun builds instead.**
+
+If behavior seems “magical,” look for:
+
+-   Custom elements metadata generation (`custom-elements-manifest` configs).
+-   Scripts in `scripts/*.js` that stitch together docs, metadata, and CDN builds.
+
+---
+
+## How to Work with the Component Docs (MANDATORY Workflow)
+
+**REQUIRED:** When a user asks about a component, **you MUST follow these steps:**
+
+-   **Step 1 (REQUIRED)** – **MUST locate its docs in `docs/pages/components/<name>.md` first.**
+    -   Example: for `terra-map`, **MUST read `docs/pages/components/map.md`.**
+    -   Example: for `terra-time-average-map`, **MUST read `docs/pages/components/time-average-map.md`.**
+-   **Step 2 (REQUIRED)** – **MUST inspect its implementation in `src/components/<name>/**`.\*\*
+-   **Step 3 (REQUIRED if applicable)** – If the question involves usage in a framework (React/Vue/Angular), **MUST also read:**
+    -   `docs/pages/frameworks/react.md`
+    -   `docs/pages/frameworks/vue*.md`
+    -   `docs/pages/frameworks/angular.md`
+
+**REQUIRED:** When generating example code, **you MUST mirror the examples shown in those docs** (props/attributes, events, CSS variables, etc.) and **MUST NOT invent undocumented attributes.**
+
+---
+
+## Things to Remember as an AI Assistant (MANDATORY Rules)
+
+-   **STRICTLY PROHIBITED:** **MUST NEVER invent public APIs** for components; **MUST always verify attributes, events, and slots in:**
+    -   The component's docs (`docs/pages/components/*.md`)
+    -   The component's TypeScript source in `src/components/**`
+    -   Generated metadata (`dist/custom-elements.json`) if necessary.
+-   **REQUIRED:** **MUST keep docs in sync** when changing behavior:
+    -   If you add a new prop/attribute/event, **MUST update:**
+        -   The relevant component doc in `docs/pages/components/*.md`
+        -   Examples in `_site/` if needed (via rebuild)
+        -   Any cross-references in tutorials or framework docs.
+-   **REQUIRED:** **MUST prefer minimal, targeted edits** over large refactors unless the user explicitly asks for a redesign.
+-   **REQUIRED:** **MUST explain your reasoning briefly** when making substantial code changes, and **MUST point to the specific files you touched** so the user can review.
+-   **REQUIRED:** **MUST ensure proper testing** for all components:
+    -   When creating a new component, **MUST create comprehensive tests** in `*.test.ts` covering all functionality.
+    -   When modifying a component, **MUST update or add tests** to cover the new/changed behavior.
+    -   **MUST NOT** submit components without tests or with incomplete test coverage.
+    -   **MUST verify tests pass** using `npm test` or `npm run test:watch` before considering work complete.
+
+**REQUIRED:** If you're ever uncertain, **MUST ask the human developer for clarification** rather than guessing about user-facing behavior.

terra_ui_components-0.0.131/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{terra_ui_components-0.0.123 → terra_ui_components-0.0.131}/PKG-INFO

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

{terra_ui_components-0.0.123 → terra_ui_components-0.0.131}/docs/_includes/default.njk

@@ -63,7 +63,7 @@
         <link href="https://fonts.googleapis.com/css2?family=Bebas+Neue&display=swap" rel="stylesheet">
         <link href="https://fonts.googleapis.com/css2?family=DM+Mono&family=Inter&family=Public+Sans&display=swap" rel="stylesheet">
     </head>
-    <body class="terra-prefers-color-scheme">
+    <body>
         <a id="skip-to-main" class="visually-hidden" href="#main-content" data-smooth-link="false">
       Skip to main content
     </a>
@@ -127,45 +127,52 @@
                 <a href="https://github.com/nasa/terra-ui-components" title="View Terra UI Components on GitHub" class="top-nav__icon-link">
                     <svg style="width: 24px; fill: #fff;" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>GitHub</title><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
                 </a>
+
+                <terra-dropdown id="theme-selector" placement="bottom-end" distance="3">
+                    <terra-button slot="trigger" size="medium" variant="text" caret title="Press \ to toggle">
+                        <terra-icon class="only-light" name="solid-sun" library="heroicons"></terra-icon>
+                        <terra-icon class="only-dark" name="solid-moon" library="heroicons"></terra-icon>
+                    </terra-button>
+                    
+                    <terra-menu>
+                        <terra-menu-item type="checkbox" value="light">Light</terra-menu-item>
+                        <terra-menu-item type="checkbox" value="dark">Dark</terra-menu-item>
+                        <terra-divider></terra-divider>
+                        <terra-menu-item type="checkbox" value="auto">System</terra-menu-item>
+                    </terra-menu>
+                </terra-dropdown>
             </div>
         </terra-site-header>
 
-        {# Menu toggle #}
-        <button id="menu-toggle" type="button" aria-label="Menu">
-            <svg width="148" height="148" viewBox="0 0 148 148" xmlns="http://www.w3.org/2000/svg">
-                <g stroke="currentColor" stroke-width="18" fill="none" fill-rule="evenodd" stroke-linecap="round">
-                    <path d="M9.5 125.5h129M9.5 74.5h129M9.5 23.5h129"></path>
-                </g>
-            </svg>
-        </button>
+        <section id="content-container">
+            <aside id="sidebar" data-preserve-scroll>
+                <nav>
+                    {% include 'sidebar.njk' %}
+                </nav>
+            </aside>
 
-        <aside id="sidebar" data-preserve-scroll>
-            <nav>
-                {% include 'sidebar.njk' %}
-            </nav>
-        </aside>
+            {# Content #}
+            <main>
+                <a id="main-content"></a>
+                <article id="content" class="content{% if (meta.toc is defined and meta.toc) or (meta.toc is not defined and toc) %} content--with-toc{% endif %}">
+                    {% if (meta.toc is defined and meta.toc) 
+                        or(meta.toc is not defined and toc) %}
+                        <div class="content__toc">
+                            <ul>
+                                <li class="top">
+                                    <a href="#">{{ meta.title }}</a>
+                                </li>
+                            </ul>
+                        </div>
+                    {% endif %}
 
-        {# Content #}
-        <main>
-            <a id="main-content"></a>
-            <article id="content" class="content{% if (meta.toc is defined and meta.toc) or (meta.toc is not defined and toc) %} content--with-toc{% endif %}">
-                {% if (meta.toc is defined and meta.toc) 
-                    or(meta.toc is not defined and toc) %}
-                    <div class="content__toc">
-                        <ul>
-                            <li class="top">
-                                <a href="#">{{ meta.title }}</a>
-                            </li>
-                        </ul>
+                    <div class="content__body">
+                        {% block content %}
+                            {{ content | safe }}
+                        {% endblock %}
                     </div>
-                {% endif %}
-
-                <div class="content__body">
-                    {% block content %}
-                        {{ content | safe }}
-                    {% endblock %}
-                </div>
-            </article>
-        </main>
+                </article>
+            </main>
+        </div>
     </body>
 </html>

{terra_ui_components-0.0.123 → terra_ui_components-0.0.131}/docs/_includes/sidebar.njk

@@ -43,6 +43,7 @@
             </li>
         </ul>
     </li>
+
     
     {% for sectionName in meta.sidebarSectionOrder %}
         {% if meta.componentsBySection[sectionName] %}

{terra_ui_components-0.0.123 → terra_ui_components-0.0.131}/docs/assets/styles/docs.css

@@ -897,15 +897,13 @@ pre:hover .copy-code-button,
     }
 }
 
+#content-container {
+    display: flex;
+}
+
 /* Sidebar */
 #sidebar {
-    position: fixed;
-    flex: 0;
-    top: var(--docs-top-nav-height);
-    left: 0;
-    bottom: 0;
-    z-index: 20;
-    width: var(--docs-sidebar-width);
+    flex: 1 0 var(--docs-sidebar-width);
     background-color: var(--docs-background-color);
     border-right: solid var(--docs-border-width) var(--docs-border-color);
     border-radius: 0;
@@ -997,11 +995,7 @@ pre:hover .copy-code-button,
 
 @media screen and (max-width: 900px) {
     #sidebar {
-        translate: -100%;
-    }
-
-    .sidebar-open #sidebar {
-        translate: 0;
+        display: none;
     }
 }
 
@@ -1024,8 +1018,7 @@ main {
     position: relative;
     padding: var(--docs-content-vertical-spacing) var(--docs-content-padding)
         calc(var(--docs-content-vertical-spacing) * 2) var(--docs-content-padding);
-    margin-left: var(--docs-sidebar-width);
-    margin-top: var(--docs-top-nav-height);
+    width: 100%;
 }
 
 .sidebar-open .content {
@@ -1672,10 +1665,6 @@ body[data-page^='/tokens/'] .table-wrapper td:first-child code {
     margin-left: 140px;
 }
 
-main {
-    margin-top: 70px;
-}
-
 @media screen and (max-width: 1650px) {
     .ks-banner,
     .ks-banner.with-toc {
@@ -1683,10 +1672,6 @@ main {
         top: 50px;
         left: calc(50% - 270px);
     }
-
-    main {
-        margin-top: 140px;
-    }
 }
 
 @media screen and (max-width: 900px) {
@@ -1703,8 +1688,4 @@ main {
         left: 1rem;
         flex-direction: column;
     }
-
-    main {
-        margin-top: 150px;
-    }
 }

{terra_ui_components-0.0.123 → terra_ui_components-0.0.131}/docs/pages/components/alert.md

@@ -3,7 +3,6 @@ meta:
     title: Alert
     description: Alerts are used to display important messages inline or as toast notifications.
 layout: component
-sidebarSection: Elements
 ---
 
 ```html:preview

{terra_ui_components-0.0.123 → terra_ui_components-0.0.131}/docs/pages/components/avatar.md

@@ -3,7 +3,6 @@ meta:
     title: Avatar
     description: Avatars are used to represent a person or object.
 layout: component
-sidebarSection: Elements
 ---
 
 By default, a generic icon will be shown. You can personalize avatars by adding custom icons, initials, and images. You should always provide a `label` for assistive devices.

{terra_ui_components-0.0.123 → terra_ui_components-0.0.131}/docs/pages/components/badge.md

@@ -3,7 +3,6 @@ meta:
     title: Badge
     description: Badges are used to draw attention and display statuses or counts.
 layout: component
-sidebarSection: Elements
 ---
 
 ```html:preview