components

Imported from gesdisc/components (AGENTS.md). Install upstream with npx skills add gesdisc/components. Copyright stays with the author.

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

npm install

• Run dev server (docs + components)

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

npm run build          # builds Lit components, docs/assets, etc.

• Create a new component (scaffold)

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)

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

npm test                        # web-test-runner, default group
npm run test:watch              # watch mode
npm run test:component <name>   # test specific component in watch mode (e.g., npm run test:component data-access)

REQUIRED: MUST use npm run test:component <name> when testing a specific component (e.g., npm run test:component data-access). This runs tests in watch mode for faster iteration.

MUST run tests when making ANY changes to component behavior, properties, events, or data services.

• Static checks

npm run prettier:check
npm run spellcheck

• Verification before publish (for maintainers)

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.