fix(core): improve api custom elements schema

projects/core/src/accordion/accordion.ts

@@ -30,7 +30,7 @@ import accordionGroupStyleSheet from './accordion-group.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/accordion/
  * @since 0.12.0
  * @entrypoint \@nvidia-elements/core/accordion
- * @slot - default content slot
+ * @slot - Heading text and supporting content that labels the accordion section.
  * @slot prefix - slot for prefix content
  * @slot suffix - slot for suffix content
  * @cssprop --cursor
@@ -57,6 +57,7 @@ export class AccordionHeader extends LitElement {
     `;
   }
 
+  /** @private */
   @hostAttr() slot = 'header';
 
   connectedCallback() {
@@ -101,14 +102,13 @@ export class AccordionContent extends LitElement {
  * @command --open - use to open the accordion
  * @command --close - use to close the accordion
  * @command --toggle - use to toggle the accordion
- * @slot - This is a default/unnamed slot for accordion content
+ * @slot - Content displayed in the collapsible region, typically an `nve-accordion-content` element.
  * @slot icon-button - icon elements to display for expand/collapse
  * @slot header - header element (Use `accordion-header` or custom content)
- * @slot content - content element (Use `accordion-content` or custom content)
  * @cssprop --background
  * @cssprop --color
  * @cssprop --border-radius
- * @cssprop --header-padding
+ * @cssprop --header-padding - Padding around the header content.
  * @cssprop --cursor
  * @cssprop --transition
  * @csspart icon-button - The toggle icon button element
@@ -244,7 +244,9 @@ export class AccordionGroup extends LitElement {
    */
   @property({ type: Boolean, attribute: 'behavior-expand-single' }) behaviorExpandSingle = false;
 
-  /** flat (Borderless, container-less accordions), full (default), or inset (Rounded corner, contained accordion) */
+  /**
+   * Controls the container style applied to child accordions. `flat` removes the visual container, `inset` adds rounded containment, and omission uses the default divided presentation.
+   */
   @property({ type: String, reflect: true }) container?: Extract<Container, 'flat' | 'inset'>;
 
   static readonly metadata = {

projects/core/src/avatar/avatar-group.ts

@@ -10,7 +10,7 @@ import styles from './avatar-group.css?inline';
  * @description An avatar group displays a collection of user avatars in a compact and organized layout, showcasing many participants or contributors in a space-efficient way.
  * @since 1.20.0
  * @entrypoint \@nvidia-elements/core/avatar
- * @slot - default slot for content
+ * @slot - `nve-avatar` elements that represent the group members.
  * @aria https://www.w3.org/WAI/ARIA/apg/patterns/alert/
  *
  */

projects/core/src/avatar/avatar.ts

@@ -14,7 +14,7 @@ import styles from './avatar.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/avatar/
  * @since 1.20.0
  * @entrypoint \@nvidia-elements/core/avatar
- * @slot - default slot for content
+ * @slot - Initials, an image, or other content that identifies the represented user or bot.
  * @cssprop --background
  * @cssprop --color
  * @cssprop --border-radius

projects/core/src/badge/badge.ts

@@ -25,7 +25,7 @@ import styles from './badge.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/badge/
  * @since 0.11.0
  * @entrypoint \@nvidia-elements/core/badge
- * @slot - default slot for content
+ * @slot - Short text that communicates the badge status.
  * @slot prefix-icon - slot for prefix icon
  * @slot suffix-icon - slot for suffix icon
  * @cssprop --background

projects/core/src/card/card.ts

@@ -55,7 +55,7 @@ export class Card extends LitElement implements ContainerElement {
  * @documentation https://nvidia.github.io/elements/docs/elements/card/
  * @since 0.1.3
  * @entrypoint \@nvidia-elements/core/card
- * @slot - default slot
+ * @slot - Card title, supporting text, and optional action controls.
  * @cssprop --padding
  * @cssprop --border-bottom
  * @cssprop --line-height
@@ -72,6 +72,7 @@ export class CardHeader extends LitElement {
     parents: ['nve-card']
   };
 
+  /** @private */
   @hostAttr() slot = 'header';
 
   render() {
@@ -133,6 +134,7 @@ export class CardFooter extends LitElement {
     parents: ['nve-card']
   };
 
+  /** @private */
   @hostAttr() slot = 'footer';
 
   render() {

projects/core/src/chat-message/chat-message.ts

@@ -15,7 +15,7 @@ import globalStyles from './chat-message.global.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/chat-message/
  * @since 1.25.0
  * @entrypoint \@nvidia-elements/core/chat-message
- * @slot - default slot for content
+ * @slot - The message body displayed between the prefix and suffix content.
  * @slot prefix - for avatar/img content
  * @slot suffix - for avatar/img content
  * @cssprop --background
@@ -37,10 +37,12 @@ export class ChatMessage extends LitElement {
     version: '0.0.0'
   };
 
+  /** Applies a transparent background and reduced horizontal padding for embedding the message in another container. */
   @property({ type: String, reflect: true }) container: 'flat';
 
   @property({ type: String, reflect: true }) color: Color;
 
+  /** Removes the border radius from the selected message corner to indicate the speaker direction. */
   @property({ type: String, reflect: true, attribute: 'arrow-position' }) arrowPosition:
     | 'top-start'
     | 'top-end'

projects/core/src/copy-button/copy-button.ts

@@ -17,7 +17,7 @@ import styles from './copy-button.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/copy-button/
  * @since 1.1.4
  * @entrypoint \@nvidia-elements/core/copy-button
- * @slot - default
+ * @slot - Text label displayed before the copy icon.
  * @slot icon - slot for custom icon
  * @cssprop --color
  * @cssprop --background

projects/core/src/dialog/dialog.ts

@@ -29,7 +29,7 @@ import styles from './dialog.css?inline';
  * @event toggle - Dispatched on a popover element just after showing or hiding. [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event)
  * @event open - Dispatched when the dialog opens.
  * @event close - Dispatched when the dialog closes.
- * @slot - default content slot
+ * @slot - Dialog body content displayed between the header and footer.
  * @cssprop --border
  * @cssprop --border-radius
  * @cssprop --background

projects/core/src/drawer/drawer.ts

@@ -26,7 +26,7 @@ import styles from './drawer.css?inline';
  * @event toggle - Dispatched on a popover element just after showing or hiding. [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event)
  * @event open - Dispatched when the drawer opens.
  * @event close - Dispatched when the drawer closes.
- * @slot - default content slot
+ * @slot - Drawer body content displayed between the header and footer.
  * @cssprop --border
  * @cssprop --background
  * @cssprop --color

projects/core/src/dropdown-group/dropdown-group.ts

@@ -23,8 +23,6 @@ import globalStyles from './dropdown-group.global.css?inline';
  * @slot - default slot for dropdown content
  * @event open - Dispatched when a dropdown in the group opens
  * @event close - Dispatched when a dropdown in the group closes
- * @cssprop --nve-dropdown-group-spacing
- * @cssprop --nve-dropdown-group-transition
  * @cssprop --arrow-transform - Transform applied to the popover arrow
  * @aria https://www.w3.org/WAI/ARIA/apg/patterns/menubar/
  */
@@ -114,6 +112,7 @@ export class DropdownGroup extends LitElement {
     }
   }
 
+  /** Closes every descendant dropdown in the group. */
   close() {
     this.querySelectorAll('nve-dropdown').forEach(d => d.hidePopover());
   }

projects/core/src/dropdown/dropdown.ts

@@ -103,6 +103,7 @@ export class Dropdown extends LitElement {
   /** @private */
   @property({ type: String, attribute: 'popover-type' }) popoverType: PopoverType = 'auto';
 
+  /** @private */
   @query('.arrow') popoverArrow: HTMLElement;
 
   #i18nController: I18nController<this> = new I18nController<this>(this);

projects/core/src/dropzone/dropzone.ts

@@ -16,30 +16,35 @@ import styles from './dropzone.css?inline';
 import { FormControlMixin } from '@nvidia-elements/forms/mixins';
 import { fileTypeValidator, fileSizeValidator, getFileTypeSpecifiers } from './dropzone.util';
 
+/* eslint-disable jsdoc/no-types */
+// Explicit JSDoc type because the CEM analyzer loses the inherited generic specialization.
+
 /**
  * @element nve-dropzone
  * @description A dropzone form control that enables users to drag and drop files onto it.
  * @documentation https://nvidia.github.io/elements/docs/elements/dropzone/
  * @since 1.29.0
  * @entrypoint \@nvidia-elements/core/dropzone
+ * @property {File[]} value - Files selected or dropped by the user. Assign files through the JavaScript property; the HTML `value` attribute is not supported.
  * @event change - Dispatched when the value has changed (files located in event.target)
- * @slot - use only when custom messaging requires it
+ * @slot - Custom messaging that replaces the default upload instructions.
  * @cssprop --background
  * @cssprop --border-color
  * @cssprop --border-radius
  * @cssprop --padding
  * @cssprop --min-height
  * @cssprop --color
- * @slot icon - default slot for icon
- * @slot content - default slot for content
+ * @slot icon - Custom icon that replaces the default upload icon.
  * @csspart icon - The upload icon element
  * @aria https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file
  */
 @scopedRegistry()
 export class Dropzone extends FormControlMixin<typeof LitElement, File[]>(LitElement) {
+  /** Comma-separated file extensions or MIME types accepted by the dropzone. */
   @property()
   accept: string = `image/gif, image/jpeg, image/png, image/svg+xml`;
 
+  /** File size limit in bytes. */
   @property({ attribute: 'max-file-size', type: Number })
   maxFileSize: number = 2 * 1024 ** 2;
 
@@ -76,6 +81,7 @@ export class Dropzone extends FormControlMixin<typeof LitElement, File[]>(LitEle
     [Icon.metadata.tag]: Icon
   };
 
+  /** @protected */
   formResetCallback() {
     this.value = [];
     this.requestUpdate();

projects/core/src/format-number/format-number.ts

@@ -110,7 +110,8 @@ export class FormatNumber extends LitElement {
   /**
    * Grouping separators: 'auto' | 'always' | 'min2' | 'true' | 'false'.
    */
-  @property({ type: String, attribute: 'use-grouping' }) useGrouping?: string;
+  @property({ type: String, attribute: 'use-grouping' })
+  useGrouping?: 'auto' | 'always' | 'min2' | 'true' | 'false' | boolean;
 
   /**
    * Pad fraction output to at least this many digits (0-20).

projects/core/src/forms/control-message/control-message.ts

@@ -22,7 +22,7 @@ const statusIcons = {
  * @documentation https://nvidia.github.io/elements/docs/elements/control/
  * @since 0.3.0
  * @entrypoint \@nvidia-elements/core/forms
- * @slot - default slot for content
+ * @slot - Validation or supporting message text for the associated control.
  * @cssprop --color
  * @cssprop --font-weight
  * @cssprop --font-size
@@ -54,6 +54,7 @@ export class ControlMessage extends LitElement {
     [Icon.metadata.tag]: Icon
   };
 
+  /** @private */
   @hostAttr() slot = 'messages';
 
   render() {

projects/core/src/grid/cell/cell.ts

@@ -11,7 +11,7 @@ import styles from './cell.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/data-grid/
  * @since 0.11.0
  * @entrypoint \@nvidia-elements/core/grid
- * @slot - default slot for content
+ * @slot - Data or interactive controls displayed within the cell.
  * @cssprop --background
  * @cssprop --color
  * @cssprop --padding

projects/core/src/grid/column/column.ts

@@ -14,7 +14,7 @@ import styles from './column.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/data-grid/
  * @since 0.11.0
  * @entrypoint \@nvidia-elements/core/grid
- * @slot - default slot for content
+ * @slot - Column heading text or controls.
  * @slot actions - slot for column actions
  * @cssprop --color
  * @cssprop --padding

projects/core/src/grid/footer/footer.ts

@@ -10,7 +10,7 @@ import styles from './footer.css?inline';
  * @since 0.11.0
  * @entrypoint \@nvidia-elements/core/grid
  * @description Grid footer displays contextual information or user actions such as pagination.
- * @slot - default slot for content
+ * @slot - Grid summary, pagination, or other footer controls.
  * @cssprop --background
  * @cssprop --color
  * @cssprop --padding
@@ -30,6 +30,7 @@ export class GridFooter extends LitElement {
   /** @private */
   _internals: ElementInternals;
 
+  /** @private */
   @hostAttr() slot = 'footer';
 
   render() {

projects/core/src/grid/grid.ts

@@ -29,7 +29,7 @@ import globalStyles from './grid.global.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/data-grid/
  * @since 0.11.0
  * @entrypoint \@nvidia-elements/core/grid
- * @slot - default slot for content
+ * @slot - `nve-grid-header`, `nve-grid-row`, and `nve-grid-placeholder` elements.
  * @slot footer - slot for grid-footer or toolbar
  * @cssprop --background
  * @cssprop --color

projects/core/src/grid/placeholder/placeholder.ts

@@ -10,7 +10,7 @@ import styles from './placeholder.css?inline';
  * @since 0.11.0
  * @entrypoint \@nvidia-elements/core/grid
  * @description Placeholder displays a message while data loads for the grid or shows empty states for datasets.
- * @slot - default slot for content
+ * @slot - Loading or empty-state message displayed in place of grid rows.
  * @cssprop --color
  * @cssprop --padding
  * @aria https://www.w3.org/WAI/ARIA/apg/patterns/grid/

projects/core/src/internal/types/index.ts

@@ -333,10 +333,10 @@ export interface NveElement {
   /** Determines the alignment of the popover relative to the provided anchor element. */
   alignment?: 'start' | 'end' | 'center';
 
-  /** Provides the element that the popover should position relative to. Anchor can accept a idref string within the same render root or a HTMLElement DOM reference. */
+  /** Provides the element that the popover should position relative to. Set the property to an element or its ID within the same render root. The HTML attribute accepts only the element ID. */
   anchor?: string | HTMLElement;
 
-  /** Defines what element triggers an `open` interaction event. A trigger can accept a idref string within the same render root or a HTMLElement DOM reference. */
+  /** Defines the element that triggers an `open` interaction event. Set the property to an element or its ID within the same render root. The HTML attribute accepts only the element ID. */
   trigger?: string | HTMLElement;
 
   /** Defines named content areas where users can insert custom markup into the element.
@@ -360,7 +360,7 @@ export interface NveElement {
   closeTimeout?: number;
 
   /**
-   * Sets the delay in milliseconds before the element emits a `open` event.
+   * Sets the delay in milliseconds before the element emits an `open` event.
    * - `0` - Keyboard focus interactions (always immediate for accessibility).
    * - `500` - Dense interfaces with many tooltips to reduce visual noise and prevent accidental triggers.
    */

projects/core/src/logo/logo.ts

@@ -13,7 +13,7 @@ import styles from './logo.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/logo/
  * @since 0.10.0
  * @entrypoint \@nvidia-elements/core/logo
- * @slot - default slot for content
+ * @slot - Text, an image, or other visual content representing the brand or application.
  * @cssprop --background
  * @cssprop --gap
  * @cssprop --color

projects/core/src/menu/menu-item.ts

@@ -13,7 +13,7 @@ import styles from './menu-item.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/menu/
  * @since 0.11.0
  * @entrypoint \@nvidia-elements/core/menu
- * @slot - default slot for content
+ * @slot - Label and supporting content for the menu option.
  * @slot suffix - slot for suffix icon
  * @cssprop --background
  * @cssprop --border-radius
@@ -36,6 +36,7 @@ import styles from './menu-item.css?inline';
 export class MenuItem extends ButtonFormControlMixin(LitElement) {
   static styles = useStyles([styles]);
 
+  /** Applies danger styling to destructive or high-risk menu actions. */
   @property({ type: String, reflect: true }) status: 'danger';
 
   static readonly metadata = {

projects/core/src/notification/notification.ts

@@ -28,7 +28,7 @@ import styles from './notification.css?inline';
  * @event toggle - Dispatched on a popover element just after showing or hiding. [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event)
  * @event open - Dispatched when the notification opens.
  * @event close - Dispatched when the notification closes.
- * @slot - default content slot
+ * @slot - The message communicated by the notification.
  * @slot icon - content slot for the status icon
  * @cssprop --border-radius
  * @cssprop --background

projects/core/src/page-loader/page-loader.ts

@@ -14,7 +14,7 @@ import styles from './page-loader.css?inline';
  * @documentation https://nvidia.github.io/elements/docs/elements/page-loader/
  * @since 0.19.0
  * @entrypoint \@nvidia-elements/core/page-loader
- * @slot - default slot for content
+ * @slot - Loading status text displayed with the progress indicator.
  * @cssprop --gap
  * @cssprop --animation-duration - Duration of page loader open/close animations
  * @csspart progress-ring - The progress ring element

projects/core/src/page/page-panel/page-panel-footer.ts

@@ -27,6 +27,7 @@ export class PagePanelFooter extends LitElement {
     version: '0.0.0'
   };
 
+  /** @private */
   @hostAttr() slot = 'footer';
 
   render() {

projects/core/src/page/page-panel/page-panel-header.ts

@@ -26,6 +26,7 @@ export class PagePanelHeader extends LitElement {
     version: '0.0.0'
   };
 
+  /** @private */
   @hostAttr() slot = 'header';
 
   render() {

projects/core/src/page/page-panel/page-panel.ts

@@ -23,7 +23,7 @@ import globalStyles from './page-panel.global.css?inline';
  * @since 1.15.0
  * @event open - Dispatched after an invoker command removes `hidden` and opens the panel.
  * @event close - Dispatched after an invoker command sets `hidden` and closes the panel.
- * @slot - default content slot
+ * @slot - `nve-page-panel-content` elements that provide the panel body.
  * @slot actions - slot for action / dismiss buttons
  * @command --open - Removes `hidden` and dispatches `open`.
  * @command --close - Sets `hidden` and dispatches `close`.