@inglorious/ui 1.0.1 → 2.0.0

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

@@ -21,18 +21,30 @@
 
 import { classMap, html, ref, repeat, when } from "@inglorious/web"
 
-import { iconButton } from "../../controls/icon-button"
-import { flex } from "../../layout/flex"
+import { IconButton } from "../../controls/icon-button"
+import { Flex } from "../../layout/flex"
 import { applyElementProps } from "../../shared/applyElementProps.js"
 
 const PRETTY_INDEX = 1
 
-export const list = {
+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 }) {
@@ -149,7 +158,7 @@ export const list = {
       .filter(Boolean)
       .join(" ")
 
-    return flex.render({
+    return Flex.render({
       element: "li",
       padding: "sm",
       direction: "column",
@@ -161,12 +170,12 @@ export const list = {
         props.onItemClick?.(raw ?? item, path)
       },
       children: [
-        flex.render({
+        Flex.render({
           align: "center",
           gap: "sm",
           children: [
             when(icon, () =>
-              iconButton.render({
+              IconButton.render({
                 icon,
                 size: "sm",
                 color: "secondary",
@@ -175,7 +184,7 @@ export const list = {
                 className: "iw-list-item-icon",
               }),
             ),
-            flex.render({
+            Flex.render({
               direction: "column",
               gap: "sm",
               className: "iw-list-item-content",
@@ -195,7 +204,7 @@ export const list = {
               () =>
                 html`<span class="iw-list-item-trailing">
                   ${when(hasChildren, () =>
-                    iconButton.render({
+                    IconButton.render({
                       variant: "ghost",
                       color: "secondary",
                       size: "sm",

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

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

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

@@ -1,6 +1,6 @@
 import { html, repeat } from "@inglorious/web"
 
-import { materialIcon } from "."
+import { MaterialIcon } from "."
 
 const materialIcons = [
   "search",
@@ -87,7 +87,7 @@ export const Gallery = {
           materialIcons,
           (name) => name,
           (name) =>
-            materialIcon.render({
+            MaterialIcon.render({
               name,
               size,
               isFilled,

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

@@ -1 +1 @@
-export { table } from "./template.js"
+export { Table } from "./template.js"

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

@@ -1,10 +1,10 @@
 import { createRender } from "../../stories/notifyStory.js"
-import { table } from "."
+import { Table } from "."
 
 export default {
   title: "Data Display/Table",
   tags: ["autodocs"],
-  render: createRender(table),
+  render: createRender(Table),
   argTypes: {
     columns: { control: "object", description: "Column definitions." },
     rows: { control: "object", description: "Row records." },

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

@@ -11,12 +11,24 @@ import { applyElementProps } from "../../shared/applyElementProps.js"
 const EVEN_ROW_DIVISOR = 2
 const STRIPED_OFFSET = 1
 
-export const table = {
+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/index.js

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

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

@@ -1,12 +1,12 @@
 import { html } from "@inglorious/web"
 
 import { createRender } from "../../stories/notifyStory.js"
-import { tooltip } from "."
+import { Tooltip } from "."
 
 export default {
   title: "Data Display/Tooltip",
   tags: ["autodocs"],
-  render: createRender(tooltip),
+  render: createRender(Tooltip),
   argTypes: {
     content: { control: "text", description: "Tooltip text." },
     position: {

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

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

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

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

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

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

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/examples/dashboard/app-drawer.js

@@ -1,13 +1,13 @@
 import { html } from "@inglorious/web"
 
-import { avatar } from "../../data-display/avatar"
-import { badge } from "../../data-display/badge"
-import { list } from "../../data-display/list"
-import { materialIcon } from "../../data-display/material-icon"
-import { flex } from "../../layout/flex"
-import { drawer } from "../../navigation/drawer"
-
-export const appDrawer = {
+import { Avatar } from "../../data-display/avatar"
+import { Badge } from "../../data-display/badge"
+import { List } from "../../data-display/list"
+import { MaterialIcon } from "../../data-display/material-icon"
+import { Flex } from "../../layout/flex"
+import { Drawer } from "../../navigation/drawer"
+
+export const AppDrawer = {
   create(entity) {
     entity.items ??= getDefaultItems()
   },
@@ -32,23 +32,23 @@ export const appDrawer = {
   render(entity, api) {
     const items = mapItemsForRender(entity.items ?? [], api)
 
-    return drawer.render({
+    return Drawer.render({
       ...entity,
       anchor: "left",
       onClose: () => api.notify(`#${entity.id}:toggle`),
       onCollapseToggle: () => api.notify(`#${entity.id}:collapseToggle`),
-      title: flex.render({
+      title: Flex.render({
         align: "center",
         gap: "sm",
         padding: "md",
         className: "iw-dashboard-brand",
         children: [
-          avatar.render({ src: "/transparent.png", shape: "square" }),
+          Avatar.render({ src: "/transparent.png", shape: "square" }),
           html`<span class="iw-dashboard-brand-title">Inglorious UI</span>`,
         ],
       }),
       children: html`
-        ${list.render({
+        ${List.render({
           isInset: true,
           padding: "sm",
           items,
@@ -67,18 +67,18 @@ function mapItemsForRender(items, api) {
     const mappedItem = { ...item }
 
     if (item.icon) {
-      mappedItem.icon = materialIcon.render({ name: item.icon, size: "lg" })
+      mappedItem.icon = MaterialIcon.render({ name: item.icon, size: "lg" })
     }
 
     if (item.badge) {
-      mappedItem.action = badge.render(item.badge)
+      mappedItem.action = Badge.render(item.badge)
     }
 
     if (item.href) {
       mappedItem.onClick = () => api.notify("#router:navigate", item.href)
     }
 
-    if (router.path === item.href) {
+    if (router?.path === item.href) {
       mappedItem.isSelected = true
     }
 

package/src/examples/dashboard/app-header.js

@@ -1,15 +1,15 @@
 import { html } from "@inglorious/web"
 
-import { button } from "../../controls/button"
-import { avatar } from "../../data-display/avatar"
-import { divider } from "../../data-display/divider"
-import { icon } from "../../data-display/icon"
-import { materialIcon } from "../../data-display/material-icon"
-import { flex } from "../../layout/flex"
-import { breadcrumbs } from "../../navigation/breadcrumbs"
-import { appBar } from "../../surfaces/app-bar"
+import { Button } from "../../controls/button"
+import { Avatar } from "../../data-display/avatar"
+import { Divider } from "../../data-display/divider"
+import { Icon } from "../../data-display/icon"
+import { MaterialIcon } from "../../data-display/material-icon"
+import { Flex } from "../../layout/flex"
+import { Breadcrumbs } from "../../navigation/breadcrumbs"
+import { AppBar } from "../../surfaces/app-bar"
 
-export const appHeader = {
+export const AppHeader = {
   render(entity, api) {
     const themeEntity = api.getEntity("theme")
     const modeEntity = api.getEntity("mode")
@@ -30,116 +30,116 @@ export const appHeader = {
 
     return html`
       <div class="iw-dashboard-header">
-        ${appBar.render({
+        ${AppBar.render({
           position: "static",
           elevated: false,
           children: html`
-            ${flex.render({
+            ${Flex.render({
               justify: "between",
               align: "center",
               gap: "md",
               className: "iw-dashboard-header-row",
               children: [
-                button.render({
+                Button.render({
                   color: "secondary",
                   variant: "ghost",
                   shape: "square",
-                  children: materialIcon.render({ name: "menu", size: "lg" }),
+                  children: MaterialIcon.render({ name: "menu", size: "lg" }),
                   "aria-label": "Toggle navigation",
                   onClick: () => api.notify(`#appDrawer:toggle`),
                 }),
-                flex.render({
+                Flex.render({
                   align: "center",
                   gap: "sm",
                   className: "iw-dashboard-header-nav",
                   children: [
-                    button.render({
+                    Button.render({
                       color: "secondary",
                       variant: "ghost",
                       children: "Dashboard",
                     }),
-                    button.render({
+                    Button.render({
                       color: "secondary",
                       variant: "ghost",
                       children: "Users",
                     }),
-                    button.render({
+                    Button.render({
                       color: "secondary",
                       variant: "ghost",
                       children: "Settings",
                     }),
                   ],
                 }),
-                flex.render({
+                Flex.render({
                   align: "center",
                   gap: "sm",
                   className: "iw-dashboard-header-actions",
                   children: [
-                    button.render({
+                    Button.render({
                       color: "secondary",
                       variant: "ghost",
                       shape: "square",
-                      children: materialIcon.render({
+                      children: MaterialIcon.render({
                         name: "notifications",
                         size: "lg",
                       }),
                       "aria-label": "Notifications",
                     }),
-                    button.render({
+                    Button.render({
                       color: "secondary",
                       variant: "ghost",
                       shape: "square",
-                      children: materialIcon.render({
+                      children: MaterialIcon.render({
                         name: "format_list_bulleted",
                       }),
                       "aria-label": "Tasks",
                     }),
-                    button.render({
+                    Button.render({
                       color: "secondary",
                       variant: "ghost",
                       shape: "square",
-                      children: materialIcon.render({
+                      children: MaterialIcon.render({
                         name: "mail",
                         size: "lg",
                       }),
                       "aria-label": "Messages",
                     }),
-                    divider.render({ orientation: "vertical" }),
+                    Divider.render({ orientation: "vertical" }),
 
-                    button.render({
+                    Button.render({
                       color: "secondary",
                       variant: "ghost",
                       shape: "square",
-                      children: icon.render({
+                      children: Icon.render({
                         children: html`<i class=${themeIcon}></i>`,
                         size: "lg",
                       }),
                       "aria-label": `Theme: ${themeName}`,
                       onClick: () => api.notify("#theme:toggle"),
                     }),
-                    button.render({
+                    Button.render({
                       color: "secondary",
                       variant: "ghost",
                       shape: "square",
-                      children: materialIcon.render({
+                      children: MaterialIcon.render({
                         name: modeIcon,
                         size: "lg",
                       }),
                       "aria-label": `Mode: ${themeMode}`,
                       onClick: () => api.notify("#mode:toggle"),
                     }),
-                    divider.render({ orientation: "vertical" }),
-                    avatar.render({ src: "/antony.jpeg" }),
+                    Divider.render({ orientation: "vertical" }),
+                    Avatar.render({ src: "/antony.jpeg" }),
                   ],
                 }),
               ],
             })}
           `,
         })}
-        ${flex.render({
+        ${Flex.render({
           align: "center",
           className: "iw-dashboard-header-row iw-dashboard-breadcrumbs",
-          children: breadcrumbs.render({
+          children: Breadcrumbs.render({
             items: [{ label: "Home", href: "#" }, { label: "Dashboard" }],
           }),
         })}

package/src/examples/dashboard/dashboard-jsx.jsx

@@ -0,0 +1,76 @@
+import { Container } from "../../layout/container/index.js"
+import { Flex } from "../../layout/flex/index.js"
+import { Grid } from "../../layout/grid/index.js"
+import { AppDrawer } from "./app-drawer.js"
+import { AppHeader } from "./app-header.js"
+import { socialCards, statCards } from "./data.js"
+import { PrimitiveSection } from "./primitive-section.js"
+import { SocialCard } from "./social-card.js"
+import { StatCard } from "./stat-card.js"
+import { TrafficCard } from "./traffic-card.js"
+import { TrafficSalesCard } from "./traffic-sales-card.js"
+
+export const DashboardJsx = {
+  render(entity, api) {
+    const appDrawer = api.getEntity("appDrawer")
+    const dashboardClassName = [
+      "iw-dashboard",
+      appDrawer.isHidden && "iw-dashboard-drawer-hidden",
+      appDrawer.isCollapsed && "iw-dashboard-drawer-collapsed",
+    ]
+      .filter(Boolean)
+      .join(" ")
+
+    const router = api.getEntity("router")
+    const isDashboardRoot = !router || router.path === "/"
+
+    return (
+      <Flex direction="column" className={dashboardClassName}>
+        <AppDrawer />
+
+        <Flex element="main" direction="column" className="iw-dashboard-main">
+          <AppHeader />
+
+          <Container
+            maxWidth="xl"
+            padding="lg"
+            className="iw-dashboard-container"
+          >
+            {isDashboardRoot && (
+              <Flex direction="column" gap="lg">
+                <Grid minColumnWidth="18rem" gap="lg">
+                  {statCards.map((card) => (
+                    <StatCard key={card.id} {...card} />
+                  ))}
+                </Grid>
+
+                <TrafficCard />
+
+                <Grid columns={3} gap="lg">
+                  {socialCards.map((card) => (
+                    <SocialCard key={card.id} {...card} />
+                  ))}
+                </Grid>
+
+                <TrafficSalesCard />
+              </Flex>
+            )}
+
+            {!isDashboardRoot && <PrimitiveSection />}
+          </Container>
+
+          <Flex
+            element="footer"
+            justify="between"
+            gap="md"
+            padding="md"
+            className="iw-dashboard-footer"
+          >
+            <div>Admin dashboard example © 2026</div>
+            <div>Built with Inglorious UI primitives and charts</div>
+          </Flex>
+        </Flex>
+      </Flex>
+    )
+  },
+}