@mohasinac/appkit 4.15.0 → 4.16.0

package/dist/ui/DataTable.js

@@ -12,6 +12,8 @@ import { GRID_MAP } from "./components/Layout";
 import { Row } from "./components/Layout";
 import { Div } from "./components/Div";
 import { mergeTableConfig, DEFAULT_PAGINATION_CONFIG } from "../contracts";
+import { resolveColumnPriority } from "./columns/build-columns";
+import { COLUMN_PRIORITY_CLASS } from "../contracts/extend";
 export function DataTable({ data, columns, keyExtractor: keyExtractorProp, onRowClick, loading = false, emptyMessage, actions, mobileCardRender, emptyState, emptyIcon, emptyTitle, tableConfig, paginationConfig, externalPagination = false, 
 // Explicit flat props — override tableConfig when provided
 pageSize: pageSizeProp, stickyHeader: stickyHeaderProp, striped: stripedProp, showViewToggle: showViewToggleProp, showTableView = true, viewMode: controlledViewMode, defaultViewMode: defaultViewModeProp, onViewModeChange, selectable: selectableProp, selectedIds = [], onSelectionChange, gridCols = "cards", labels = {}, }) {
@@ -135,13 +137,13 @@ pageSize: pageSizeProp, stickyHeader: stickyHeaderProp, striped: stripedProp, sh
                                                         ? "ascending"
                                                         : "descending"
                                                     : "none"
-                                                : undefined, className: `appkit-data-table__th ${col.sortable ? "appkit-data-table__th--sortable" : ""}`, style: { width: col.width }, onClick: () => col.sortable && handleSort(col.key), children: _jsxs(Row, { gap: "sm", children: [col.header, col.sortable && (_jsx(Span, { "aria-hidden": "true", color: "faint", children: sortKey === col.key ? (sortDirection === "asc" ? ("↑") : ("↓")) : (_jsx(Span, { className: "opacity-30", children: "\u2195" })) }))] }) }, col.key))), actions && (_jsx("th", { scope: "col", className: "appkit-data-table__th appkit-data-table__td--actions", children: labelActions }))] }) }), _jsx("tbody", { className: "appkit-data-table__tbody divide-y divide-zinc-200 divide-[var(--appkit-color-border)]", children: paginatedData.map((item, index) => (_jsxs("tr", { className: [
+                                                : undefined, className: `appkit-data-table__th ${col.sortable ? "appkit-data-table__th--sortable" : ""} ${COLUMN_PRIORITY_CLASS[resolveColumnPriority(col)]}`, style: { width: col.width }, onClick: () => col.sortable && handleSort(col.key), children: _jsxs(Row, { gap: "sm", children: [col.header, col.sortable && (_jsx(Span, { "aria-hidden": "true", color: "faint", children: sortKey === col.key ? (sortDirection === "asc" ? ("↑") : ("↓")) : (_jsx(Span, { className: "opacity-30", children: "\u2195" })) }))] }) }, col.key))), actions && (_jsx("th", { scope: "col", className: "appkit-data-table__th appkit-data-table__td--actions", children: labelActions }))] }) }), _jsx("tbody", { className: "appkit-data-table__tbody divide-y divide-zinc-200 divide-[var(--appkit-color-border)]", children: paginatedData.map((item, index) => (_jsxs("tr", { className: [
                                         "appkit-data-table__row",
                                         striped && index % 2 === 1
                                             ? "appkit-data-table__row--striped"
                                             : "",
                                         onRowClick ? "appkit-data-table__row--clickable" : "",
-                                    ].join(" "), onClick: () => onRowClick?.(item), children: [selectable && (_jsx("td", { className: "px-4 py-4 w-8", onClick: (e) => e.stopPropagation(), children: _jsx(Checkbox, { bare: true, className: CLS_CHECKBOX, "aria-label": "Select row", checked: selectedIds.includes(keyExtractor(item)), onChange: (e) => handleRowSelectionChange(item, e.target.checked) }) })), columns.map((col) => (_jsx("td", { className: "appkit-data-table__td", children: col.render
+                                    ].join(" "), onClick: () => onRowClick?.(item), children: [selectable && (_jsx("td", { className: "px-4 py-4 w-8", onClick: (e) => e.stopPropagation(), children: _jsx(Checkbox, { bare: true, className: CLS_CHECKBOX, "aria-label": "Select row", checked: selectedIds.includes(keyExtractor(item)), onChange: (e) => handleRowSelectionChange(item, e.target.checked) }) })), columns.map((col) => (_jsx("td", { className: `appkit-data-table__td ${COLUMN_PRIORITY_CLASS[resolveColumnPriority(col)]}`, children: col.render
                                                 ? col.render(item)
                                                 : (item[col.key] ?? "-") }, col.key))), actions && (_jsx("td", { className: "appkit-data-table__td appkit-data-table__td--actions", onClick: (e) => e.stopPropagation(), children: actions(item) }))] }, keyExtractor(item)))) })] }) }) })), !externalPagination && totalPages > 1 && (_jsx(Div, { className: "appkit-data-table__pagination", children: _jsx(Pagination, { currentPage: currentPage, totalPages: totalPages, onPageChange: setCurrentPage, maxVisible: resolvedPag.maxVisible, showFirstLast: resolvedPag.showFirstLast, showPrevNext: resolvedPag.showPrevNext, size: resolvedPag.size }) }))] }));
 }

package/dist/ui/columns/build-columns.d.ts

@@ -5,7 +5,12 @@
  * @example
  * export const buildOrderColumns = createColumnBuilder(orderAdminColumns);
  */
-import type { TableColumn, ColumnExtensionOpts } from "../../contracts";
+import type { TableColumn, ColumnExtensionOpts, ColumnPriority } from "../../contracts";
+/**
+ * Resolve a column's breakpoint. An explicit `priority` always wins; otherwise
+ * the field dictionary decides; otherwise the column shows at every width.
+ */
+export declare function resolveColumnPriority<T>(col: TableColumn<T>): ColumnPriority;
 /**
  * Build a merged column list from base columns + extension opts.
  * Handles omit, overrides, and extras in one pass.

package/dist/ui/columns/build-columns.js

@@ -5,6 +5,59 @@
  * @example
  * export const buildOrderColumns = createColumnBuilder(orderAdminColumns);
  */
+/*
+ * Field-name → breakpoint, from the same vocabulary the form field-dictionary
+ * uses. Applied ONLY when a column does not set `priority` itself.
+ *
+ * 🛑 The default for an unrecognised key is `"always"`, not `"lg"`.
+ *
+ * A `"lg"` default would have been tidier and would have silently hidden a
+ * column on every one of the ~25 existing column sets the moment this shipped
+ * — including, on some tables, the only identifying label. Safe-by-default
+ * plus an audit that nudges wide tables to declare priorities gets the same
+ * end state without a silent regression in between.
+ */
+const PRIORITY_BY_FIELD = {
+    // md — one state and one number is enough to triage a row
+    status: "md",
+    price: "md",
+    total: "md",
+    totalAmount: "md",
+    amount: "md",
+    listingType: "md",
+    type: "md",
+    // lg — relational context
+    category: "lg",
+    categorySlug: "lg",
+    brand: "lg",
+    brandSlug: "lg",
+    store: "lg",
+    storeName: "lg",
+    storeId: "lg",
+    quantity: "lg",
+    stockQuantity: "lg",
+    rating: "lg",
+    scope: "lg",
+    role: "lg",
+    // xl — audit metadata: useful, never urgent
+    createdAt: "xl",
+    updatedAt: "xl",
+    publishedAt: "xl",
+    id: "xl",
+    slug: "xl",
+    views: "xl",
+    viewCount: "xl",
+    productCount: "xl",
+    createdBy: "xl",
+    updatedBy: "xl",
+};
+/**
+ * Resolve a column's breakpoint. An explicit `priority` always wins; otherwise
+ * the field dictionary decides; otherwise the column shows at every width.
+ */
+export function resolveColumnPriority(col) {
+    return col.priority ?? PRIORITY_BY_FIELD[col.key] ?? "always";
+}
 /**
  * Build a merged column list from base columns + extension opts.
  * Handles omit, overrides, and extras in one pass.

package/dist/ui/columns/cell-renderers.d.ts

@@ -0,0 +1,68 @@
+import React from "react";
+import { type StatusTone } from "./column-renderers";
+/**
+ * The single tone→class map.
+ *
+ * Previously duplicated verbatim in `features/admin/components/DataTable.tsx`
+ * and `AdminViewCards.tsx`. Both are now consumers of this one.
+ */
+export declare const STATUS_TONE_CLASSES: Record<StatusTone, string>;
+/** A status string as a themed chip. Unknown statuses render neutral, not invisible. */
+export declare function renderStatusBadge(status: string | null | undefined, opts?: {
+    emptyLabel?: string;
+}): React.ReactNode;
+declare const THUMB_SIZE: {
+    readonly sm: "h-8 w-8";
+    readonly md: "h-10 w-10";
+    readonly lg: "h-14 w-14";
+};
+/**
+ * A row thumbnail in an explicitly-sized box.
+ *
+ * `fallback` takes the resource emoji from `getResourceIcon`, so a row with no
+ * image still has a visual anchor rather than an empty cell.
+ */
+export declare function renderThumbnail(src: string | null | undefined, alt: string, opts?: {
+    size?: keyof typeof THUMB_SIZE;
+    fallback?: string;
+    rounded?: "full" | "md";
+}): React.ReactNode;
+/** A person: round thumbnail + name, with an optional secondary line. */
+export declare function renderAvatar(name: string, opts?: {
+    photoURL?: string | null;
+    secondary?: string | null;
+    fallback?: string;
+}): React.ReactNode;
+/** Money, right-aligned and tabular so columns of figures line up. */
+export declare function renderMoney(amount: number | null | undefined, opts?: {
+    currency?: string;
+    locale?: string;
+}): React.ReactNode;
+/**
+ * "2 days ago", with the full timestamp on hover.
+ *
+ * Takes `now` so it is testable and so a table full of dates shares one clock
+ * rather than drifting cell to cell.
+ */
+export declare function renderRelativeDate(value: Date | string | number | null | undefined, opts?: {
+    now?: Date;
+    emptyLabel?: string;
+}): React.ReactNode;
+/** ✓ / ✗ instead of the words "true"/"false". */
+export declare function renderBooleanIcon(value: boolean | null | undefined): React.ReactNode;
+/** A count as a pill. Zero renders muted rather than shouting. */
+export declare function renderCountPill(count: number | null | undefined, opts?: {
+    label?: string;
+}): React.ReactNode;
+/**
+ * A listing type as its registry badge.
+ *
+ * Goes through `listingBadgeVariant()`, not `LISTING_BADGE_VARIANT[kind]` — the
+ * accessor tolerates a non-`ListingType` string (a raw API value, a UI
+ * sentinel like `"all"`) while the map itself stays exhaustively typed, so a
+ * new listing type is a compile error there rather than a silent fallthrough.
+ */
+export declare function renderTypeChip(listingType: string | null | undefined, opts?: {
+    label?: string;
+}): React.ReactNode;
+export {};

package/dist/ui/columns/cell-renderers.js

@@ -0,0 +1,111 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge } from "../components/Badge";
+import { Row, Stack } from "../components/Layout";
+import { Div } from "../components/Div";
+import { Span, Text } from "../components/Typography";
+import { MediaImage } from "../../features/media/MediaImage";
+import { getStatusTone, renderCurrency } from "./column-renderers";
+import { listingBadgeVariant } from "../../features/products/utils/listing-badge-variant";
+/**
+ * The single tone→class map.
+ *
+ * Previously duplicated verbatim in `features/admin/components/DataTable.tsx`
+ * and `AdminViewCards.tsx`. Both are now consumers of this one.
+ */
+export const STATUS_TONE_CLASSES = {
+    success: "bg-success-surface text-success",
+    warning: "bg-warning-surface text-warning",
+    error: "bg-error-surface text-error",
+    info: "bg-info-surface text-info",
+    // Not a status colour — see the header.
+    neutral: "bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]",
+};
+/** A status string as a themed chip. Unknown statuses render neutral, not invisible. */
+export function renderStatusBadge(status, opts) {
+    const label = status ?? opts?.emptyLabel ?? "—";
+    const tone = getStatusTone(status);
+    return (_jsx(Span, { size: "xs", weight: "medium", rounded: "full", padding: "pill-sm-tall", className: `inline-flex whitespace-nowrap ${STATUS_TONE_CLASSES[tone]}`, children: label }));
+}
+const THUMB_SIZE = {
+    sm: "h-8 w-8",
+    md: "h-10 w-10",
+    lg: "h-14 w-14",
+};
+/**
+ * A row thumbnail in an explicitly-sized box.
+ *
+ * `fallback` takes the resource emoji from `getResourceIcon`, so a row with no
+ * image still has a visual anchor rather than an empty cell.
+ */
+export function renderThumbnail(src, alt, opts) {
+    const size = opts?.size ?? "sm";
+    return (_jsx(Div, { className: `relative shrink-0 ${THUMB_SIZE[size]}`, overflow: "hidden", rounded: opts?.rounded ?? "md", children: _jsx(MediaImage, { src: src ?? undefined, alt: alt, size: "avatar", fallback: opts?.fallback }) }));
+}
+/** A person: round thumbnail + name, with an optional secondary line. */
+export function renderAvatar(name, opts) {
+    return (_jsxs(Row, { gap: "sm", align: "center", children: [renderThumbnail(opts?.photoURL, name, { rounded: "full", fallback: opts?.fallback }), _jsxs(Stack, { gap: "none", className: "min-w-0", children: [_jsx(Text, { weight: "medium", color: "primary", className: "truncate", children: name }), opts?.secondary ? (_jsx(Text, { size: "xs", color: "muted", className: "truncate", children: opts.secondary })) : null] })] }));
+}
+/** Money, right-aligned and tabular so columns of figures line up. */
+export function renderMoney(amount, opts) {
+    return (_jsx(Span, { size: "sm", numeric: true, className: "whitespace-nowrap", children: renderCurrency(amount, opts?.currency, opts?.locale) }));
+}
+const MINUTE = 60000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+/**
+ * Thresholds, ordered ascending — a table rather than an if/else chain so a new
+ * granularity is one row, and so the ordering is visible at a glance.
+ */
+const RELATIVE_STEPS = [
+    { under: MINUTE, format: () => "just now" },
+    { under: HOUR, format: (abs, suffix) => `${Math.round(abs / MINUTE)}m ${suffix}` },
+    { under: DAY, format: (abs, suffix) => `${Math.round(abs / HOUR)}h ${suffix}` },
+    { under: 30 * DAY, format: (abs, suffix) => `${Math.round(abs / DAY)}d ${suffix}` },
+];
+/**
+ * "2 days ago", with the full timestamp on hover.
+ *
+ * Takes `now` so it is testable and so a table full of dates shares one clock
+ * rather than drifting cell to cell.
+ */
+export function renderRelativeDate(value, opts) {
+    if (value == null || value === "") {
+        return (_jsx(Span, { size: "sm", color: "muted", children: opts?.emptyLabel ?? "—" }));
+    }
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        // A malformed date renders as an em-dash rather than "Invalid Date".
+        return (_jsx(Span, { size: "sm", color: "muted", children: opts?.emptyLabel ?? "—" }));
+    }
+    const diff = (opts?.now ?? new Date()).getTime() - date.getTime();
+    const abs = Math.abs(diff);
+    const suffix = diff >= 0 ? "ago" : "from now";
+    const step = RELATIVE_STEPS.find((s) => abs < s.under);
+    // Past ~a month, a relative label stops being useful — show the real date.
+    const label = step ? step.format(abs, suffix) : date.toLocaleDateString();
+    return (_jsx(Span, { size: "sm", color: "muted", className: "whitespace-nowrap", title: date.toLocaleString(), children: label }));
+}
+/** ✓ / ✗ instead of the words "true"/"false". */
+export function renderBooleanIcon(value) {
+    return value ? (_jsx(Span, { size: "sm", className: "text-success", "aria-label": "Yes", children: "\u2713" })) : (_jsx(Span, { size: "sm", color: "muted", "aria-label": "No", children: "\u2717" }));
+}
+/** A count as a pill. Zero renders muted rather than shouting. */
+export function renderCountPill(count, opts) {
+    const n = count ?? 0;
+    const suffix = opts?.label ? ` ${opts.label}` : "";
+    return (_jsxs(Span, { size: "xs", weight: "medium", rounded: "full", padding: "pill-sm-tall", numeric: true, className: `inline-flex whitespace-nowrap ${n > 0 ? STATUS_TONE_CLASSES.info : STATUS_TONE_CLASSES.neutral}`, children: [n.toLocaleString(), suffix] }));
+}
+/**
+ * A listing type as its registry badge.
+ *
+ * Goes through `listingBadgeVariant()`, not `LISTING_BADGE_VARIANT[kind]` — the
+ * accessor tolerates a non-`ListingType` string (a raw API value, a UI
+ * sentinel like `"all"`) while the map itself stays exhaustively typed, so a
+ * new listing type is a compile error there rather than a silent fallthrough.
+ */
+export function renderTypeChip(listingType, opts) {
+    if (!listingType)
+        return null;
+    return (_jsx(Badge, { variant: listingBadgeVariant(listingType), children: opts?.label ?? listingType }));
+}

package/dist/ui/columns/column-renderers.d.ts

@@ -4,7 +4,12 @@
  * Every renderer returns a `string` (not ReactNode) so it works with
  * `TableColumn<T>.render` in both server and client contexts.
  *
- * For JSX renderers (badge, thumbnail, action buttons) see `column-renderers.tsx`.
+ * For JSX renderers (status badge, thumbnail, avatar, money, relative date,
+ * boolean icon, count pill, type chip) see `cell-renderers.tsx`.
+ *
+ * NOTE: that sibling was called `column-renderers.tsx` here for months and was
+ * never written, because it cannot be: `.ts` and `.tsx` of the same basename
+ * both emit `column-renderers.js` (TS5056). Hence the distinct name.
  */
 export interface BooleanRenderOpts {
     trueLabel?: string;

package/dist/ui/columns/column-renderers.js

@@ -4,7 +4,12 @@
  * Every renderer returns a `string` (not ReactNode) so it works with
  * `TableColumn<T>.render` in both server and client contexts.
  *
- * For JSX renderers (badge, thumbnail, action buttons) see `column-renderers.tsx`.
+ * For JSX renderers (status badge, thumbnail, avatar, money, relative date,
+ * boolean icon, count pill, type chip) see `cell-renderers.tsx`.
+ *
+ * NOTE: that sibling was called `column-renderers.tsx` here for months and was
+ * never written, because it cannot be: `.ts` and `.tsx` of the same basename
+ * both emit `column-renderers.js` (TS5056). Hence the distinct name.
  */
 import { formatCurrency } from "../../utils/number.formatter";
 import { getDefaultCurrency } from "../../core/baseline-resolver";

package/dist/ui/columns/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * Barrel for shared column utilities.
  */
-export { buildColumns, createColumnBuilder } from "./build-columns";
+export { buildColumns, createColumnBuilder, resolveColumnPriority } from "./build-columns";
 export { renderBoolean, renderCurrency, renderCurrencyCompact, renderCount, renderNullable, renderRating, getStatusTone, getResourceIcon, } from "./column-renderers";
 export type { BooleanRenderOpts, RatingMode, RatingRenderOpts, StatusTone, } from "./column-renderers";
+export { STATUS_TONE_CLASSES, renderStatusBadge, renderThumbnail, renderAvatar, renderMoney, renderRelativeDate, renderBooleanIcon, renderCountPill, renderTypeChip, } from "./cell-renderers";

package/dist/ui/columns/index.js

@@ -1,5 +1,9 @@
 /**
  * Barrel for shared column utilities.
  */
-export { buildColumns, createColumnBuilder } from "./build-columns";
+export { buildColumns, createColumnBuilder, resolveColumnPriority } from "./build-columns";
 export { renderBoolean, renderCurrency, renderCurrencyCompact, renderCount, renderNullable, renderRating, getStatusTone, getResourceIcon, } from "./column-renderers";
+// JSX renderers. Deliberately a separate module from `column-renderers.ts`:
+// that one is React-free so it can run in a server context, and mixing the two
+// would drag React into every consumer of a plain string formatter.
+export { STATUS_TONE_CLASSES, renderStatusBadge, renderThumbnail, renderAvatar, renderMoney, renderRelativeDate, renderBooleanIcon, renderCountPill, renderTypeChip, } from "./cell-renderers";

package/dist/ui/components/Button.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useCallback, useState } from "react";
 import { createPortal } from "react-dom";
 import { twMerge } from "tailwind-merge";
@@ -7,6 +7,7 @@ import { Loader2 } from "lucide-react";
 import { surfaceError } from "../../client/api/surface-error";
 import { useToastSafe } from "./Toast";
 import { SHADOW_MAP } from "./surface-tokens";
+import { resolveIcon } from "../icons/icon-registry";
 function spawnRipple(host, clientX, clientY) {
     const rect = host.getBoundingClientRect();
     const size = Math.max(rect.width, rect.height);
@@ -105,6 +106,23 @@ const BUTTON_JUSTIFY_MAP = {
     end: "justify-end",
     between: "justify-between",
 };
+/**
+ * The action's icon, rendered before its label.
+ *
+ * This is what makes `ActionDef.iconKey` real. It has existed on the type
+ * since the registry shipped, with a comment saying it is "resolved by the
+ * consumer's icon set" — there was no icon set, nothing resolved it, and every
+ * button in the app was text-only as a result.
+ *
+ * `aria-hidden` because the label (or `ariaLabel`) already names the action;
+ * announcing the glyph as well would read it twice.
+ */
+function ActionIcon({ action }) {
+    const Icon = resolveIcon(action?.iconKey);
+    if (!Icon)
+        return null;
+    return _jsx(Icon, { className: "h-4 w-4 shrink-0", "aria-hidden": "true" });
+}
 // Map ActionKind → Button variant (caller can override via explicit variant prop)
 const ACTION_KIND_VARIANT = {
     primary: "primary",
@@ -128,7 +146,14 @@ export function Button({ variant, size = "md", className = "", isLoading = false
     const pendingTargetRef = React.useRef(null);
     // Resolve defaults from action registry
     const resolvedVariant = variant ?? (action ? (ACTION_KIND_VARIANT[action.kind] ?? "primary") : "primary");
-    const resolvedChildren = children ?? (action ? action.label : undefined);
+    /*
+     * The icon is prepended only when the Button is rendering the action's OWN
+     * label. If the caller passed children they have composed their own content,
+     * and injecting a glyph into it would be a surprise.
+     */
+    const actionIcon = children === undefined && action?.iconKey ? _jsx(ActionIcon, { action: action }) : null;
+    const resolvedChildren = children ??
+        (action ? (actionIcon ? (_jsxs(_Fragment, { children: [actionIcon, action.label] })) : (action.label)) : undefined);
     const resolvedAriaLabel = props["aria-label"] ?? (action ? (action.ariaLabel ?? action.label) : undefined);
     const classes = twMerge(UI_BUTTON.base, UI_BUTTON.variants[resolvedVariant], UI_BUTTON.sizes[size], gap ? BUTTON_GAP_MAP[gap] : "", textSize ? BUTTON_TEXT_SIZE_MAP[textSize] : "", paddingX ? BUTTON_PADDING_X_MAP[paddingX] : "", paddingY ? BUTTON_PADDING_Y_MAP[paddingY] : "", weight ? BUTTON_WEIGHT_MAP[weight] : "", textColor ? BUTTON_TEXT_COLOR_MAP[textColor] : "", border ? BUTTON_BORDER_MAP[border] : "", rounded ? BUTTON_ROUNDED_MAP[rounded] : "", shadow ? SHADOW_MAP[shadow] : "", justify ? BUTTON_JUSTIFY_MAP[justify] : "", className);
     const userOnClick = props.onClick;

package/dist/ui/icons/icon-registry.d.ts

@@ -0,0 +1,65 @@
+import { type LucideIcon } from "lucide-react";
+/**
+ * Semantic name → component.
+ *
+ * Keys are INTENT ("approve", "reject"), not appearance ("check", "x"), so a
+ * later change of glyph is one edit here rather than a sweep of call sites.
+ * The few appearance-named keys exist because the action they serve genuinely
+ * has no better verb.
+ */
+export declare const ICONS: {
+    readonly view: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly hide: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly edit: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly create: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly save: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly delete: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly archive: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly duplicate: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly approve: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly reject: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly confirm: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly cancel: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly pause: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly resume: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly restore: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly retry: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly ban: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly report: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly verify: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly lock: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly cart: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly order: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly ship: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly bid: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly wishlist: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly review: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly analytics: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly message: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly reply: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly email: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly send: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly share: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly link: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly download: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly export: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly upload: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly back: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly search: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly filter: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly settings: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly expand: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly user: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+};
+/** Every valid `iconKey`. A typo is a compile error, not a silent blank. */
+export type IconKey = keyof typeof ICONS;
+/** Narrow an unknown string — for data that crosses a boundary the type cannot. */
+export declare function isIconKey(value: unknown): value is IconKey;
+/**
+ * Resolve a key to its component, or `undefined`.
+ *
+ * Returns `undefined` rather than a placeholder glyph on purpose: a missing
+ * icon should render nothing and leave the label intact, not draw a
+ * question-mark box that reads as a broken image.
+ */
+export declare function resolveIcon(key: string | null | undefined): LucideIcon | undefined;

package/dist/ui/icons/icon-registry.js

@@ -0,0 +1,115 @@
+/*
+ * WHY: `ActionDef.iconKey` has existed as `iconKey?: string` with the comment
+ *      *"resolved by the consumer's icon set"* — and there is no consumer icon
+ *      set. Nothing in either tree resolves it. It is set on **2 of 220**
+ *      actions (0.9%) and **rendered by nothing**: `Button` is the only
+ *      component that accepts an `ActionDef` and it reads `kind`, `label` and
+ *      `ariaLabel` only.
+ *
+ *      Meanwhile 105 files import `lucide-react` directly, so there is no
+ *      indirection anywhere — an icon is whatever each file happened to pick.
+ *
+ * WHAT: The name→component registry `iconKey` was always supposed to resolve
+ *       against, so the field can become real rather than inert.
+ *
+ * ## Typed, so a bad key cannot ship
+ *
+ * `ActionDef.iconKey` is retyped from `string` to `IconKey`. A typo was
+ * previously a silent no-op that rendered nothing; it is now a compile error.
+ * That is the same reasoning as every other registry in this codebase
+ * (`Record<Union, true>`), applied to icons.
+ *
+ * The one working name→icon pattern already in the repo is `TrustBadges.tsx`'s
+ * local `BADGE_ICONS` + `TrustBadgeIconKey` union. This generalises that shape
+ * rather than inventing a new one.
+ *
+ * ## Deliberately small
+ *
+ * Only the verbs the action registry actually uses, plus the handful of
+ * resource glyphs row menus need. This is not a re-export of lucide — a
+ * registry that mirrors the whole icon set is just an alias with extra steps,
+ * and it would pull every icon into the bundle.
+ *
+ * EXPORTS: ICONS, type IconKey, isIconKey, resolveIcon
+ *
+ * @tag domain:ui
+ * @tag layer:constants
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:Button,RowActionMenu,BulkActionBar,action-registry
+ * @tag sideEffects:none
+ */
+import { Archive, ArrowLeft, Ban, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, Heart, Link as LinkIcon, Lock, Mail, MessageSquare, Package, Pause, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Trash2, TrendingUp, Truck, Upload, User, X, XCircle, } from "lucide-react";
+/**
+ * Semantic name → component.
+ *
+ * Keys are INTENT ("approve", "reject"), not appearance ("check", "x"), so a
+ * later change of glyph is one edit here rather than a sweep of call sites.
+ * The few appearance-named keys exist because the action they serve genuinely
+ * has no better verb.
+ */
+export const ICONS = {
+    // Core CRUD
+    view: Eye,
+    hide: EyeOff,
+    edit: Edit,
+    create: Plus,
+    save: Save,
+    delete: Trash2,
+    archive: Archive,
+    duplicate: Copy,
+    // Decisions
+    approve: CheckCircle,
+    reject: XCircle,
+    confirm: Check,
+    cancel: X,
+    pause: Pause,
+    resume: Play,
+    restore: RotateCcw,
+    retry: RefreshCw,
+    // Moderation / trust
+    ban: Ban,
+    report: Flag,
+    verify: ShieldCheck,
+    lock: Lock,
+    // Commerce
+    cart: ShoppingCart,
+    order: Package,
+    ship: Truck,
+    bid: Gavel,
+    wishlist: Heart,
+    review: Star,
+    analytics: TrendingUp,
+    // Communication
+    message: MessageSquare,
+    reply: Reply,
+    email: Mail,
+    send: Send,
+    share: Share2,
+    link: LinkIcon,
+    // Data movement
+    download: Download,
+    export: FileDown,
+    upload: Upload,
+    // Navigation / chrome
+    back: ArrowLeft,
+    search: Search,
+    filter: Filter,
+    settings: Settings,
+    expand: ChevronDown,
+    user: User,
+};
+/** Narrow an unknown string — for data that crosses a boundary the type cannot. */
+export function isIconKey(value) {
+    return typeof value === "string" && value in ICONS;
+}
+/**
+ * Resolve a key to its component, or `undefined`.
+ *
+ * Returns `undefined` rather than a placeholder glyph on purpose: a missing
+ * icon should render nothing and leave the label intact, not draw a
+ * question-mark box that reads as a broken image.
+ */
+export function resolveIcon(key) {
+    return isIconKey(key) ? ICONS[key] : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.15.0",
+  "version": "4.16.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"