arcgis-exb-widget-dev

name	arcgis-exb-widget-dev
description	Use when: creating, modifying, debugging, or testing ArcGIS Experience Builder widgets; covers runtime/setting surfaces, manifest/config/contracts, widget-list registration, translations, accessibility, map view / data source/ message action / data action / extension points, jimu-ui/jimu-for-builder/jimu-for-test, ArcGIS JS SDK and Calcite. For Developer Edition widget work, finish by running `npm run tscheck` from `client/` to validate `your-extensions`.
argument-hint	widget goal, existing widget path, or new widget name

ArcGIS Experience Builder Widget Development

When to Use

Use this skill for ArcGIS Experience Builder widget work, including:

• Creating a new widget from requirements.
• Modifying an existing widget runtime or setting UI.
• Wiring config.json, manifest.json, icon.svg, README.md, translations, tests, data sources, map views, actions, or builder support.
• Integrating jimu-ui, jimu-icon, theme tokens, jimu-arcgis, ArcGIS Maps SDK for JavaScript modules/components, or Calcite components.

Required First Steps

1. Determine whether the task is new widget or existing widget modification.
2. If the product requirements are still underspecified, stop and clarify them before implementation.
3. Locate the widget folder.
   • For existing widget modification, resolve the target from the provided widget path/name.
   • For new widget creation, infer placement from environment/path rules and repository naming convention.
4. Read the existing nearby widgets and framework types before editing. Prefer current repository patterns over assumptions.
5. Decide all surfaces that must change: runtime, setting, config, manifest, translations, tests, README, actions, builder-only support, assets.
6. Confirm which capability and widget communication contracts are affected (manifest/config/message actions/data actions/data sources/map/output data/state/extensions) before editing.

Requirement Clarification

When requirements are incomplete, use an interactive clarification step before implementation.

Do not start implementation until the minimum product requirements are clear enough to determine the affected capability contracts and implementation surfaces.

Minimum-ready information before implementation:

• task type is clear (new widget or existing widget modification)
• target widget identity is clear (name for new widget, path/name for existing widget)
• core user-facing behavior is clear
• data integration mode is clear (none, data source, map/layer view, or both)
• communication need is clear (none, or specific communication contracts)

Ask only for missing product requirements, and do it conditionally:

• Stop asking once the minimum-ready information is satisfied, then proceed to implementation.

• When asking about business requirements, always provide a small set of likely options and allow freeform input for anything not covered.

• Ask whether this is a new widget or an existing widget modification only if unclear, with options plus freeform input.

• Ask for widget name only if it is not already clear, with name suggestions plus freeform input.

• Ask for widget goal and core user-facing behavior only if the request is still too vague to determine the affected surfaces.

• Ask whether the widget needs a setting panel only if configuration behavior is still unclear.

• Ask first whether the widget needs to connect to app data. If yes, then clarify whether it needs data source integration, map or layer view integration, or both.

• If data source and map integration have already been confirmed, do not ask extra service-interface-detail questions unless implementation is blocked by missing technical constraints.

• Ask about backward compatibility for existing saved config only for existing widget modification, or when the request implies config/schema changes.

• Ask about widget communication only when the user goal suggests cross-widget interaction. In that case, offer likely options such as message actions, data actions, output data, or shared state, and allow freeform input for other communication needs.

• Do not ask the user to choose widget directory placement; infer placement from workspace/environment rules.

• Do not ask the user to choose localization scope by default; follow the repository localization checklist unless the user explicitly requests a different scope.

For example, a request like "build a photo gallery widget" is not specific enough to skip clarification. Before implementation, clarify the missing behavior and integration requirements such as data source usage, configuration surface, map dependence, and communication capabilities.

Environment Detection And Path Rules

Use this quick rule before editing:

1. If workspace has client/extensions/widgets/arcgis and client/webpack/widget-order.js, treat it as Source Code Repository.
2. Otherwise, treat it as Developer Edition and follow: https://developers.arcgis.com/experience-builder/guide/getting-started-widget/

Path and registration rules:

• Source Code Repository
  • Widget path families in this repo include client/extensions/widgets/arcgis, client/extensions/widgets/common, and existing product families such as lrs, geobim, quickcapture, survey123, and ba-infographic.
  • For new widgets, prefer arcgis (map-centric) or common (non-map-centric) unless requirements clearly belong to an existing product family.
  • For existing widget modification, keep the widget in its current family unless explicitly requested to migrate.
• Developer Edition
  • Widget path: typically client/your-extensions/widgets
  • If using a custom extension repo (not your-extensions), ensure the repo root has a manifest.json with type exb-web-extension-repo, and include that repo folder in client/tsconfig.json include
  • After finishing widget development in Developer Edition, run npm run tscheck from client/ to validate your-extensions

If target identity is still unclear for existing widget modification, ask for widget name or feature context first, not directory placement.

Development Workflow

Use workflow reference for the end-to-end process.

Use file and manifest reference before creating or changing:

• manifest.json
• config.json
• icon.svg
• README.md
• src/runtime/**
• src/setting/**
• src/config.ts
• src/runtime/translations/**
• src/setting/translations/**
• tests

Use implementation surfaces reference when the widget uses:

• jimu-ui, jimu-icon, Emotion, theme tokens (jimu-theme)
• data sources and data records
• JimuMapViewComponent, JimuLayerViewComponent, map/layer view APIs
• widget communication contracts (message actions, data actions, and data-sharing contracts)
• widget/app state communication
• widget state and app actions (WidgetState, appActions, getAppStore) for cross-widget coordination
• runtime execution boundaries (src/runtime/**)
• jimu-for-builder
• test
• assets and static resources
• URL parameter driven behavior
• translations
• accessibility

Use widget skeleton reference only as a starting shape. Adapt to nearby widgets and current framework APIs.

General Engineering Baseline

• Keep changes focused and avoid unrelated refactors.
• Preserve backward compatibility for existing app config unless the task explicitly requires a breaking change.
• Add tests and README updates only when behavior/setup/contracts are affected.

Core Rules

• manifest.json is mandatory for every widget. Missing manifest means the folder is not a valid widget package for build/discovery.
• Treat manifest.json as a capability contract. Use manifest fields to express widget capabilities, actions, dependencies, default size, licensing, URL params, layouts, and translated locales instead of hiding those decisions in runtime code.
• Runtime must be resilient to missing optional configuration, unavailable data sources, unloaded map views, and builder/runtime mode differences.
• New widgets must use React functional components (FC) for runtime and setting surfaces; use class components only when modifying existing legacy widgets.
• Runtime code must not import jimu-for-builder; keep builder-only APIs in setting, builder support modules, or builder widgets.
• Prefer runtime UI from jimu-ui or jimu-ui/basic/* or jimu-ui/advanced/*; use Calcite or ArcGIS web components when the scenario requires them.
• Setting UI must save selected data sources (and selected fields when used) through Experience Builder setting patterns and expose only valid combinations of options.
• For framework-managed selections (for example useDataSources, useMapWidgetIds), write them through top-level onSettingChange payload fields instead of config.set(...).
• Keep translation keys widget-scoped and non-generic (for example with a widget prefix) to reduce conflict risk with framework/shared keys.
• Keep runtime and setting config types aligned in src/config.ts.
• Use sys design tokens (theme.sys.* or var(--sys-*)) in new code, and do not use classic token paths such as theme.colors, theme.sizes, theme.borderRadiuses, theme.boxShadows, theme.typography, theme.surfaces, theme.body, theme.link, theme.border, or CSS vars like var(--light-*)/var(--dark-*).
• For JSAPI-heavy widgets, declare jimu-arcgis dependency in manifest.json and use approved import patterns; for conditional JSAPI usage, prefer dynamic loading via ExB loaders.
• Prefer ExB wrappers and jimu-ui design system components first; use Calcite or ArcGIS Maps SDK web components when the scenario requires them.

Done Criteria

• Widget files are complete and internally consistent.
• manifest.json exists and declares all required capabilities and dependencies.
• Runtime and setting UI handle configured and unconfigured states, including reading selected data sources from props.useDataSources when data source integration is required.
• In Source Code Repository, new widgets are registered in the widget list source when category/order control is required (otherwise they fall back to Custom group/default ordering).
• When user-visible strings or translation folders change, translations cover those strings, manifest.translatedLocales stays complete, and any new translation folder is listed in translation-manifest.txt.
• Translation key names avoid generic collisions with framework/shared keys (for example by using widget-prefixed keys).
• In Source Code Repository, post-development checks are run from client/: npm run tscheck:extensions and npm run check-translation.
• In Developer Edition, npm run tscheck is part of the finish-of-work validation for your-extensions widget development.
• If config schema changed and compatibility cannot be guaranteed by fallback/default handling, VersionManager-based migration behavior via version-manager.ts is implemented and validated.
• A11y labels, keyboard behavior, focus, status text, and contrast are addressed.
• Tests or existing validation commands pass for the touched area, including data source selection/query/filter behavior when data contracts are changed.