diff --git a/projects/starters/angular/AGENTS.md b/projects/starters/angular/AGENTS.md new file mode 100644 index 000000000..75595146f --- /dev/null +++ b/projects/starters/angular/AGENTS.md @@ -0,0 +1,27 @@ +# Elements Angular Starter + +This file only covers how this starter wires Elements into Angular. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Register used Elements in the Angular component file that owns the template, as in `src/app/app.ts`. +- Add `CUSTOM_ELEMENTS_SCHEMA` to the standalone component metadata before using `nve-*` tags in `app.html`. +- Keep theme and utility CSS imports in `src/styles.css`; Angular component styles should stay local to component layout refinements. +- Keep `nve-theme` and `nve-transition` on `src/index.html`. + +## Angular Syntax + +- Use normal Angular template syntax with custom elements: `[property]` for JavaScript properties, `[attr.name]` for attributes, and `(event)` for custom events. +- Boolean attributes on custom elements usually need `[attr.hidden]="condition ? '' : null"` when the attribute semantics matter. +- Use Angular router primitives outside or inside Elements slots normally; Elements do not own Angular state. + +## Forms + +- Use Elements form wrappers around native inputs so Angular forms keep owning value and validation state. +- Bind Angular reactive forms to the nested native control, not to the `nve-*` wrapper. +- Put Angular conditional rendering for validation messages on `nve-control-message` or around it, depending on the control state. + +## Verification + +- Run `pnpm run build` in `projects/starters/angular` after schema, import, or template changes. +- Run `pnpm run lint` when editing TypeScript, HTML templates, or CSS. diff --git a/projects/starters/bundles/AGENTS.md b/projects/starters/bundles/AGENTS.md new file mode 100644 index 000000000..fd7820431 --- /dev/null +++ b/projects/starters/bundles/AGENTS.md @@ -0,0 +1,25 @@ +# Elements Bundles Starter + +This file only covers how this starter wires Elements into a static bundle page. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Load pre-built CSS bundles from `@nvidia-elements/styles`, `@nvidia-elements/themes`, and any optional package bundle in `src/index.html`. +- Load pre-built JavaScript bundles with module scripts in `src/index.html`. +- Keep bundle paths rooted through the Vite alias for `./node_modules` from `vite.config.ts`. +- Use this starter only when loading all registered components is acceptable; it trades tree-shaking for drop-in integration. + +## Optional Package Bundles + +- Include an optional package bundle only when the page uses that package. The current starter includes Monaco because it renders `nve-monaco-input`. +- Pair optional package JavaScript and CSS bundles when the package ships both. + +## DOM Events + +- Attach listeners with script code, not inline event handler attributes. +- Query typed Elements only after the bundle import has run. + +## Verification + +- Run `pnpm run build` in `projects/starters/bundles` after changing bundle paths or static HTML. +- Run `pnpm run dev` only when visual browser verification is needed. diff --git a/projects/starters/eleventy-ssr/AGENTS.md b/projects/starters/eleventy-ssr/AGENTS.md new file mode 100644 index 000000000..4854de02f --- /dev/null +++ b/projects/starters/eleventy-ssr/AGENTS.md @@ -0,0 +1,24 @@ +# Elements Eleventy SSR Starter + +This file only covers how this starter wires Elements into Eleventy with Lit SSR. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Configure Lit SSR in `eleventy.config.js` through `@lit-labs/eleventy-plugin-lit`. +- Keep `mode: 'worker'` for SSR isolation unless the build requirement changes. +- Provide server-renderable Elements through `componentModules`; include `@nvidia-elements/core/dist/icon/server.js` before component `define.js` entrypoints when icons can render server-side. +- Use metadata to generate broad component entrypoint lists only for SSR demos that intentionally exercise many Elements. + +## Hydration + +- Import `@lit-labs/ssr-client/lit-element-hydrate-support.js` in the client module script before importing client-side `define.js` modules. +- Match server `componentModules` and client `define.js` imports for components rendered in the HTML. + +## Template Constraints + +- Keep raw generated examples filtered away from components that are not SSR-safe for this starter. +- If transforming example templates, keep the transforms local and explicit in `src/index.11ty.js`. + +## Verification + +- Run `pnpm run build` in `projects/starters/eleventy-ssr` after SSR config, metadata filtering, or template changes. diff --git a/projects/starters/eleventy/AGENTS.md b/projects/starters/eleventy/AGENTS.md new file mode 100644 index 000000000..68f121b63 --- /dev/null +++ b/projects/starters/eleventy/AGENTS.md @@ -0,0 +1,26 @@ +# Elements Eleventy Starter + +This file only covers how this starter wires Elements into Eleventy. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Keep global Elements CSS in `src/_layouts/index.css`. +- Register Elements used by layout or markdown content in `src/_layouts/index.ts`. +- Keep shared page shell markup in `src/_layouts/index.11ty.js`; page files should supply content. +- Use `@11ty/eleventy-plugin-vite` for bundling the layout entrypoint. + +## Markdown Rendering + +- Add `nve-text` and `nve-layout` attributes through the markdown-it renderer in `eleventy.config.js` when markdown should receive Elements typography. +- Keep renderer mappings constrained to token types that markdown-it exposes predictably: headings, paragraphs, links, and lists. +- Let raw `nve-*` HTML pass through markdown only when the page intentionally owns that markup. + +## Routing + +- Keep the `` URL and Vite `base` aligned with `PAGES_BASE_URL`. +- Use relative links in generated tab markup so static output works under the starter base path. + +## Verification + +- Run `pnpm run build` in `projects/starters/eleventy` after layout, renderer, or asset pipeline changes. +- Run `pnpm run lint` when editing Eleventy config or layout TypeScript. diff --git a/projects/starters/go/AGENTS.md b/projects/starters/go/AGENTS.md new file mode 100644 index 000000000..5b4bcca48 --- /dev/null +++ b/projects/starters/go/AGENTS.md @@ -0,0 +1,26 @@ +# Elements Go Starter + +This file only covers how this starter wires Elements into Go templates. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Render Elements markup through `html/template` in `src/index.html`. +- Keep dynamic values in the Go `PageData` shape and pass them into the template; do not concatenate HTML strings in handlers. +- Use static bundles or a separate frontend build pipeline. This starter is the static-bundle path. + +## Static Assets + +- Treat the current CDN comments in `src/index.html` as placeholders until a real Elements CDN path exists. +- If serving local bundles instead, add explicit static file handling in `main.go` and point CSS and module imports at that route. +- Keep theme attributes on the root HTML template, not in Go handler code. + +## Go Template Constraints + +- Use escaped template output for data values. +- Only use trusted template HTML for checked Elements markup. +- Keep routing and rendering small; move repeated page shell code into templates before adding more routes. + +## Verification + +- Run `pnpm run build` in `projects/starters/go` after Go or template changes. +- Run `pnpm run dev` for local rendering checks on `http://localhost:8080`. diff --git a/projects/starters/hugo/AGENTS.md b/projects/starters/hugo/AGENTS.md new file mode 100644 index 000000000..44cfb5d38 --- /dev/null +++ b/projects/starters/hugo/AGENTS.md @@ -0,0 +1,28 @@ +# Elements Hugo Starter + +This file only covers how this starter wires Elements into Hugo. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Mount Elements package `dist` folders in `hugo.toml` before referencing package assets from templates. +- Keep static bundle CSS and module script loading in `layouts/baseof.html`. +- Allow raw HTML through Goldmark only when content authors are trusted to write checked Elements markup. +- Keep the Elements page shell in `layouts/baseof.html` and page-specific content in blocks or partials. + +## Render Hooks + +- Use Hugo render hooks to map markdown features onto Elements: + - headings: add `nve-text` based on heading level. + - links: add `nve-text="link"` and external-link attributes. + - tables: render `nve-grid`, `nve-grid-header`, `nve-grid-row`, and cells. + - code blocks: render `nve-codeblock`. +- Register the package bundle for any component introduced by a render hook. + +## Base URLs + +- Keep local and hosted base URL handling in `baseof.html`. +- Use relative links in tabs and partials so static output works under the hosted starter path. + +## Verification + +- Run `pnpm run build` in `projects/starters/hugo` after config, template, or render-hook changes. diff --git a/projects/starters/importmaps/AGENTS.md b/projects/starters/importmaps/AGENTS.md new file mode 100644 index 000000000..061c8151c --- /dev/null +++ b/projects/starters/importmaps/AGENTS.md @@ -0,0 +1,26 @@ +# Elements Import Maps Starter + +This file only covers how this starter wires Elements through browser import maps. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Keep the import map in `src/index.html` aligned with the packages copied by `build.js`. +- Map both bare package names and trailing-slash subpaths for Lit packages and `@nvidia-elements/core`. +- Import individual `define.js` files from the mapped `@nvidia-elements/core/` prefix. +- Load CSS with normal `` tags because there is no bundler to process CSS imports. + +## Static Copy Script + +- Update `build.js` whenever the import map references a new package that must exist in `dist/node_modules`. +- Copy package `dist` folders for Elements packages; copy full dependency folders only when browser subpath imports require them. +- Keep the copy list explicit. + +## Constraints + +- Use this starter for no-build prototypes and browser-native module loading. +- Prefer a Vite starter when tree-shaking, TypeScript transforms, or production bundling matter. + +## Verification + +- Run `pnpm run build` in `projects/starters/importmaps` after import map or copy script changes. +- Use `pnpm run dev` to catch browser import resolution errors. diff --git a/projects/starters/lit-library/AGENTS.md b/projects/starters/lit-library/AGENTS.md new file mode 100644 index 000000000..ed91d6cc5 --- /dev/null +++ b/projects/starters/lit-library/AGENTS.md @@ -0,0 +1,26 @@ +# Elements Lit Library Starter + +This file only covers how this starter wires Elements into reusable Lit components. For component APIs, use the Elements CLI/MCP documentation. For production core components, use repository component guidance; this starter is for reusable domain components outside `@nvidia-elements/core`. + +## Integration Points + +- Export side-effect-free classes from feature `index.ts` files. +- Put custom element registration in sibling `define.ts` files. +- Add every public deep import to `package.json#exports` and `typesVersions`. +- Keep `./**/define.js` in `sideEffects` so bundlers preserve registration entrypoints. + +## Composing Elements + +- Import Elements classes from side-effect-free entrypoints when using a scoped registry. +- Define composed Elements in the same registry used by `static shadowRootOptions.customElementRegistry`. +- Use `define.js` entrypoints only for global registration tests or consuming app examples. + +## Component Authoring + +- Keep public props primitive unless an ADR or local requirement justifies the exception. +- Emit standard DOM events with `bubbles: true` and `composed: true` when crossing the shadow root. +- Prefer form-associated custom elements when the domain component behaves as one form control. + +## Verification + +- Run `pnpm run build`, `pnpm run test`, and `pnpm run lint` in `projects/starters/lit-library` after component, export, or package changes. diff --git a/projects/starters/mpa/AGENTS.md b/projects/starters/mpa/AGENTS.md new file mode 100644 index 000000000..0549b73de --- /dev/null +++ b/projects/starters/mpa/AGENTS.md @@ -0,0 +1,26 @@ +# Elements MPA Starter + +This file only covers how this starter wires Elements into a Vite multi-page app. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Keep shared Elements CSS in `src/common/index.css`. +- Keep shared Elements registrations in `src/common/index.ts`. +- Import `./common/index.js` from each page entrypoint before page-specific code. +- Add new HTML pages to `vite.config.ts` `build.rolldownOptions.input`. + +## Page Structure + +- Each page owns its ``, metadata, stylesheet link, and module script. +- Keep selected navigation state local to each page's static HTML. +- Use root-relative dev paths in source HTML when Vite owns serving; verify build output after adding nested pages. + +## View Transitions + +- Keep `nve-transition` on the root HTML for global transitions. +- Add component-level transition attributes only to pages that need them. + +## Verification + +- Run `pnpm run build` in `projects/starters/mpa` after adding pages or changing shared entries. +- Run `pnpm run lint` after TypeScript or config changes. diff --git a/projects/starters/nextjs/AGENTS.md b/projects/starters/nextjs/AGENTS.md new file mode 100644 index 000000000..2c6018d0f --- /dev/null +++ b/projects/starters/nextjs/AGENTS.md @@ -0,0 +1,31 @@ +# Elements NextJS Starter + +This file only covers how this starter wires Elements into Next.js. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Use the React custom elements type augmentation in `src/global.d.ts`. +- Keep global theme attributes on `src/pages/_document.tsx`. +- Keep global CSS imports in `src/styles/globals.css`. +- Register Elements in the page or component module that renders them. + +## Next.js Runtime + +- This starter uses the pages router and `output: 'export'`. +- Keep `basePath`, `output`, and `distDir` aligned in `next.config.ts` for static starter output. +- Import server-specific modules, such as `@nvidia-elements/core/icon/server.js`, only when a component needs server render support. + +## SSR Status + +- Treat `@lit-labs/nextjs` integration as experimental in this starter. Do not enable it casually; the current config leaves it commented with the upstream issue. +- If enabling Lit SSR, import or configure it before any Elements registration imports and run a full build. + +## JSX Syntax + +- Use React custom element event naming such as `onclose` for a `close` event. +- Use primitive JSX props for custom element properties and strings for attributes when the Elements API expects attributes. + +## Verification + +- Run `pnpm run build` in `projects/starters/nextjs` after React, config, SSR, or type changes. +- Run `pnpm run lint` after TSX or config edits. diff --git a/projects/starters/nuxt/AGENTS.md b/projects/starters/nuxt/AGENTS.md new file mode 100644 index 000000000..dd5ed75dd --- /dev/null +++ b/projects/starters/nuxt/AGENTS.md @@ -0,0 +1,26 @@ +# Elements Nuxt Starter + +This file only covers how this starter wires Elements into Nuxt. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Keep `vue.compilerOptions.isCustomElement` in `nuxt.config.ts` so Vue treats `nve-*` tags as custom elements. +- Keep global `htmlAttrs` for `lang`, `nve-theme`, and `nve-transition` in `nuxt.config.ts`. +- Keep Elements Vue type references in `env.d.ts`. +- Import global Elements CSS in `app/app.vue`. + +## Layouts And Pages + +- Register Elements in the SFC that renders them. Shared page shell registrations belong in `app/layouts/default.vue`. +- Use `NuxtLink` inside Elements navigation components such as `nve-tabs-item`. +- Keep route content in `app/pages/*` and shared shell in layouts. + +## Vue Syntax + +- Use Vue custom element syntax: `:property` for properties and `@event` for custom events. +- Run `nuxi typecheck` through the package build before trusting template types. + +## Verification + +- Run `pnpm run build` in `projects/starters/nuxt` after config, layout, page, or type changes. +- Run `pnpm run lint` after Vue, TypeScript, or config edits. diff --git a/projects/starters/react/AGENTS.md b/projects/starters/react/AGENTS.md new file mode 100644 index 000000000..896a48fc9 --- /dev/null +++ b/projects/starters/react/AGENTS.md @@ -0,0 +1,22 @@ +# Elements React Starter + +This file only covers how this starter wires Elements into React. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Register Elements in the React module that renders the corresponding `nve-*` tags, as in `src/App.tsx`. +- Keep global theme CSS in `src/index.css`. +- Keep `nve-theme` and `nve-transition` on `src/index.html`. +- Keep JSX custom element type augmentation in `src/global.d.ts`. + +## JSX Syntax + +- Use direct custom elements for React 19. +- Use lowercase custom event props such as `onclose` for an Elements `close` event. +- Pass primitive values as JSX props when setting JavaScript properties. +- Use string attributes when the Elements API is attribute-driven. + +## Verification + +- Run `pnpm run build` in `projects/starters/react` after TSX, type, or import changes. +- Run `pnpm run lint` after React source edits. diff --git a/projects/starters/solidjs/AGENTS.md b/projects/starters/solidjs/AGENTS.md new file mode 100644 index 000000000..586d39ccd --- /dev/null +++ b/projects/starters/solidjs/AGENTS.md @@ -0,0 +1,22 @@ +# Elements SolidJS Starter + +This file only covers how this starter wires Elements into SolidJS. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Register Elements in the Solid component module that renders the tags, as in `src/App.tsx`. +- Keep Elements JSX augmentation in `src/types.d.ts` by extending `solid-js` JSX `IntrinsicElements`. +- Keep global Elements CSS in `src/index.css`. +- Keep theme attributes on `src/index.html`. + +## TSX Syntax + +- Use Solid's native custom element support with lowercase `nve-*` tags. +- Use event props such as `onclose` for custom Events. +- Use primitive reactive expressions for properties. +- Use explicit empty-string attributes where Solid serializes boolean attributes in static markup. + +## Verification + +- Run `pnpm run build` in `projects/starters/solidjs` after TSX, type, or import changes. +- Run `pnpm run lint` after Solid source edits. diff --git a/projects/starters/svelte/AGENTS.md b/projects/starters/svelte/AGENTS.md new file mode 100644 index 000000000..9e1407bf6 --- /dev/null +++ b/projects/starters/svelte/AGENTS.md @@ -0,0 +1,26 @@ +# Elements Svelte Starter + +This file only covers how this starter wires Elements into Svelte. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Register Elements in the `.svelte` component that renders them, as in `src/App.svelte`. +- Keep global Elements CSS in `src/app.css`. +- Keep theme attributes on `src/index.html`. +- Keep Vite root and output behavior in `vite.config.ts` aligned with the `src` directory layout. + +## Svelte Syntax + +- Use Svelte custom event binding such as `on:close`. +- Use `bind:property` only when the Elements property is mutable and the component actually emits a matching event. +- Prefer explicit attributes for static Elements configuration. + +## Type Checking + +- Use `svelte-check` through the package `check` script for `.svelte` files. +- Keep DOM-only code in component lifecycle or module contexts that Svelte can compile for the current target. + +## Verification + +- Run `pnpm run build` and `pnpm run check` in `projects/starters/svelte` after `.svelte`, TypeScript, or config changes. +- Run `pnpm run lint` after source edits. diff --git a/projects/starters/typescript/AGENTS.md b/projects/starters/typescript/AGENTS.md new file mode 100644 index 000000000..e9ae376ef --- /dev/null +++ b/projects/starters/typescript/AGENTS.md @@ -0,0 +1,27 @@ +# Elements TypeScript Starter + +This file only covers how this starter wires Elements into a Vite TypeScript app. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Register Elements in `src/index.ts`. +- Keep global Elements CSS in `src/index.css`. +- Keep the module script pointing at `./index.ts` from `src/index.html`. +- Keep root theme attributes on `src/index.html`. + +## TypeScript Usage + +- Import component classes as `type` imports when querying or narrowing DOM elements. +- Use `querySelector<ComponentType>('nve-component')` for local DOM access. +- Attach custom event listeners with `addEventListener`. +- Keep page-specific behavior in `src/index.ts`; extract reusable behavior only after another page or component needs it. + +## Vite Constraints + +- Keep `base: './'` for archive-friendly static output. +- Keep source paths relative to the `src` root established by `vite.config.ts`. + +## Verification + +- Run `pnpm run build` in `projects/starters/typescript` after HTML, TypeScript, CSS, or Vite changes. +- Run `pnpm run lint` after TypeScript edits. diff --git a/projects/starters/vue/AGENTS.md b/projects/starters/vue/AGENTS.md new file mode 100644 index 000000000..8ca0765eb --- /dev/null +++ b/projects/starters/vue/AGENTS.md @@ -0,0 +1,28 @@ +# Elements Vue Starter + +This file only covers how this starter wires Elements into Vue. For component APIs, template validation, and project setup commands, use the Elements CLI/MCP documentation instead. + +## Integration Points + +- Keep `template.compilerOptions.isCustomElement` in `vite.config.ts` so Vue treats `nve-*` tags as custom elements. +- Keep `custom-elements-vue.d.ts` referenced from `env.d.ts`. +- Keep `env.d.ts` included by `tsconfig.app.json`. +- Register Elements in the SFC that renders them, as in `src/App.vue`. +- Keep global Elements CSS in `src/main.css`. + +## Vue Syntax + +- Use `:property` for custom element properties. +- Use `@event` for custom Events. +- Use plain attributes for static string values. +- Keep router links or app-specific components inside Elements slots normally. + +## Type Checking + +- Use `vue-tsc` through the package build so invalid Elements attributes fail CI. +- If a new `nve-*` tag has no template type, verify the referenced generated type file includes it before adding local declarations. + +## Verification + +- Run `pnpm run build` in `projects/starters/vue` after Vue, type, or config changes. +- Run `pnpm run lint` after source edits.