diff --git a/AGENTS.md b/AGENTS.md index 147fdf04a..470b99069 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -273,3 +273,12 @@ When adding new technical terms, component names, or abbreviations that Vale fla - `projects/*/DEVELOPMENT.md` - When working within a specific project; lists all available pnpm scripts for that project - `/projects/internals/BUILD.md` - When modifying build configuration, Wireit scripts, or CI/CD pipeline - `/projects/internals/RELEASE.md` - When creating new projects or modifying release process; covers semantic release setup, CI artifacts, commit scopes, initial tags + +## Cloud Agent Specific Instructions + +These notes are for cloud agents running in the prebuilt VM (dependencies already installed by the startup update script). They capture non-obvious caveats, not full setup steps. + +### Toolchain access + +- **mise** manages the toolchain, and the VM image already includes it. `~/.local/bin` sits on `PATH` and `mise activate` runs from `~/.bashrc`, so `node` (26.4.0), `pnpm` (11.9.0), `go`, `vale`, and `git-lfs` resolve directly. If a fresh shell ever lacks them, prefix commands with `mise exec --` (for example, `mise exec -- pnpm ...`) or run `mise run `. +- Run all repo commands through mise to guarantee the pinned versions, exactly as the root `AGENTS.md` examples show. diff --git a/projects/site/src/_11ty/layouts/common.js b/projects/site/src/_11ty/layouts/common.js index 1a2f73496..580b90cc9 100644 --- a/projects/site/src/_11ty/layouts/common.js +++ b/projects/site/src/_11ty/layouts/common.js @@ -150,6 +150,7 @@ export const renderDocsNav = data => /* html */ ` Bundles CDN Custom Elements + Eleventy Golang HTMX + Go Hugo diff --git a/projects/site/src/_11ty/shortcodes/svg-logo.js b/projects/site/src/_11ty/shortcodes/svg-logo.js index 63210f101..deb7e39fb 100644 --- a/projects/site/src/_11ty/shortcodes/svg-logo.js +++ b/projects/site/src/_11ty/shortcodes/svg-logo.js @@ -19,6 +19,7 @@ const svgs = { claude: ``, codex: ``, cursor: ``, + eleventy: ``, javascript: ``, angular: ``, vue: ``, diff --git a/projects/site/src/docs/integrations/eleventy.md b/projects/site/src/docs/integrations/eleventy.md new file mode 100644 index 000000000..b8aee8d8f --- /dev/null +++ b/projects/site/src/docs/integrations/eleventy.md @@ -0,0 +1,155 @@ +--- +{ + title: 'Eleventy', + description: 'Use NVIDIA Elements in Eleventy with Vite-bundled component definitions and styles, template markup, and optional Lit server-side rendering.', + layout: 'docs.11ty.js' +} +--- + +# {{ title }} + +{% integration 'eleventy' %} + +{% installation 'eleventy' %} + +Elements are standard Web Components, so Eleventy can emit their tags from any template language. For most sites, render the element markup at build time and register the components in the browser. Use Lit server-side rendering (SSR) only when component shadow DOM must be present in the generated HTML. + +## Client-Side Rendering + +The [Eleventy starter]({{ELEMENTS_REPO_BASE_URL}}/tree/main/projects/starters/eleventy) uses [Eleventy Plugin Vite](https://github.com/11ty/eleventy-plugin-vite) to bundle Elements styles and component definitions. This approach supports tree-shaking and keeps the Eleventy build environment separate from browser component registration. + +Install the Vite integration in an existing Eleventy project: + +```shell +npm install --save-dev @11ty/eleventy-plugin-vite vite +``` + +### Configure Eleventy and Vite + +Register the Vite plugin and copy the browser entry files into Eleventy's output for Vite to process: + +```javascript +// eleventy.config.js +import EleventyPluginVite from '@11ty/eleventy-plugin-vite'; + +export default function (eleventyConfig) { + eleventyConfig.addPassthroughCopy('src/**/*.ts'); + eleventyConfig.addPassthroughCopy('src/**/*.css'); + + eleventyConfig.addPlugin(EleventyPluginVite, { + viteOptions: { + build: { + target: 'esnext' + } + } + }); + + return { + dir: { + input: 'src', + output: 'dist', + layouts: '_layouts' + } + }; +} +``` + +If you deploy the site below the domain root, set the same base path in the Vite `base` option and the document's `` element. Keeping those values aligned lets entry points and generated links resolve from the deployment path. + +### Add Browser Entry Points + +Create a TypeScript entry point for component registration. Import each `define.js` module that the site uses: + +```typescript +// src/_layouts/elements.ts +import './elements.css'; +import '@nvidia-elements/core/alert/define.js'; +import '@nvidia-elements/core/button/define.js'; +``` + +Create a CSS entry point for the global theme, font, and utility styles: + +```css +/* src/_layouts/elements.css */ +@import '@nvidia-elements/themes/fonts/inter.css'; +@import '@nvidia-elements/themes/index.css'; +@import '@nvidia-elements/themes/dark.css'; +@import '@nvidia-elements/styles/layout.css'; +@import '@nvidia-elements/styles/typography.css'; +@import '@nvidia-elements/styles/view-transitions.css'; +``` + +Load the entry points from the shared Eleventy layout: + +{% raw %} + +```html + + + + + + + + + + {{ content | safe }} + + +``` + +{% endraw %} + +Keep `define.js` imports in the browser entry point. The Eleventy configuration runs in Node.js and should not register browser components unless you configure SSR. + +### Use Elements in Templates + +Write Elements markup in HTML, JavaScript, or Markdown templates: + +```html +
+ Site generated successfully. + + View documentation + +
+``` + +When configuring a custom Markdown library, enable inline HTML so Markdown pages can emit `nve-*` tags. The starter also extends the Markdown renderer to add `nve-text` and `nve-layout` attributes to generated headings, paragraphs, links, and lists. + +## Server-Side Rendering + +The [`@lit-labs/eleventy-plugin-lit`](https://github.com/lit/lit/tree/main/packages/labs/eleventy-plugin-lit) plugin can render Lit components into declarative shadow DOM during the Eleventy build. Lit SSR and the Eleventy plugin are experimental, so verify component compatibility before using this path in production. The [Eleventy SSR starter]({{ELEMENTS_REPO_BASE_URL}}/tree/main/projects/starters/eleventy-ssr) provides a working testbed. + +Install the SSR plugin and client hydration support: + +```shell +npm install @lit-labs/eleventy-plugin-lit @lit-labs/ssr-client +``` + +Register every component that Eleventy must render. Load the server-compatible icon module before components that can render icons: + +```javascript +// eleventy.config.js +import litPlugin from '@lit-labs/eleventy-plugin-lit'; + +export default function (eleventyConfig) { + eleventyConfig.addPlugin(litPlugin, { + mode: 'worker', + componentModules: [ + 'node_modules/@nvidia-elements/core/dist/icon/server.js', + 'node_modules/@nvidia-elements/core/dist/alert/define.js' + ] + }); +} +``` + +For interactive components, load Lit hydration support before the client-side component definitions: + +```typescript +// src/_layouts/elements.ts +import '@lit-labs/ssr-client/lit-element-hydrate-support.js'; +import '@nvidia-elements/core/alert/define.js'; +``` + +The server `componentModules` list and the browser `define.js` imports must include the same interactive components. Components that do not load in the browser remain static after Eleventy renders them. diff --git a/projects/site/src/docs/integrations/index.11ty.js b/projects/site/src/docs/integrations/index.11ty.js index e0cf5cf96..6c6771b93 100644 --- a/projects/site/src/docs/integrations/index.11ty.js +++ b/projects/site/src/docs/integrations/index.11ty.js @@ -1,131 +1,10 @@ +import { siteData } from '../../index.11tydata.js'; + export const data = { title: 'Integrations', layout: 'docs.11ty.js' }; -const integrations = [ - { - href: '/docs/integrations/angular/', - icon: 'angular.svg', - title: 'Angular', - description: 'Use Elements with Angular templates and events.' - }, - { - href: '/docs/integrations/bundles/', - icon: 'javascript.svg', - title: 'Bundles', - description: 'Load prebuilt Elements bundles in static pages.' - }, - { - href: '/docs/integrations/cdn/', - nveIcon: 'globe-alt-stroke', - title: 'CDN', - description: 'Load Elements from CDN-hosted npm packages.' - }, - { - href: '/docs/integrations/custom-elements/', - nveIcon: 'code', - title: 'Custom Elements', - description: 'Use Elements package metadata with Web Component tooling.' - }, - { - href: '/docs/integrations/go/', - icon: 'go.svg', - iconSize: '48', - title: 'Golang', - description: 'Use Elements with Go-backed web applications.' - }, - { - href: '/docs/integrations/go-htmx/', - icon: 'htmx.svg', - iconHeight: '32', - iconWidth: '48', - title: 'HTMX + Go', - description: 'Use Elements with HTMX and Go template fragments.' - }, - { - href: '/docs/integrations/hugo/', - icon: 'hugo.svg', - iconSize: '28px', - title: 'Hugo', - description: 'Use Elements in Hugo static sites.' - }, - { - href: '/docs/integrations/importmaps/', - icon: 'javascript.svg', - title: 'Import Maps', - description: 'Load Elements from browser-native import maps.' - }, - { - href: '/docs/integrations/lit/', - icon: 'lit.svg', - title: 'Lit', - description: 'Use Elements alongside Lit components and SSR.' - }, - { - href: '/docs/integrations/lit-library/', - icon: 'lit.svg', - title: 'Lit Library', - description: 'Build a distributable Custom Element library with Lit and Elements.' - }, - { - href: '/docs/integrations/mcp-apps/', - nveIcon: 'connected-blocks', - title: 'MCP Apps', - description: 'Use Elements in iframe-based MCP UI hosts.' - }, - { - href: '/docs/integrations/nextjs/', - icon: 'nextjs.svg', - iconSize: '28px', - title: 'NextJS', - description: 'Use Elements with NextJS and React.' - }, - { - href: '/docs/integrations/nuxt/', - icon: 'nuxt.svg', - iconSize: '38px', - title: 'Nuxt', - description: 'Use Elements with Nuxt applications.' - }, - { - href: '/docs/integrations/preact/', - icon: 'preact.svg', - title: 'Preact', - description: 'Use Elements with Preact JSX and custom events.' - }, - { - href: '/docs/integrations/react/', - icon: 'react.svg', - title: 'React', - description: 'Use Elements with React and native custom events.' - }, - { - href: '/docs/integrations/solidjs/', - icon: 'solidjs.svg', - title: 'SolidJS', - description: 'Use Elements with SolidJS and Vite.' - }, - { - href: '/docs/integrations/svelte/', - icon: 'svelte.svg', - title: 'Svelte', - description: 'Use Elements with Svelte and Vite.' - }, - { - href: '/docs/integrations/typescript/', - icon: 'typescript.svg', - title: 'TypeScript', - description: 'Use Elements with TypeScript and Vite.' - }, - { - href: '/docs/integrations/vue/', - icon: 'vue.svg', - title: 'Vue', - description: 'Use Elements with Vue and Vite.' - } -]; - const renderLogo = ({ icon, iconHeight, iconSize = '36px', iconWidth, nveIcon, title, color = 'gray-denim' }) => { if (icon) { return /* html */ ` @@ -176,7 +55,7 @@ export function render(data) {

Use NVIDIA Elements across frameworks, runtimes, and Web Component tooling.

-${integrations.map(renderIntegration).join('\n')} +${Object.values(siteData.integrations).map(renderIntegration).join('\n')}
`, 'md' ); diff --git a/projects/site/src/docs/integrations/nuxt.md b/projects/site/src/docs/integrations/nuxt.md index 81df28984..b5bb3ecc7 100644 --- a/projects/site/src/docs/integrations/nuxt.md +++ b/projects/site/src/docs/integrations/nuxt.md @@ -1,7 +1,7 @@ --- { title: 'Nuxt', - description: 'Use NVIDIA Elements in a Nuxt app: register the components, configure SSR, and bind to events in Vue single-file components.', + description: 'Use NVIDIA Elements in a Nuxt app: register components, configure SSR, bind native form controls with v-model, and handle custom events.', layout: 'docs.11ty.js' } --- @@ -96,6 +96,39 @@ Properties and events then work via the standard Vue template syntax. ``` +## Form controls + +Place `v-model` on the nested native ``, not on the `nve-input`, `nve-range`, or `nve-switch` wrapper. The native control owns the value or checked state that Vue updates. + +```typescript +import { ref } from 'vue'; +import '@nvidia-elements/core/forms/define.js'; +import '@nvidia-elements/core/input/define.js'; +import '@nvidia-elements/core/range/define.js'; +import '@nvidia-elements/core/switch/define.js'; + +const name = ref(''); +const volume = ref(50); +const notifications = ref(false); +``` + +```html + + + + + + + + + + + + + + +``` + ## Layouts Use Elements within Nuxt layouts to create consistent page structures. diff --git a/projects/site/src/docs/integrations/vue.md b/projects/site/src/docs/integrations/vue.md index f223a04b4..27356bea4 100644 --- a/projects/site/src/docs/integrations/vue.md +++ b/projects/site/src/docs/integrations/vue.md @@ -1,7 +1,7 @@ --- { title: 'Vue', - description: 'Use NVIDIA Elements with Vue: register the components, bind props with v-bind, and handle custom events with v-on.', + description: 'Use NVIDIA Elements with Vue: register components, bind native form controls with v-model, and handle custom events with v-on.', layout: 'docs.11ty.js' } --- @@ -20,6 +20,39 @@ import '@nvidia-elements/core/alert/define.js'; Properties and events then work via the standard Vue template syntax. +## Form controls + +Place `v-model` on the nested native ``, not on the `nve-input`, `nve-range`, or `nve-switch` wrapper. The native control owns the value or checked state that Vue updates. + +```typescript +import { ref } from 'vue'; +import '@nvidia-elements/core/forms/define.js'; +import '@nvidia-elements/core/input/define.js'; +import '@nvidia-elements/core/range/define.js'; +import '@nvidia-elements/core/switch/define.js'; + +const name = ref(''); +const volume = ref(50); +const notifications = ref(false); +``` + +```html + + + + + + + + + + + + + + +``` + ## TypeScript types To get type checking and autocomplete for Elements in Vue templates (and to have invalid props like `size="invalid"` reported by the IDE and build), add a reference to the custom-elements Vue types. diff --git a/projects/site/src/index.11tydata.js b/projects/site/src/index.11tydata.js index 4b656d818..fedd0a6ed 100644 --- a/projects/site/src/index.11tydata.js +++ b/projects/site/src/index.11tydata.js @@ -44,6 +44,10 @@ const examples = (await ExamplesService.getAll()) const integrations = { angular: { + href: '/docs/integrations/angular/', + icon: 'angular.svg', + title: 'Angular', + description: 'Use Elements with Angular templates and events.', logo: 'angular', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/angular/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/angular.zip`, @@ -55,6 +59,10 @@ const integrations = { }) }, bundles: { + href: '/docs/integrations/bundles/', + icon: 'javascript.svg', + title: 'Bundles', + description: 'Load prebuilt Elements bundles in static pages.', logo: 'javascript', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/bundles/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/bundles.zip`, @@ -62,7 +70,36 @@ const integrations = { documentation: 'https://vite.dev', playgroundURL: null }, + cdn: { + href: '/docs/integrations/cdn/', + nveIcon: 'globe-alt-stroke', + title: 'CDN', + description: 'Load Elements from CDN-hosted npm packages.' + }, + 'custom-elements': { + href: '/docs/integrations/custom-elements/', + nveIcon: 'code', + title: 'Custom Elements', + description: 'Use Elements package metadata with Web Component tooling.' + }, + eleventy: { + href: '/docs/integrations/eleventy/', + icon: 'eleventy.svg', + title: 'Eleventy', + description: 'Use Elements with Eleventy static sites.', + logo: 'eleventy', + starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/eleventy/`, + starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/eleventy.zip`, + starterSource: `${ELEMENTS_REPO_BASE_URL}/tree/main/projects/starters/eleventy`, + documentation: 'https://www.11ty.dev/docs/', + playgroundURL: null + }, go: { + href: '/docs/integrations/go/', + icon: 'go.svg', + iconSize: '48', + title: 'Golang', + description: 'Use Elements with Go-backed web applications.', logo: 'go', starterDemo: null, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/go.zip`, @@ -71,6 +108,12 @@ const integrations = { playgroundURL: null }, 'go-htmx': { + href: '/docs/integrations/go-htmx/', + icon: 'htmx.svg', + iconHeight: '32', + iconWidth: '48', + title: 'HTMX + Go', + description: 'Use Elements with HTMX and Go template fragments.', logo: 'htmx', starterDemo: null, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/go-htmx.zip`, @@ -79,6 +122,11 @@ const integrations = { playgroundURL: null }, hugo: { + href: '/docs/integrations/hugo/', + icon: 'hugo.svg', + iconSize: '28px', + title: 'Hugo', + description: 'Use Elements in Hugo static sites.', logo: 'hugo', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/hugo/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/hugo.zip`, @@ -87,6 +135,10 @@ const integrations = { playgroundURL: null }, importmaps: { + href: '/docs/integrations/importmaps/', + icon: 'javascript.svg', + title: 'Import Maps', + description: 'Load Elements from browser-native import maps.', logo: 'javascript', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/importmaps/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/importmaps.zip`, @@ -95,6 +147,10 @@ const integrations = { playgroundURL: null }, lit: { + href: '/docs/integrations/lit/', + icon: 'lit.svg', + title: 'Lit', + description: 'Use Elements alongside Lit components and SSR.', logo: 'lit', starterDemo: null, starterDownload: null, @@ -106,6 +162,10 @@ const integrations = { }) }, 'lit-library': { + href: '/docs/integrations/lit-library/', + icon: 'lit.svg', + title: 'Lit Library', + description: 'Build a distributable Custom Element library with Lit and Elements.', logo: 'lit', starterDemo: null, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/lit-library.zip`, @@ -114,6 +174,10 @@ const integrations = { playgroundURL: null }, 'mcp-app': { + href: '/docs/integrations/mcp-apps/', + nveIcon: 'connected-blocks', + title: 'MCP Apps', + description: 'Use Elements in iframe-based MCP UI hosts.', logo: 'javascript', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/mcp-app/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/mcp-app.zip`, @@ -122,6 +186,11 @@ const integrations = { playgroundURL: null }, nextjs: { + href: '/docs/integrations/nextjs/', + icon: 'nextjs.svg', + iconSize: '28px', + title: 'NextJS', + description: 'Use Elements with NextJS and React.', logo: 'nextjs', starterDemo: null, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/nextjs.zip`, @@ -130,6 +199,11 @@ const integrations = { playgroundURL: null }, nuxt: { + href: '/docs/integrations/nuxt/', + icon: 'nuxt.svg', + iconSize: '38px', + title: 'Nuxt', + description: 'Use Elements with Nuxt applications.', logo: 'nuxt', starterDemo: null, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/nuxt.zip`, @@ -138,6 +212,10 @@ const integrations = { playgroundURL: null }, preact: { + href: '/docs/integrations/preact/', + icon: 'preact.svg', + title: 'Preact', + description: 'Use Elements with Preact JSX and custom events.', logo: 'preact', starterDemo: null, starterDownload: null, @@ -149,6 +227,10 @@ const integrations = { }) }, react: { + href: '/docs/integrations/react/', + icon: 'react.svg', + title: 'React', + description: 'Use Elements with React and native custom events.', logo: 'react', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/react/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/react.zip`, @@ -160,6 +242,10 @@ const integrations = { }) }, solidjs: { + href: '/docs/integrations/solidjs/', + icon: 'solidjs.svg', + title: 'SolidJS', + description: 'Use Elements with SolidJS and Vite.', logo: 'solidjs', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/solidjs/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/solidjs.zip`, @@ -168,6 +254,10 @@ const integrations = { playgroundURL: null }, svelte: { + href: '/docs/integrations/svelte/', + icon: 'svelte.svg', + title: 'Svelte', + description: 'Use Elements with Svelte and Vite.', logo: 'svelte', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/svelte/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/svelte.zip`, @@ -176,6 +266,10 @@ const integrations = { playgroundURL: null }, typescript: { + href: '/docs/integrations/typescript/', + icon: 'typescript.svg', + title: 'TypeScript', + description: 'Use Elements with TypeScript and Vite.', logo: 'typescript', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/typescript/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/typescript.zip`, @@ -186,6 +280,10 @@ const integrations = { }) }, vue: { + href: '/docs/integrations/vue/', + icon: 'vue.svg', + title: 'Vue', + description: 'Use Elements with Vue and Vite.', logo: 'vue', starterDemo: `${ELEMENTS_PAGES_BASE_URL}/starters/vue/`, starterDownload: `${ELEMENTS_PAGES_BASE_URL}/starters/download/vue.zip`, diff --git a/projects/starters/angular/README.md b/projects/starters/angular/README.md index 2677044b5..ca78bf90c 100644 --- a/projects/starters/angular/README.md +++ b/projects/starters/angular/README.md @@ -1,59 +1,23 @@ -# Angular +# NVIDIA Elements + Angular Starter -This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.0.5. +An interactive Angular starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). -## Development server +## Getting started -To start a local development server, run: - -```bash -ng serve -``` - -Once the server is running, open your browser and navigate to `http://localhost:4200/`. The application will automatically reload whenever you modify any of the source files. - -## Code scaffolding - -Angular CLI includes powerful code scaffolding tools. To generate a new component, run: - -```bash -ng generate component component-name +```shell +npm install +npm run dev ``` -For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run: - -```bash -ng generate --help -``` - -## Building - -To build the project run: - -```bash -ng build -``` - -This will compile your project and store the build artifacts in the `dist/` directory. By default, the production build optimizes your application for performance and speed. - -## Running unit tests - -To execute unit tests with the [Vitest](https://vitest.dev/) test runner, use the following command: - -```bash -ng test -``` - -## Running end-to-end tests - -For end-to-end (e2e) testing, run: - -```bash -ng e2e -``` +Open `http://localhost:4200/` to view the application. The development server reloads when you change a source file. -Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs. +## Tasks -## Additional Resources +| Command | Description | +| --------------- | --------------------------------- | +| `npm run dev` | Start the local development server | +| `npm run build` | Create a production build | +| `npm test` | Run the Vitest unit tests | +| `npm run lint` | Lint the application source | -For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page. +See the [Angular CLI documentation](https://angular.dev/tools/cli) for more commands. diff --git a/projects/starters/bundles/src/index.html b/projects/starters/bundles/src/index.html index 5fa14b90a..4bd0dcfd6 100644 --- a/projects/starters/bundles/src/index.html +++ b/projects/starters/bundles/src/index.html @@ -22,7 +22,7 @@ NV Elements - Catalog + Catalog Starters Gitlab diff --git a/projects/starters/eleventy/README.md b/projects/starters/eleventy/README.md index d194c86d1..2ed440269 100644 --- a/projects/starters/eleventy/README.md +++ b/projects/starters/eleventy/README.md @@ -1,7 +1,25 @@ -# Eleventy + Elements +# NVIDIA Elements + Eleventy Starter -Starter for using 11ty and Elements. This known issue currently affects watch/serve mode: https://github.com/11ty/eleventy/issues/2975 +An interactive Eleventy starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). -This demo shows how to use Eleventy, a static site generator to create many static HTML pages with common templates such as navigation or page headers. This setup is ideal for documentation sites, blogs, or even multi-page applications. +This starter uses JavaScript templates, Markdown content, and the Eleventy Vite plugin to generate a static site with shared navigation and page layouts. -Eleventy while NodeJS based, supports many different [templating language](https://www.11ty.dev/docs/languages/) options. This starter uses standard [ESM JavaScript](https://www.11ty.dev/docs/languages/javascript/) with [Markdown rendering support](https://www.11ty.dev/docs/languages/markdown/). +## Getting started + +```shell +pnpm install +pnpm run dev +``` + +Open `http://localhost:8082/elements/starters/eleventy/` to view the site. + +## Tasks + +| Command | Description | +| ----------------- | ------------------------------------------ | +| `pnpm run dev` | Start the local development server | +| `pnpm run build` | Generate the production site in `dist/` | +| `pnpm run preview` | Preview the production build | +| `pnpm run lint` | Lint the JavaScript and TypeScript source | + +See the [Eleventy documentation](https://www.11ty.dev/docs/) for information about templates, data, and configuration. diff --git a/projects/starters/eleventy/src/_layouts/index.11ty.js b/projects/starters/eleventy/src/_layouts/index.11ty.js index 5a622c4d0..055fd2805 100644 --- a/projects/starters/eleventy/src/_layouts/index.11ty.js +++ b/projects/starters/eleventy/src/_layouts/index.11ty.js @@ -22,7 +22,7 @@ export function render(data) { NV Elements - Catalog + Catalog Starters Gitlab diff --git a/projects/starters/go-htmx/README.md b/projects/starters/go-htmx/README.md index 289a64030..ee959e6da 100644 --- a/projects/starters/go-htmx/README.md +++ b/projects/starters/go-htmx/README.md @@ -1,12 +1,22 @@ -# HTMX + Go + Elements Starter +# NVIDIA Elements + HTMX + Go Starter + +An interactive HTMX and Go starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). This starter shows a minimal Go web server using Elements and HTMX. The server uses `html/template`, pre-built Elements bundles, and one fragment endpoint that returns only the HTMX swap target. -## Commands / npm scripts +## Getting started + +```shell +go run main.go +``` + +Open `http://localhost:8080/` to view the application. + +## Commands -- `dev`: `go run main.go` -- `build`: `go build -o bin main.go` -- `preview`: `go build -o bin main.go && ./bin` +- `npm run dev`: Run the local server. +- `npm run build`: Build the server binary in `bin`. +- `npm run preview`: Build and run the server binary. ## Static Assets diff --git a/projects/starters/go/README.md b/projects/starters/go/README.md index 92098d848..3fca49c98 100644 --- a/projects/starters/go/README.md +++ b/projects/starters/go/README.md @@ -1,12 +1,22 @@ -# Go + Elements Starter +# NVIDIA Elements + Go Starter + +An interactive Go starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). This starter shows a minimal Go web server using Elements. The server uses `html/template` and pre-built Elements bundles. -## Commands / npm scripts +## Getting started + +```shell +go run main.go +``` + +Open `http://localhost:8080/` to view the application. + +## Commands -- `dev`: `go run main.go` -- `build`: `go build -o bin main.go` -- `preview`: `go build -o bin main.go && ./bin` +- `npm run dev`: Run the local server. +- `npm run build`: Build the server binary in `bin`. +- `npm run preview`: Build and run the server binary. ## Static Assets diff --git a/projects/starters/hugo/README.md b/projects/starters/hugo/README.md index 87e639005..83979da6a 100644 --- a/projects/starters/hugo/README.md +++ b/projects/starters/hugo/README.md @@ -1,26 +1,25 @@ -# Hugo + Elements Starter +# NVIDIA Elements + Hugo Starter -This starter shows a minimal example of a Hugo static site generator using Elements. Hugo is using its templating system with static JS/CSS bundles provided by the Elements package. +An interactive Hugo starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). -## Getting Started +This starter uses Hugo templates with the prebuilt JavaScript and CSS bundles from the Elements packages. -Ensure [Hugo](https://gohugo.io/) are installed in your development environment. +## Getting started -```bash -# run dev server locally -hugo server +Install the package dependencies to use the starter's pinned Hugo binary: -# build site -hugo +```shell +npm install +npm run dev ``` -## Advance Usage +Open the URL printed by the Hugo development server. -This demo demonstrates a minimal Hugo static site with Elements integration using static bundles. The tradeoff with this approach is it requires less build tooling but at the cost of performance due to loading the entire package rather than optimized/tree-shaken builds. For more advanced usage with TypeScript or to have better production performance, consider using tools like [Vite](https://vite.dev/) alongside Hugo. Explore the TypeScript starter for a example resource of how to get started. +## Tasks -## Documentation +| Command | Description | +| --------------- | ---------------------------------------- | +| `npm run dev` | Start the local Hugo development server | +| `npm run build` | Generate the production site in `dist/` | -For more information on using Elements with Hugo, see: -- [Elements Documentation](https://NVIDIA.github.io/elements/) -- [Hugo Documentation](https://gohugo.io/documentation/) -- [Hugo Integration Guide](https://NVIDIA.github.io/elements/docs/integrations/hugo/) +For more information, see the [Elements Hugo integration guide](https://nvidia.github.io/elements/docs/integrations/hugo/) and the [Hugo documentation](https://gohugo.io/documentation/). diff --git a/projects/starters/hugo/layouts/baseof.html b/projects/starters/hugo/layouts/baseof.html index 0dfda98d1..7ac021d70 100644 --- a/projects/starters/hugo/layouts/baseof.html +++ b/projects/starters/hugo/layouts/baseof.html @@ -20,7 +20,7 @@ NV Elements Catalog diff --git a/projects/starters/lit-library/README.md b/projects/starters/lit-library/README.md index 7ad487adc..cb0ce8287 100644 --- a/projects/starters/lit-library/README.md +++ b/projects/starters/lit-library/README.md @@ -1,8 +1,10 @@ -# Lit Library + Elements +# NVIDIA Elements + Lit Library Starter -[Built with Vite](https://vitejs.dev/) +An interactive Lit Library starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). -To create reusable UI components that build on top of Elements, use [lit.dev](https://lit.dev) for authoring highly reusable custom elements (Web Components). This path enables your components to work in a large variety of frameworks and environments. We recommend reading the [publishing and best practices](https://lit.dev/docs/tools/publishing/) provided by the Lit team. The rest of this guide focuses on Elements integration and best practices. +[Built with Vite](https://vite.dev/) + +Use [Lit](https://lit.dev) to author reusable custom elements (Web Components) that build on Elements and work across frameworks and environments. Follow the Lit team's [publishing best practices](https://lit.dev/docs/tools/publishing/). This guide focuses on Elements integration. ## Getting Started @@ -16,6 +18,6 @@ pnpm run dev | Command | Description | | ---------------- | ------------------------------------------------------ | -| `pnpm run build` | Build library source | -| `pnpm run test` | Run library tests | -| `pnpm run ci` | Build and run all library CI requirements (build/test) | +| `pnpm run build` | Build the library source | +| `pnpm run test` | Run the library tests | +| `pnpm run lint` | Lint the library source | diff --git a/projects/starters/mcp-app/README.md b/projects/starters/mcp-app/README.md index 6d73c08f1..69c97dd01 100644 --- a/projects/starters/mcp-app/README.md +++ b/projects/starters/mcp-app/README.md @@ -1,4 +1,4 @@ -# NVIDIA Elements MCP App Starter +# NVIDIA Elements + MCP App Starter A minimal MCP App using NVIDIA Elements, TypeScript, and Vite. @@ -6,6 +6,7 @@ A minimal MCP App using NVIDIA Elements, TypeScript, and Vite. ```shell npm i +npm run build npm run dev ``` @@ -28,6 +29,6 @@ After building the app, configure a local MCP client with the compiled stdio ent | Command | Description | | --------------- | ------------------------------------------------ | -| `npm run build` | Build the single-file app resource and server JS | -| `npm run dev` | Build, then open the MCP Inspector | -| `npm run lint` | Run eslint | +| `npm run build` | Build the single-file app resource and server JavaScript | +| `npm run dev` | Open the MCP Inspector with the built server | +| `npm run lint` | Lint the TypeScript source | diff --git a/projects/starters/mpa/README.md b/projects/starters/mpa/README.md index 86f1a3b8d..598b6698a 100644 --- a/projects/starters/mpa/README.md +++ b/projects/starters/mpa/README.md @@ -1,8 +1,10 @@ -# Multi Page App (MPA) Starter +# NVIDIA Elements + Multi-Page App Starter -[Built with Vite](https://vitejs.dev/) +An interactive multi-page app starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). -This demo app shows how to build a standard mult-page application. +[Built with Vite](https://vite.dev/) + +This demo shows how HTML entry points can share Elements styles and component registrations. ## Getting Started @@ -13,3 +15,12 @@ npm i ```shell npm run dev ``` + +## Tasks + +| Command | Description | +| ----------------- | ----------------------------------- | +| `npm run dev` | Start the local development server | +| `npm run build` | Create a production build | +| `npm run preview` | Preview the production build | +| `npm run lint` | Lint the TypeScript source | diff --git a/projects/starters/mpa/src/about/index.html b/projects/starters/mpa/src/about/index.html index 5883723ab..fee1e7c7a 100644 --- a/projects/starters/mpa/src/about/index.html +++ b/projects/starters/mpa/src/about/index.html @@ -1,10 +1,10 @@ - Elements + Multi Page App + NVIDIA Elements + Multi Page App - + @@ -14,7 +14,7 @@ NV Elements - Catalog + Catalog Starters Gitlab diff --git a/projects/starters/mpa/src/index.html b/projects/starters/mpa/src/index.html index 49f90ba46..e71c4126f 100644 --- a/projects/starters/mpa/src/index.html +++ b/projects/starters/mpa/src/index.html @@ -1,7 +1,7 @@ - Elements + Multi Page App + NVIDIA Elements + Multi Page App @@ -14,7 +14,7 @@ NV Elements - Catalog + Catalog Starters Gitlab diff --git a/projects/starters/mpa/src/settings/index.html b/projects/starters/mpa/src/settings/index.html index bb5ee3be4..fa1d8f078 100644 --- a/projects/starters/mpa/src/settings/index.html +++ b/projects/starters/mpa/src/settings/index.html @@ -1,10 +1,10 @@ - Elements + Multi Page App + NVIDIA Elements + Multi Page App - + @@ -14,7 +14,7 @@ NV Elements - Catalog + Catalog Starters Gitlab diff --git a/projects/starters/nextjs/README.md b/projects/starters/nextjs/README.md index 72315c58e..6b24a7fe2 100644 --- a/projects/starters/nextjs/README.md +++ b/projects/starters/nextjs/README.md @@ -1,38 +1,24 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/pages/api-reference/create-next-app). +# NVIDIA Elements + Next.js Starter -## Getting Started +An interactive Next.js starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). -First, run the development server: +This starter uses the Next.js Pages Router and exports a static site. -```bash +## Getting started + +```shell +npm install npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file. - -[API routes](https://nextjs.org/docs/pages/building-your-application/routing/api-routes) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`. - -The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/pages/building-your-application/routing/api-routes) instead of React pages. - -## Learn More - -To learn more about Next.js, take a look at the following resources: - -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn-pages-router) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +Open `http://localhost:3000/elements/starters/nextjs` to view the application. Edit `src/pages/index.tsx` to update the page. -## Deploy on Vercel +## Tasks -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +| Command | Description | +| --------------- | -------------------------------------------- | +| `npm run dev` | Start the local Next.js development server | +| `npm run build` | Export the production site to `dist/` | +| `npm run lint` | Lint the TypeScript and TSX source | -Check out our [Next.js deployment documentation](https://nextjs.org/docs/pages/building-your-application/deploying) for more details. +See the [Next.js documentation](https://nextjs.org/docs) for more information. diff --git a/projects/starters/nextjs/src/pages/index.tsx b/projects/starters/nextjs/src/pages/index.tsx index 72130238f..452a6ba06 100644 --- a/projects/starters/nextjs/src/pages/index.tsx +++ b/projects/starters/nextjs/src/pages/index.tsx @@ -14,7 +14,7 @@ export default function Home() { NV Elements - Catalog + Catalog Starters Gitlab diff --git a/projects/starters/nuxt/README.md b/projects/starters/nuxt/README.md index 25b58212c..57369dbc6 100644 --- a/projects/starters/nuxt/README.md +++ b/projects/starters/nuxt/README.md @@ -1,6 +1,6 @@ -# Nuxt Minimal Starter +# NVIDIA Elements + Nuxt Starter -Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more. +An interactive Nuxt starter for the [NVIDIA Elements design system](https://nvidia.github.io/elements/). ## Setup diff --git a/projects/starters/nuxt/app/layouts/default.vue b/projects/starters/nuxt/app/layouts/default.vue index b440452a4..5964ab8f6 100644 --- a/projects/starters/nuxt/app/layouts/default.vue +++ b/projects/starters/nuxt/app/layouts/default.vue @@ -1,10 +1,10 @@