@inglorious/ui 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ui",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A design system for Inglorious Web with render-function components and customizable themes",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -280,9 +280,9 @@
     "**/*.css"
   ],
   "peerDependencies": {
-    "@inglorious/charts": "4.0.0",
+    "@inglorious/charts": "4.0.1",
     "@inglorious/utils": "3.7.3",
-    "@inglorious/web": "4.5.0"
+    "@inglorious/web": "4.5.1"
   },
   "devDependencies": {
     "@fontsource/material-symbols-outlined": "^5.2.36",
@@ -296,9 +296,9 @@
     "storybook": "^10.2.19",
     "vite": "^7.3.1",
     "vitest": "^4.0.15",
-    "@inglorious/web": "4.5.0",
+    "@inglorious/eslint-config": "1.1.2",
     "@inglorious/store": "9.6.0",
-    "@inglorious/eslint-config": "1.1.2"
+    "@inglorious/web": "4.5.1"
   },
   "engines": {
     "node": ">= 22"

package/src/controls/button/template.js

@@ -8,8 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
- * Button type for Inglorious Web.
- *
+ * Renders a themed button for actions and form submission.
+ * Supports variants, sizes, shapes, pressed state, and full-width layout.
  * @example
  * // Stateless usage
  * button.render({ children: 'Click me', variant: 'primary' })

package/src/controls/button-group/template.js

@@ -9,8 +9,8 @@ import { applyElementProps } from "../../shared/applyElementProps.js"
 import { button } from "../button/index.js"
 
 /**
- * Button group control for grouped actions.
- *
+ * Renders a grouped set of buttons with optional single or multi selection.
+ * Handles attached layout, selection state, and per-item overrides.
  * @param {ButtonGroupProps} props
  * @returns {TemplateResult}
  */

package/src/controls/checkbox/template.js

@@ -8,8 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
- * Checkbox control for boolean values.
- *
+ * Renders a labeled checkbox for boolean input.
+ * Supports disabled/required states plus size and color variants.
  * @param {CheckboxProps} props
  * @returns {TemplateResult}
  */

package/src/controls/combobox/template.js

@@ -19,11 +19,22 @@ const NO_FOCUSED_INDEX = -1
 
 export const combobox = {
   /**
-   * Select control render function.
+   * Main entrypoint for the combobox control. It renders the wrapper, label, control, and dropdown when open.
+   * Comboboxes support search, single or multi-select values, and clearable selection.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderCombobox(props)
+  },
+
+  /**
+   * Main entrypoint for the combobox control. It renders the wrapper, label, control, and dropdown when open.
+   * Comboboxes support search, single or multi-select values, and clearable selection.
+   * @param {ComboboxProps} props
+   * @returns {TemplateResult}
+   */
+  renderCombobox(props) {
     return html`<div
       class=${classMap({
         "iw-combobox": true,
@@ -40,7 +51,8 @@ export const combobox = {
   },
 
   /**
-   * Render trigger control.
+   * Renders the clickable control element that shows the current selection and toggles the dropdown.
+   * Handles placeholder, clear button, and the open/disabled state.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */
@@ -85,7 +97,8 @@ export const combobox = {
   },
 
   /**
-   * Render single selected value.
+   * Renders the currently selected value in single-select mode.
+   * Falls back to the placeholder when no value is selected.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */
@@ -108,7 +121,8 @@ export const combobox = {
   },
 
   /**
-   * Render multi selected value tags.
+   * Renders the selected values in multi-select mode as a row of tags.
+   * Falls back to the placeholder when the selection is empty.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */
@@ -129,7 +143,8 @@ export const combobox = {
   },
 
   /**
-   * Render a selected multi-value tag.
+   * Renders a single selected tag in multi-select mode.
+   * Used to customize chip styling and remove behavior.
    * @param {ComboboxProps} props
    * @param {string|number} value
    * @returns {TemplateResult}
@@ -158,7 +173,8 @@ export const combobox = {
   },
 
   /**
-   * Render dropdown.
+   * Renders the dropdown panel that contains search input, options, and empty/loading states.
+   * Shown only when the combobox is open.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */
@@ -195,7 +211,8 @@ export const combobox = {
   },
 
   /**
-   * Render search input.
+   * Renders the optional search input used to filter options.
+   * Emits search change events as the user types.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */
@@ -214,7 +231,8 @@ export const combobox = {
   },
 
   /**
-   * Render options list.
+   * Renders the list of available options in the dropdown.
+   * Delegates each option to `renderOption` for customization.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */
@@ -231,7 +249,8 @@ export const combobox = {
   },
 
   /**
-   * Render an option row.
+   * Renders a single option row, including selection and focus styling.
+   * Handles click/selection for the option.
    * @param {ComboboxProps} props
    * @param {{ option: ComboboxOption, index: number }} payload
    * @returns {TemplateResult}
@@ -272,7 +291,8 @@ export const combobox = {
   },
 
   /**
-   * Render loading state.
+   * Renders the loading state shown while options are being fetched or filtered.
+   * Displayed when `isLoading` is true.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */
@@ -281,7 +301,8 @@ export const combobox = {
   },
 
   /**
-   * Render no options state.
+   * Renders the empty state when no options match the search or list is empty.
+   * Uses the `noOptionsMessage` prop when provided.
    * @param {ComboboxProps} props
    * @returns {TemplateResult}
    */

package/src/controls/fab/template.js

@@ -8,8 +8,8 @@ import { html } from "@inglorious/web"
 import { button } from "../button/index.js"
 
 /**
- * Floating action button for primary contextual actions.
- *
+ * Renders a floating action button for primary contextual actions.
+ * Supports extended mode to display label text alongside the icon.
  * @param {FabProps} props
  * @returns {TemplateResult}
  */

package/src/controls/icon-button/template.js

@@ -8,8 +8,8 @@ import { html } from "@inglorious/web"
 import { button } from "../button/index.js"
 
 /**
- * Icon button wrapper built on top of the base button renderer.
- *
+ * Renders a button optimized for icons with optional label and icon placement.
+ * Built on top of the base button renderer for consistent theming.
  * @param {IconButtonProps} props
  * @returns {TemplateResult}
  */

package/src/controls/input/template.js

@@ -8,8 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
- * Input component for Inglorious Web.
- *
+ * Renders a labeled input field with optional icons, hint text, and error messaging.
+ * Supports disabled/readonly/required states and emits `onChange` on input.
  * @example
  * // Stateless usage
  * input.render({ label: 'Email', type: 'email', placeholder: 'you@example.com' })

package/src/controls/radio-group/template.js

@@ -8,8 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
- * Radio group control for selecting one option.
- *
+ * Renders a group of radio options for single selection.
+ * Supports horizontal/vertical layouts and disabled state.
  * @param {RadioGroupProps} props
  * @returns {TemplateResult}
  */

package/src/controls/rating/template.js

@@ -10,8 +10,8 @@ const DEFAULT_MAX = 5
 const INDEX_TO_RATING = 1
 
 /**
- * Rating control rendered as clickable symbols.
- *
+ * Renders a star (or custom symbol) rating control.
+ * Supports max value, read-only/disabled states, and emits selection changes.
  * @param {RatingProps} props
  * @returns {TemplateResult}
  */

package/src/controls/select/template.js

@@ -9,8 +9,8 @@ import { applyElementProps } from "../../shared/applyElementProps.js"
 import { formatOption, getOptionValue, isOptionSelected } from "./helpers.js"
 
 /**
- * Select component for Inglorious Web.
- *
+ * Renders a styled native select control with optional single or multi-select modes.
+ * Options can be primitives or objects and are rendered with consistent theming.
  * @example
  * // Stateless usage
  * select.render({ options: ['true', 'false'], value: 'true' })

package/src/controls/slider/template.js

@@ -13,8 +13,8 @@ const DEFAULT_MAX = 100
 const DEFAULT_STEP = 1
 
 /**
- * Slider control based on native range input.
- *
+ * Renders a range slider with optional label and current value display.
+ * Supports min/max/step, color, disabled state, and full-width layout.
  * @param {SliderProps} props
  * @returns {TemplateResult}
  */

package/src/controls/switch/template.js

@@ -8,8 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
- * Switch control implemented with a checkbox input.
- *
+ * Renders a toggle switch backed by a checkbox input.
+ * Use it for boolean settings with optional labels and disabled state.
  * @param {SwitchProps} props
  * @returns {TemplateResult}
  */

package/src/data-display/avatar/template.js

@@ -6,7 +6,8 @@
 import { classMap, html, styleMap } from "@inglorious/web"
 
 /**
- * Avatar component.
+ * Renders an avatar with image, initials, or fallback content.
+ * Supports size, shape, and automatic background color generation.
  * @param {AvatarProps} props
  * @returns {TemplateResult}
  */

package/src/data-display/badge/template.js

@@ -1,9 +1,16 @@
 /**
  * @typedef {import('../../../types/data-display/badge').BadgeProps} BadgeProps
+ * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
 import { classMap, html, styleMap } from "@inglorious/web"
 
+/**
+ * Renders a compact badge for status, labels, or counts.
+ * Supports color, variant, size, shape, and optional ring styling.
+ * @param {BadgeProps} props
+ * @returns {TemplateResult}
+ */
 export function render(props) {
   const {
     children,

package/src/data-display/chip/template.js

@@ -1,9 +1,16 @@
 /**
  * @typedef {import('../../../types/data-display/chip').ChipProps} ChipProps
+ * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
 import { classMap, html } from "@inglorious/web"
 
+/**
+ * Renders a compact chip label with optional remove action.
+ * Use chips for tags, filters, or selected values.
+ * @param {ChipProps} props
+ * @returns {TemplateResult}
+ */
 export function render(props) {
   const {
     children,

package/src/data-display/data-grid/template.js

@@ -27,7 +27,8 @@ const LAST_PAGE = 1
 
 export const dataGrid = {
   /**
-   * Main entrypoint. Allows override to wire to the store.
+   * Main entrypoint for the data grid template. It delegates to the base grid renderer so overrides can still reuse it.
+   * Data grids support sorting, filtering, selection, pagination, and optional virtualization.
    * @param {DataGridProps} props The data grid props.
    * @returns {TemplateResult} The rendered data grid.
    */
@@ -36,7 +37,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders the data grid component.
+   * Renders the data grid container and wires the header, body, and footer regions.
+   * This is the canonical renderer that custom `render()` overrides should call.
    * @param {DataGridProps} props The data grid props.
    * @returns {TemplateResult} The rendered data grid.
    */
@@ -55,7 +57,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders the data grid header.
+   * Renders the grid header region, including optional toolbar and column headers.
+   * Column rendering is delegated to `renderHeaderColumn`.
    * @param {DataGridProps} props The data grid props.
    * @returns {TemplateResult} The rendered header.
    */
@@ -74,7 +77,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders the toolbar above the header row.
+   * Renders the toolbar row that contains search, bulk actions, and filtering controls.
+   * Override to customize the global header tools.
    * @param {DataGridProps} props The data grid props.
    * @returns {TemplateResult}
    */
@@ -85,7 +89,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders a single column in the header.
+   * Renders a single column header cell, including sorting and filter affordances.
+   * Override to customize header labels or controls per column.
    * @param {DataGridProps} props The data grid props.
    * @param {object} payload The payload.
    * @param {Column} payload.column The column definition.
@@ -118,7 +123,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders the search bar.
+   * Renders the global search input shown in the grid toolbar.
+   * Used when `search` is enabled in the grid props.
    * @param {DataGridProps} props The data grid props.
    * @returns {TemplateResult} The rendered search bar.
    */
@@ -137,7 +143,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders the data grid body with rows.
+   * Renders the grid body, either as a standard list of rows or as a virtualized list.
+   * Row rendering is delegated to `renderRow`.
    * @param {DataGridProps} props The data grid props.
    * @returns {TemplateResult} The rendered data grid body.
    */
@@ -187,7 +194,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders a single row in the data grid body.
+   * Renders a single data row and wires row click/selection handlers.
+   * Cells are delegated to `renderCell` for customization.
    * @param {DataGridProps} props The data grid props.
    * @param {object} payload The payload.
    * @param {Row} payload.row The row data.
@@ -220,7 +228,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders a single cell within a row.
+   * Renders a single cell container and delegates the value to `renderValue`.
+   * Override to customize per-column cell structure.
    * @param {DataGridProps} props The data grid props.
    * @param {object} payload The payload.
    * @param {any} payload.cell The cell data.
@@ -243,7 +252,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders the value within a cell. This can be overridden for custom formatting.
+   * Renders the raw cell value for a column.
+   * Override to format values or inject custom content.
    * @param {DataGridProps} _props The data grid props (ignored).
    * @param {object} payload The payload.
    * @param {any} payload.value The value to render.
@@ -254,7 +264,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders the data grid footer.
+   * Renders the grid footer, including pagination controls and page size selectors.
+   * Footer elements are delegated to `renderPagination` and `renderPageSize`.
    * @param {DataGridProps} props The data grid props.
    * @returns {TemplateResult} The rendered footer.
    */
@@ -281,7 +292,8 @@ export const dataGrid = {
   },
 
   /**
-   * Renders the pagination controls.
+   * Renders pagination controls for the grid footer.
+   * Override to provide custom paging UI.
    * @param {DataGridProps} props The data grid props.
    * @param {object} pagination The pagination info object from `getPaginationInfo`.
    * @returns {TemplateResult} The rendered pagination controls.

package/src/data-display/divider/template.js

@@ -1,9 +1,16 @@
 /**
  * @typedef {import('../../../types/data-display/divider').DividerProps} DividerProps
+ * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
 import { classMap, html } from "@inglorious/web"
 
+/**
+ * Renders a horizontal or vertical divider line.
+ * Supports inset styling for aligned content blocks.
+ * @param {DividerProps} props
+ * @returns {TemplateResult}
+ */
 export function render(props) {
   const { orientation = "horizontal", isInset = false } = props
 

package/src/data-display/icon/template.js

@@ -1,9 +1,16 @@
 /**
  * @typedef {import('../../../types/data-display/icon').IconProps} IconProps
+ * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
 import { classMap, html } from "@inglorious/web"
 
+/**
+ * Renders an inline icon element with size and color control.
+ * Use it for custom SVG, emoji, or font-based glyphs.
+ * @param {IconProps} props
+ * @returns {TemplateResult}
+ */
 export function render({ children, size = "md", color = "current", onClick }) {
   return html`<span
     class=${classMap({

package/src/data-display/list/template.js

@@ -29,10 +29,22 @@ const PRETTY_INDEX = 1
 
 export const list = {
   /**
+   * Main entrypoint for the list component. It delegates to the base list renderer so overrides can reuse it.
+   * Lists support ordered/unordered modes, nested items, and optional dividers.
    * @param {ListProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderList(props)
+  },
+
+  /**
+   * Renders the list container (ordered or unordered) and iterates items.
+   * Each item is delegated to `renderItem` for customization.
+   * @param {ListProps} props
+   * @returns {TemplateResult}
+   */
+  renderList(props) {
     const {
       type, // eslint-disable-line no-unused-vars
       items = [],
@@ -107,13 +119,10 @@ export const list = {
   },
 
   /**
+   * Renders a single list item, including icon, primary/secondary text, and actions.
+   * Handles item click/toggle wiring and nested children.
    * @param {ListProps} props
    * @param {{
-   *   item: ListItem,
-   *   meta: ListItemMeta,
-   *   index: number,
-   *   path: number[]
-   * }} payload
    * @returns {TemplateResult}
    */
   renderItem(props, { item, meta, path }) {

package/src/data-display/material-icon/template.js

@@ -1,9 +1,16 @@
 /**
  * @typedef {import('../../../types/data-display/material-icon').MaterialIconProps} MaterialIconProps
+ * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
  */
 
 import { classMap, html } from "@inglorious/web"
 
+/**
+ * Renders a Material Symbols icon by name.
+ * Requires the Material Symbols font and supports filled and size variants.
+ * @param {MaterialIconProps} props
+ * @returns {TemplateResult}
+ */
 export function render(props) {
   const { name = "help", size = "md", isFilled = true, onClick } = props
 

package/src/data-display/table/template.js

@@ -13,10 +13,22 @@ const STRIPED_OFFSET = 1
 
 export const table = {
   /**
+   * Main entrypoint for the table component. It delegates to the base table renderer so overrides can reuse it.
+   * Tables render columns and rows and can be striped or full width.
    * @param {TableProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderTable(props)
+  },
+
+  /**
+   * Renders the table wrapper, header row, and body rows.
+   * Header and cells are delegated to `renderHeaderCell` and `renderCell`.
+   * @param {TableProps} props
+   * @returns {TemplateResult}
+   */
+  renderTable(props) {
     const {
       columns = [],
       rows = [],
@@ -61,6 +73,8 @@ export const table = {
   },
 
   /**
+   * Renders a single header cell label for a column.
+   * Override to customize header content or add controls.
    * @param {TableProps} _props
    * @param {{column: TableColumn, index: number}} payload
    * @returns {TemplateResult}
@@ -71,6 +85,8 @@ export const table = {
   },
 
   /**
+   * Renders a single table row and wires row click handlers.
+   * Cells are delegated to `renderCell`.
    * @param {TableProps} props
    * @param {{row: Record<string, unknown>, index: number}} payload
    * @returns {TemplateResult}
@@ -95,6 +111,8 @@ export const table = {
   },
 
   /**
+   * Renders a single table cell value for a column.
+   * Override to format values or inject custom content.
    * @param {TableProps} _props
    * @param {{column: TableColumn, row: Record<string, unknown>}} payload
    * @returns {TemplateResult}

package/src/data-display/tooltip/template.js

@@ -8,6 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
+ * Renders a tooltip trigger and bubble with positional styling.
+ * Use `isOpen` to control visibility and `content` to set the tooltip body.
  * @param {TooltipProps} props
  * @returns {TemplateResult}
  */

package/src/data-display/typography/template.js

@@ -8,6 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
+ * Renders styled text with semantic variants such as headings, body, and caption.
+ * Supports alignment, weight, color, and gutter spacing.
  * @param {TypographyProps} props
  * @returns {TemplateResult}
  */

package/src/data-display/virtual-list/template.js

@@ -9,7 +9,8 @@ import { html, ref, repeat, styleMap } from "@inglorious/web"
 const PRETTY_INDEX = 1
 
 /**
- * Renders the virtualized list component.
+ * Renders a virtualized list that only mounts visible items for performance.
+ * Uses item height estimates to compute scroll ranges and notifies on mount/scroll.
  * @param {VirtualListEntity} entity The list entity state.
  * @param {Api} api The API object.
  * @returns {TemplateResult} The rendered list.
@@ -85,7 +86,8 @@ export function render(entity, api) {
 }
 
 /**
- * Default item renderer.
+ * Default item renderer for a virtualized list item.
+ * Override to customize how each item is displayed.
  * @param {VirtualListEntity} entity The list entity.
  * @param {object} payload The payload for rendering the item.
  * @param {any} payload.item The item data.

package/src/feedback/alert/template.js

@@ -8,6 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
+ * Renders an alert message with optional title, description, icon, and actions.
+ * Supports severity and variant styles for info, success, warning, and error.
  * @param {AlertProps} props
  * @returns {TemplateResult}
  */

package/src/feedback/backdrop/template.js

@@ -6,6 +6,8 @@
 import { classMap, html, when } from "@inglorious/web"
 
 /**
+ * Renders a fullscreen backdrop overlay when open.
+ * Optionally wraps child content in a centered container.
  * @param {BackdropProps} props
  * @returns {TemplateResult | null}
  */

package/src/feedback/dialog/template.js

@@ -6,6 +6,8 @@
 import { classMap, html } from "@inglorious/web"
 
 /**
+ * Renders a modal dialog with header, body, and actions when open.
+ * Clicking the backdrop can close the dialog when handlers are provided.
  * @param {DialogProps} props
  * @returns {TemplateResult | null}
  */

package/src/feedback/progress/template.js

@@ -10,6 +10,8 @@ function clamp(value) {
 }
 
 /**
+ * Renders a linear or circular progress indicator.
+ * Indeterminate mode is used when no explicit value is provided.
  * @param {ProgressProps} props
  * @returns {TemplateResult}
  */

package/src/feedback/skeleton/template.js

@@ -6,6 +6,8 @@
 import { classMap, html } from "@inglorious/web"
 
 /**
+ * Renders a loading skeleton placeholder for text, blocks, or multiple lines.
+ * Use it to indicate content is loading without layout shifts.
  * @param {SkeletonProps} props
  * @returns {TemplateResult}
  */

package/src/feedback/snackbar/template.js

@@ -6,6 +6,8 @@
 import { classMap, html } from "@inglorious/web"
 
 /**
+ * Renders a transient snackbar message with optional action and dismiss control.
+ * Position is configurable (for example bottom-left or top-right).
  * @param {SnackbarProps} props
  * @returns {TemplateResult | null}
  */

package/src/layout/container/template.js

@@ -16,6 +16,8 @@ const SIZE_TO_MAX_WIDTH = {
 }
 
 /**
+ * Renders a responsive layout container with optional max width and padding.
+ * Use it to constrain page content while keeping semantic HTML tags.
  * @param {ContainerProps} props
  * @returns {TemplateResult}
  */

package/src/layout/flex/template.js

@@ -8,9 +8,8 @@ import { classMap, ref, staticHtml, unsafeStatic } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
- * Flex layout component for Inglorious Web.
- * Children are rendered as-is (templates/content composition).
- *
+ * Renders a flexible layout container with direction, alignment, spacing, and wrap control.
+ * Use it to compose layouts without writing custom flexbox CSS.
  * @param {FlexProps} props
  * @returns {TemplateResult}
  */

package/src/layout/grid/template.js

@@ -6,9 +6,8 @@
 import { classMap, html, styleMap } from "@inglorious/web"
 
 /**
- * Grid layout component for Inglorious Web.
- * Children are rendered as-is (templates/content composition).
- *
+ * Renders a CSS grid container with configurable columns, gaps, and alignment.
+ * Supports fixed column counts or auto-fit with a minimum column width.
  * @param {GridProps} props
  * @returns {TemplateResult}
  */

package/src/navigation/bottom-navigation/template.js

@@ -10,10 +10,22 @@ import { applyElementProps } from "../../shared/applyElementProps.js"
 
 export const bottomNavigation = {
   /**
+   * Main entrypoint for bottom navigation. Delegates to the base renderer for overrides.
+   * Renders a row of actions with optional labels.
    * @param {BottomNavigationProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderBottomNavigation(props)
+  },
+
+  /**
+   * Renders the navigation container and iterates actions.
+   * Each action is delegated to `renderAction`.
+   * @param {BottomNavigationProps} props
+   * @returns {TemplateResult}
+   */
+  renderBottomNavigation(props) {
     const {
       type, // eslint-disable-line no-unused-vars
       actions = [],
@@ -41,6 +53,8 @@ export const bottomNavigation = {
   },
 
   /**
+   * Renders a single bottom navigation action.
+   * Handles selection state and click callbacks.
    * @param {BottomNavigationAction} action
    * @param {number} index
    * @param {BottomNavigationProps} props

package/src/navigation/breadcrumbs/template.js

@@ -10,10 +10,22 @@ import { applyElementProps } from "../../shared/applyElementProps.js"
 
 export const breadcrumbs = {
   /**
+   * Main entrypoint for breadcrumbs navigation. Delegates to the base renderer for overrides.
+   * Renders a list of path items separated by a configurable separator.
    * @param {BreadcrumbsProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderBreadcrumbs(props)
+  },
+
+  /**
+   * Renders the breadcrumb container and iterates items.
+   * Each item is delegated to `renderItem`.
+   * @param {BreadcrumbsProps} props
+   * @returns {TemplateResult}
+   */
+  renderBreadcrumbs(props) {
     const {
       type, // eslint-disable-line no-unused-vars
       items = [],
@@ -49,6 +61,8 @@ export const breadcrumbs = {
   },
 
   /**
+   * Renders a single breadcrumb item, handling current vs. link states.
+   * Override to customize labels or link behavior.
    * @param {BreadcrumbItem} item
    * @param {number} index
    * @param {BreadcrumbsProps} props

package/src/navigation/drawer/template.js

@@ -11,6 +11,8 @@ import { backdrop } from "../../feedback/backdrop"
 import { flex } from "../../layout/flex"
 
 /**
+ * Renders a side drawer panel with optional header, body, and collapse controls.
+ * Can show a backdrop when open and supports left/right anchoring.
  * @param {DrawerProps} props
  * @returns {TemplateResult}
  */

package/src/navigation/link/template.js

@@ -8,6 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
+ * Renders a styled link element with optional underline and color variants.
+ * Supports external link behavior and click handling.
  * @param {LinkProps} props
  * @returns {TemplateResult}
  */

package/src/navigation/menu/template.js

@@ -10,10 +10,22 @@ import { applyElementProps } from "../../shared/applyElementProps.js"
 
 export const menu = {
   /**
+   * Main entrypoint for a menu list. Delegates to the base renderer for overrides.
+   * Menus render selectable items and optional dividers.
    * @param {MenuProps} props
    * @returns {TemplateResult | null}
    */
   render(props) {
+    return this.renderMenu(props)
+  },
+
+  /**
+   * Renders the menu container and iterates items when open.
+   * Each item is delegated to `renderItem`.
+   * @param {MenuProps} props
+   * @returns {TemplateResult | null}
+   */
+  renderMenu(props) {
     const {
       type, // eslint-disable-line no-unused-vars
       isOpen = false,
@@ -46,6 +58,8 @@ export const menu = {
   },
 
   /**
+   * Renders a single menu item or divider.
+   * Handles selection, disabled state, and click callbacks.
    * @param {MenuItem} item
    * @param {number} index
    * @param {MenuProps} props

package/src/navigation/pagination/template.js

@@ -13,10 +13,22 @@ const PRETTY_PAGE = 1
 
 export const pagination = {
   /**
+   * Main entrypoint for pagination controls. Delegates to the base renderer for overrides.
+   * Supports sibling ranges, first/last buttons, and disabled state.
    * @param {PaginationProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderPagination(props)
+  },
+
+  /**
+   * Renders the pagination container and page/control items.
+   * Items are delegated to `renderItem` and `renderControl`.
+   * @param {PaginationProps} props
+   * @returns {TemplateResult}
+   */
+  renderPagination(props) {
     const {
       page = 1,
       count = 1,
@@ -68,6 +80,8 @@ export const pagination = {
   },
 
   /**
+   * Renders a single page number item or ellipsis.
+   * Uses the button primitive for interactive pages.
    * @param {PaginationProps} props
    * @param {PaginationItemRenderProps} payload
    * @returns {TemplateResult}
@@ -97,6 +111,8 @@ export const pagination = {
   },
 
   /**
+   * Renders a navigation control (first/prev/next/last).
+   * Uses the button primitive and wires change events.
    * @param {PaginationProps} props
    * @param {PaginationControlRenderProps} payload
    * @returns {TemplateResult}

package/src/navigation/speed-dial/template.js

@@ -8,10 +8,22 @@ import { classMap, html } from "@inglorious/web"
 
 export const speedDial = {
   /**
+   * Main entrypoint for the speed dial. Delegates to the base renderer for overrides.
+   * Shows a trigger button and an expandable list of actions.
    * @param {SpeedDialProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderSpeedDial(props)
+  },
+
+  /**
+   * Renders the speed dial container, trigger, and optional actions list.
+   * Actions are delegated to `renderAction`.
+   * @param {SpeedDialProps} props
+   * @returns {TemplateResult}
+   */
+  renderSpeedDial(props) {
     const {
       isOpen = false,
       direction = "up",
@@ -46,6 +58,8 @@ export const speedDial = {
   },
 
   /**
+   * Renders a single speed dial action button.
+   * Handles click callbacks and disabled state.
    * @param {SpeedDialAction} action
    * @param {number} index
    * @param {SpeedDialProps} props

package/src/navigation/stepper/template.js

@@ -8,10 +8,22 @@ import { classMap, html } from "@inglorious/web"
 
 export const stepper = {
   /**
+   * Main entrypoint for the stepper component. Delegates to the base renderer for overrides.
+   * Steppers render a sequence of steps with completion states.
    * @param {StepperProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderStepper(props)
+  },
+
+  /**
+   * Renders the ordered list of steps with orientation styling.
+   * Each step is delegated to `renderStep`.
+   * @param {StepperProps} props
+   * @returns {TemplateResult}
+   */
+  renderStepper(props) {
     const {
       steps = [],
       activeStep = 0,
@@ -33,6 +45,8 @@ export const stepper = {
   },
 
   /**
+   * Renders a single step with label, optional text, and completion state.
+   * Calculates active/completed styling based on the current step.
    * @param {Step} step
    * @param {number} index
    * @param {StepperProps} props

package/src/navigation/tabs/template.js

@@ -8,10 +8,22 @@ import { classMap, html } from "@inglorious/web"
 
 export const tabs = {
   /**
+   * Main entrypoint for tabbed navigation. Delegates to the base renderer for overrides.
+   * Renders tab labels and the active panel.
    * @param {TabsProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderTabs(props)
+  },
+
+  /**
+   * Renders the tabs list and the active panel container.
+   * Individual tabs are delegated to `renderTab`.
+   * @param {TabsProps} props
+   * @returns {TemplateResult}
+   */
+  renderTabs(props) {
     const {
       items = [],
       value = items[0]?.value ?? 0,
@@ -40,6 +52,8 @@ export const tabs = {
   },
 
   /**
+   * Renders a single tab button with selected/disabled states.
+   * Wires click events to update the active tab.
    * @param {TabItem} item
    * @param {number} index
    * @param {TabsProps} props
@@ -69,6 +83,8 @@ export const tabs = {
   },
 
   /**
+   * Renders the active tab panel content.
+   * Returns `null` when the active item has no panel.
    * @param {TabItem | null} item
    * @returns {TemplateResult | null}
    */

package/src/surfaces/accordion/template.js

@@ -10,10 +10,22 @@ import { applyElementProps } from "../../shared/applyElementProps.js"
 
 export const accordion = {
   /**
+   * Main entrypoint for the accordion component. Delegates to the base accordion renderer for overrides.
+   * Accordions render a list of collapsible items with optional icons.
    * @param {AccordionProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderAccordion(props)
+  },
+
+  /**
+   * Renders the accordion container and iterates items.
+   * Each item is delegated to `renderItem`.
+   * @param {AccordionProps} props
+   * @returns {TemplateResult}
+   */
+  renderAccordion(props) {
     const {
       type, // eslint-disable-line no-unused-vars
       items = [],
@@ -40,6 +52,8 @@ export const accordion = {
   },
 
   /**
+   * Renders a single accordion item with trigger and panel content.
+   * Handles expand/collapse behavior and item-level callbacks.
    * @param {AccordionItem} item
    * @param {number} index
    * @param {AccordionProps} props

package/src/surfaces/app-bar/template.js

@@ -8,6 +8,8 @@ import { classMap, html, ref, when } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
+ * Renders a top app bar with optional leading/trailing content and title metadata.
+ * Supports variants, density, color, and positioning modes.
  * @param {AppBarProps} props
  * @returns {TemplateResult}
  */

package/src/surfaces/card/template.js

@@ -9,10 +9,22 @@ import { applyElementProps } from "../../shared/applyElementProps.js"
 
 export const card = {
   /**
+   * Main entrypoint for the card component. Delegates to the base card renderer for easy overrides.
+   * Cards support header, body, and footer slots with optional click behavior.
    * @param {CardProps} props
    * @returns {TemplateResult}
    */
   render(props) {
+    return this.renderCard(props)
+  },
+
+  /**
+   * Renders the card container and composes header, body, and footer sub-sections.
+   * Uses `element` to control the semantic tag.
+   * @param {CardProps} props
+   * @returns {TemplateResult}
+   */
+  renderCard(props) {
     const {
       type, // eslint-disable-line no-unused-vars
       element = "article",
@@ -52,6 +64,8 @@ export const card = {
   },
 
   /**
+   * Renders the optional card header area (title, subtitle, or custom header content).
+   * Returns `null` when no header content is provided.
    * @param {CardProps} props
    * @returns {TemplateResult | null}
    */
@@ -83,6 +97,8 @@ export const card = {
   },
 
   /**
+   * Renders the main card content area.
+   * Returns `null` when there is no body or children content.
    * @param {CardProps} props
    * @returns {TemplateResult | null}
    */
@@ -103,6 +119,8 @@ export const card = {
   },
 
   /**
+   * Renders the optional card footer area, typically for actions.
+   * Returns `null` when no footer content is provided.
    * @param {CardProps} props
    * @returns {TemplateResult | null}
    */

package/src/surfaces/paper/template.js

@@ -8,6 +8,8 @@ import { classMap, html, ref } from "@inglorious/web"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 /**
+ * Renders a surface container with elevation, radius, and padding options.
+ * Use it as a generic surface for grouping content.
  * @param {PaperProps} props
  * @returns {TemplateResult}
  */

package/types/controls/combobox.d.ts

@@ -51,6 +51,7 @@ export interface ComboboxProps {
 export interface ComboboxType {
   create(entity: ComboboxProps): void
   render(entity: ComboboxProps, api: Api): TemplateResult
+  renderCombobox(props: ComboboxProps): TemplateResult
   open(entity: ComboboxProps): void
   close(entity: ComboboxProps): void
   toggle(entity: ComboboxProps): void

package/types/data-display/data-grid.d.ts

@@ -122,9 +122,10 @@ export interface DataGridType {
   rowsToggleAll(entity: DataGridProps): void
   rowsSelectAll(entity: DataGridProps): void
   selectionClear(entity: DataGridProps): void
-  virtualScroll(entity: DataGridProps, containerEl: HTMLElement): void
   virtualMount(entity: DataGridProps, containerEl: HTMLElement): void
+  virtualScroll(entity: DataGridProps, containerEl: HTMLElement): void
   render(entity: DataGridProps, api: Api): TemplateResult
+  renderDataGrid(entity: DataGridProps, api: Api): TemplateResult
   renderHeader(entity: DataGridProps, api: Api): TemplateResult
   renderToolbar(entity: DataGridProps, api: Api): TemplateResult
   renderHeaderColumn(

package/types/data-display/list.d.ts

@@ -39,6 +39,7 @@ export interface ListProps {
 
 export interface ListType {
   render(props: ListProps): TemplateResult
+  renderList(props: ListProps): TemplateResult
   renderItem(
     props: ListProps,
     payload: {

package/types/data-display/table.d.ts

@@ -23,6 +23,7 @@ export interface TableProps {
 
 export interface TableType {
   render(props: TableProps): TemplateResult
+  renderTable(props: TableProps): TemplateResult
   renderHeaderCell(
     props: TableProps,
     payload: { column: TableColumn; index: number },

package/types/navigation/bottom-navigation.d.ts

@@ -23,6 +23,7 @@ export interface BottomNavigationProps {
 
 export interface BottomNavigationType {
   render(props: BottomNavigationProps): TemplateResult
+  renderBottomNavigation(props: BottomNavigationProps): TemplateResult
   renderAction(
     action: BottomNavigationAction,
     index: number,

package/types/navigation/breadcrumbs.d.ts

@@ -19,6 +19,7 @@ export interface BreadcrumbsProps {
 
 export interface BreadcrumbsType {
   render(props: BreadcrumbsProps): TemplateResult
+  renderBreadcrumbs(props: BreadcrumbsProps): TemplateResult
   renderItem(
     item: BreadcrumbItem,
     index: number,

package/types/navigation/menu.d.ts

@@ -26,6 +26,7 @@ export interface MenuProps {
 
 export interface MenuType {
   render(props: MenuProps): TemplateResult | null
+  renderMenu(props: MenuProps): TemplateResult | null
   renderItem(item: MenuItem, index: number, props: MenuProps): TemplateResult
 }
 

package/types/navigation/pagination.d.ts

@@ -37,6 +37,7 @@ export interface PaginationControlRenderProps {
 
 export interface PaginationType {
   render(props: PaginationProps): TemplateResult
+  renderPagination(props: PaginationProps): TemplateResult
   renderItem(
     props: PaginationProps,
     payload: PaginationItemRenderProps,

package/types/navigation/speed-dial.d.ts

@@ -25,6 +25,7 @@ export interface SpeedDialProps {
 
 export interface SpeedDialType {
   render(props: SpeedDialProps): TemplateResult
+  renderSpeedDial(props: SpeedDialProps): TemplateResult
   renderAction(
     action: SpeedDialAction,
     index: number,

package/types/navigation/stepper.d.ts

@@ -20,6 +20,7 @@ export interface StepperProps {
 
 export interface StepperType {
   render(props: StepperProps): TemplateResult
+  renderStepper(props: StepperProps): TemplateResult
   renderStep(step: Step, index: number, props: StepperProps): TemplateResult
 }
 

package/types/navigation/tabs.d.ts

@@ -24,6 +24,7 @@ export interface TabsProps {
 
 export interface TabsType {
   render(props: TabsProps): TemplateResult
+  renderTabs(props: TabsProps): TemplateResult
   renderTab(item: TabItem, index: number, props: TabsProps): TemplateResult
   renderPanel(item: TabItem | null, props: TabsProps): TemplateResult | null
 }

package/types/surfaces/accordion.d.ts

@@ -22,6 +22,7 @@ export interface AccordionProps {
 
 export interface AccordionType {
   render(props: AccordionProps): TemplateResult
+  renderAccordion(props: AccordionProps): TemplateResult
   renderItem(
     item: AccordionItem,
     index: number,

package/types/surfaces/card.d.ts

@@ -31,6 +31,7 @@ export interface CardProps {
 
 export interface CardType {
   render(props: CardProps): TemplateResult
+  renderCard(props: CardProps): TemplateResult
   renderHeader(props: CardProps): TemplateResult | null
   renderBody(props: CardProps): TemplateResult | null
   renderFooter(props: CardProps): TemplateResult | null