@inglorious/ui 1.0.1 → 2.0.0

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/badge.stories.js

@@ -1,10 +1,10 @@
 import { createRender } from "../../stories/notifyStory.js"
-import { badge } from "."
+import { Badge } from "."
 
 export default {
   title: "Data Display/Badge",
   tags: ["autodocs"],
-  render: createRender(badge),
+  render: createRender(Badge),
   argTypes: {
     children: { control: "text", description: "Badge content." },
     color: {

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

@@ -1,3 +1,3 @@
 import * as renderers from "./template.js"
 
-export const badge = { ...renderers }
+export const Badge = { ...renderers }

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/chip.stories.js

@@ -1,10 +1,10 @@
 import { createRender } from "../../stories/notifyStory.js"
-import { chip } from "."
+import { Chip } from "."
 
 export default {
   title: "Data Display/Chip",
   tags: ["autodocs"],
-  render: createRender(chip),
+  render: createRender(Chip),
   argTypes: {
     children: { control: "text", description: "Chip label content." },
     isRemovable: {

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

@@ -1,3 +1,3 @@
 import * as renderers from "./template.js"
 
-export const chip = { ...renderers }
+export const Chip = { ...renderers }

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/data-grid.stories.js

@@ -2,7 +2,7 @@ import {
   createEntityRender,
   notifyActionArgType,
 } from "../../stories/notifyStory.js"
-import { dataGrid } from "."
+import { DataGrid } from "."
 
 const baseRows = [
   { id: 1, name: "Charlie", age: 35, active: true, role: "Admin" },
@@ -57,7 +57,7 @@ function createRows(count) {
 export default {
   title: "Data Display/DataGrid",
   tags: ["autodocs"],
-  render: createEntityRender({ dataGrid }),
+  render: createEntityRender({ DataGrid }),
   argTypes: {
     ...notifyActionArgType,
     id: { control: "text", description: "Optional grid id" },
@@ -75,7 +75,7 @@ export default {
 export const Default = {
   args: {
     id: "dataGrid",
-    type: "dataGrid",
+    type: "DataGrid",
     rows: baseRows,
     columns: baseColumns,
     search: {},
@@ -130,7 +130,7 @@ export const FlexibleWidths = {
 export const Virtualized = {
   args: {
     id: "virtualizedGrid",
-    type: "dataGrid",
+    type: "DataGrid",
     rows: createRows(1000),
     columns: baseColumns,
     search: null,

package/src/data-display/data-grid/filters/index.js

@@ -1,21 +1,21 @@
 import { choose, html } from "@inglorious/web"
 
-import { inputFilter } from "./input.js"
-import { rangeFilter } from "./range.js"
-import { selectFilter } from "./select.js"
+import { InputFilter } from "./input.js"
+import { RangeFilter } from "./range.js"
+import { SelectFilter } from "./select.js"
 
-export const filters = {
+export const Filters = {
   render(entity, column) {
     return html`${choose(
       column.filter.type,
       [
-        ["range", () => rangeFilter.render(entity, column)],
-        ["date", () => rangeFilter.render(entity, column)],
-        ["time", () => rangeFilter.render(entity, column)],
-        ["datetime", () => rangeFilter.render(entity, column)],
-        ["select", () => selectFilter.render(entity, column)],
+        ["range", () => RangeFilter.render(entity, column)],
+        ["date", () => RangeFilter.render(entity, column)],
+        ["time", () => RangeFilter.render(entity, column)],
+        ["datetime", () => RangeFilter.render(entity, column)],
+        ["select", () => SelectFilter.render(entity, column)],
       ],
-      () => inputFilter.render(entity, column),
+      () => InputFilter.render(entity, column),
     )}`
   },
 }

package/src/data-display/data-grid/filters/input.js

@@ -1,4 +1,4 @@
-import { input } from "../../../controls/input"
+import { Input } from "../../../controls/input"
 import { format } from "./helpers"
 
 const DEFAULT_PLACEHOLDER = {
@@ -6,9 +6,9 @@ const DEFAULT_PLACEHOLDER = {
   text: "Contains...",
 }
 
-export const inputFilter = {
+export const InputFilter = {
   render(entity, column) {
-    return input.render({
+    return Input.render({
       name: column.id,
       inputType: column.filter.type,
       placeholder:

package/src/data-display/data-grid/filters/range.js

@@ -1,6 +1,6 @@
 import { html } from "@inglorious/web"
 
-import { input } from "../../../controls/input"
+import { Input } from "../../../controls/input"
 import { format } from "./helpers"
 
 const RANGE_TYPE = {
@@ -10,10 +10,10 @@ const RANGE_TYPE = {
   datetime: "datetime-local",
 }
 
-export const rangeFilter = {
+export const RangeFilter = {
   render(entity, column) {
     return html`<div class="iw-data-grid-filter-range">
-      ${input.render({
+      ${Input.render({
         name: `${column.id}Min`,
         inputType: RANGE_TYPE[column.filter.type],
         placeholder: column.filter.placeholder ?? "≥",
@@ -28,7 +28,7 @@ export const rangeFilter = {
           })
         },
       })}
-      ${input.render({
+      ${Input.render({
         name: `${column.id}Max`,
         inputType: RANGE_TYPE[column.filter.type],
         placeholder: column.filter.placeholder ?? "≤",

package/src/data-display/data-grid/filters/select.js

@@ -1,9 +1,9 @@
-import { select } from "../../../controls/select"
+import { Select } from "../../../controls/select"
 import { format } from "./helpers"
 
-export const selectFilter = {
+export const SelectFilter = {
   render(entity, column) {
-    return select.render({
+    return Select.render({
       name: column.id,
       size: "sm",
       isFullWidth: true,

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

@@ -1,8 +1,8 @@
 import * as handlers from "./handlers.js"
 import * as helpers from "./helpers.js"
-import { dataGrid as renderers } from "./template.js"
+import { DataGrid as renderers } from "./template.js"
 
-export const dataGrid = {
+export const DataGrid = {
   ...handlers,
   ...renderers,
   render(entity, api) {

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

@@ -7,11 +7,11 @@
 
 import { classMap, html, repeat, when } from "@inglorious/web"
 
-import { input } from "../../controls/input/index.js"
-import { select } from "../../controls/select/index.js"
-import { pagination } from "../../navigation/pagination/index.js"
-import { virtualList } from "../virtual-list/index.js"
-import { filters } from "./filters"
+import { Input } from "../../controls/input/index.js"
+import { Select } from "../../controls/select/index.js"
+import { Pagination } from "../../navigation/pagination/index.js"
+import { VirtualList } from "../virtual-list/index.js"
+import { Filters } from "./filters"
 import {
   getPaginationInfo,
   getRowKeyValue,
@@ -25,9 +25,10 @@ const PRETTY_PAGE = 1
 const FIRST_PAGE = 0
 const LAST_PAGE = 1
 
-export const dataGrid = {
+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.
@@ -103,7 +108,7 @@ export const dataGrid = {
         ${column.title} ${getSortIcon(getSortDirection(props, column.id))}
       </div>
 
-      ${column.isFilterable && filters.render(props, column)}
+      ${column.isFilterable && Filters.render(props, column)}
 
       <div
         class="iw-data-grid-column-resizer"
@@ -118,13 +123,14 @@ 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.
    */
   renderSearchbar(props) {
     return html`<div class="iw-data-grid-searchbar">
-      ${input.render({
+      ${Input.render({
         size: "sm",
         isFullWidth: true,
         name: "search",
@@ -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.
    */
@@ -157,7 +164,7 @@ export const dataGrid = {
     const virtualState = getVirtualizationState(props, rows.length)
     const virtualEntity = {
       id: props.id,
-      type: "dataGridVirtualRows",
+      type: "DataGridVirtualRows",
       items: rows,
       className: "iw-data-grid-body",
       scrollTop: virtualState.scrollTop,
@@ -183,11 +190,12 @@ export const dataGrid = {
       }),
     }
 
-    return virtualList.render(virtualEntity, virtualApi)
+    return VirtualList.render(virtualEntity, virtualApi)
   },
 
   /**
-   * 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,14 +292,15 @@ 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.
    */
   renderPagination(props, paginationInfo) {
     return html`<div class="iw-data-grid-row">
-      ${pagination.renderControl(
+      ${Pagination.renderControl(
         {
           buttonSize: "sm",
           buttonVariant: "outline",
@@ -301,7 +313,7 @@ export const dataGrid = {
           onChange: () => props.onPageChange?.(FIRST_PAGE),
         },
       )}
-      ${pagination.renderControl(
+      ${Pagination.renderControl(
         {
           buttonSize: "sm",
           buttonVariant: "outline",
@@ -314,7 +326,7 @@ export const dataGrid = {
           onChange: () => props.onPagePrev?.(),
         },
       )}
-      ${input.render({
+      ${Input.render({
         name: "page",
         size: "sm",
         inputType: "number",
@@ -325,7 +337,7 @@ export const dataGrid = {
       })}
       /
       <span>${paginationInfo.totalPages}</span>
-      ${pagination.renderControl(
+      ${Pagination.renderControl(
         {
           buttonSize: "sm",
           buttonVariant: "outline",
@@ -338,7 +350,7 @@ export const dataGrid = {
           onChange: () => props.onPageNext?.(),
         },
       )}
-      ${pagination.renderControl(
+      ${Pagination.renderControl(
         {
           buttonSize: "sm",
           buttonVariant: "outline",
@@ -358,7 +370,7 @@ export const dataGrid = {
   renderPageSize(props, pagination) {
     return html`<div class="iw-data-grid-footer-row">
       <div>Page size:</div>
-      ${select.render({
+      ${Select.render({
         size: "sm",
         value: pagination.pageSize,
         options: pagination.pageSizes,

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

@@ -1,12 +1,12 @@
 import { render } from "@inglorious/web/test"
 
 import { createRender } from "../../stories/notifyStory.js"
-import { divider } from "."
+import { Divider } from "."
 
 export default {
   title: "Data Display/Divider",
   tags: ["autodocs"],
-  render: createRender(divider),
+  render: createRender(Divider),
   argTypes: {
     orientation: {
       control: "select",

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

@@ -1,3 +1,3 @@
 import * as renderers from "./template.js"
 
-export const divider = { ...renderers }
+export const Divider = { ...renderers }

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/icon-implementations.mdx

@@ -83,13 +83,13 @@ Use this page as a quick reference for supported icon strategies in `@inglorious
   <div className="iw-icon-tab-panels">
     <section className="iw-icon-tab-panel iw-icon-tab-panel-generic">
       <p>Use <code>@inglorious/ui/icon</code> for glyphs, emoji, and simple symbols. Reference: <a href="/?path=/story/data-display-icon--unicode">UTF-8 Icons</a></p>
-      <pre><code>{`icon.render({ children: "★", size: "md", color: "primary" })`}</code></pre>
+      <pre><code>{`Icon.render({ children: "★", size: "md", color: "primary" })`}</code></pre>
       <div className="iw-icon-example">★ ⚑ ♫</div>
     </section>
 
     <section className="iw-icon-tab-panel iw-icon-tab-panel-svg">
       <p>Use inline SVG when you want a custom icon pack without font dependencies.</p>
-      <pre><code>{`icon.render({
+      <pre><code>{`Icon.render({
     children: html\`<svg viewBox="0 0 24 24" ...>...</svg>\`,
     size: "md",
 })`}</code></pre>
@@ -109,7 +109,7 @@ Use this page as a quick reference for supported icon strategies in `@inglorious
 
     <section className="iw-icon-tab-panel iw-icon-tab-panel-material">
       <p>Use <code>@inglorious/ui/material-icon</code> when Material Symbols fonts are loaded. Reference: <a href="https://fonts.google.com/icons?icon.set=Material+Icons" target="_blank">Material Icons</a></p>
-      <pre><code>{`materialIcon.render({ name: "home", filled: true, size: "md" })`}</code></pre>
+      <pre><code>{`MaterialIcon.render({ name: "home", filled: true, size: "md" })`}</code></pre>
       <div className="iw-icon-example">
         <span className="iw-material-symbol" aria-hidden="true">home</span>
         <span className="iw-material-symbol" aria-hidden="true">settings</span>
@@ -119,7 +119,7 @@ Use this page as a quick reference for supported icon strategies in `@inglorious
 
     <section className="iw-icon-tab-panel iw-icon-tab-panel-fa">
       <p>Load Font Awesome CSS globally, then pass an icon element as <code>children</code>. Reference: <a href="https://fontawesome.com/search" target="_blank">Font Awesome Icons</a></p>
-      <pre><code>{`icon.render({
+      <pre><code>{`Icon.render({
     children: html\`<i class="fa-solid fa-user" aria-hidden="true"></i>\`,
 })`}</code></pre>
 

package/src/data-display/icon/icon-utf8.stories.js

@@ -1,18 +1,18 @@
-import { virtualList } from "@inglorious/ui/virtual-list"
+import { VirtualList } from "@inglorious/ui/virtual-list"
 import { html, repeat } from "@inglorious/web"
 
-import { button } from "../../controls/button"
+import { Button } from "../../controls/button"
 import {
   createEntityRender,
   notifyActionArgType,
 } from "../../stories/notifyStory.js"
-import { icon } from "."
+import { Icon } from "."
 
 const unicodeList = {
-  ...virtualList,
+  ...VirtualList,
 
   create(entity) {
-    virtualList.create(entity)
+    VirtualList.create(entity)
 
     const items = []
     let rowIndex = 0
@@ -35,7 +35,7 @@ const unicodeList = {
   },
 
   render(entity, api) {
-    return virtualList.render(entity, {
+    return VirtualList.render(entity, {
       ...api,
       getType: () => unicodeList,
     })
@@ -64,7 +64,7 @@ const unicodeList = {
               .toUpperCase()
               .padStart(4, "0")}`
 
-            return button.render({
+            return Button.render({
               id: code,
               variant: "ghost",
               color: "default",
@@ -72,7 +72,7 @@ const unicodeList = {
               shape: "square",
               ariaLabel: label,
               onClick: () => copyGlyph(glyph),
-              children: icon.render({
+              children: Icon.render({
                 children: glyph,
                 size,
                 color: "current",
@@ -128,7 +128,7 @@ export default {
 export const Unicode = {
   args: {
     id: "unicodeList",
-    type: "unicodeList",
+    type: "UnicodeList",
     start: 0,
     end: 129799,
     columns: 20,

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

@@ -1,10 +1,10 @@
 import { createRender } from "../../stories/notifyStory.js"
-import { icon } from "."
+import { Icon } from "."
 
 export default {
   title: "Data Display/Icon",
   tags: ["autodocs"],
-  render: createRender(icon),
+  render: createRender(Icon),
   argTypes: {
     children: { control: "text", description: "Icon glyph or inline content." },
     size: {

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

@@ -1,3 +1,3 @@
 import * as renderers from "./template.js"
 
-export const icon = { ...renderers }
+export const Icon = { ...renderers }

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/index.js

@@ -1,4 +1,4 @@
 import * as handlers from "./handlers.js"
-import { list as renderers } from "./template.js"
+import { List as renderers } from "./template.js"
 
-export const list = { ...renderers, ...handlers }
+export const List = { ...renderers, ...handlers }

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

@@ -1,10 +1,10 @@
 import { createRender } from "../../stories/notifyStory.js"
-import { list } from "."
+import { List } from "."
 
 export default {
   title: "Data Display/List",
   tags: ["autodocs"],
-  render: createRender(list),
+  render: createRender(List),
   argTypes: {
     items: {
       control: "object",