pixelize-design-library 2.4.2-beta.39 → 2.4.2-beta.40

package/COMPONENT-GOTCHAS.md

@@ -443,15 +443,17 @@ styleable) `Divider` re-exported from the `Primitives` barrel. `Trail/TrailWorks
 **Apply:** for a divider in a consuming app, use the `Divider` from `Primitives`, not this library's
 own. For a real data grid, use `Table` — nothing under `Trail/` is meant for reuse.
 
-### `KanbanActions` is not wired into `KanbanBoard`, and is not exported
+### `KanbanActions` is exported but still not wired into `KanbanBoard`
 
 `KanbanBoard`'s header select/edit/create bar is driven by its own `kanbanSelect`/`kanbanEdit`/
-`kanbanCreate` props, via a different internal component. `KanbanActions` is a separate,
-unconnected, unexported component whose only references are its own file and test — its
-`options`-driven buttons always render with no gating, unlike the real header actions.
+`kanbanCreate` props, via a different internal component. `KanbanActions` is a separate, standalone
+component (exported from the package root as of 2.4.2-beta.39) that a consumer must render and wire
+up itself — its `options`-driven buttons always render with no permission gating, unlike
+`KanbanBoard`'s own header actions, which respect `permissions.isEditable`/`isCreatable`.
 
-**Apply:** use `KanbanBoard`'s own `kanbanSelect`/`kanbanEdit`/`kanbanCreate` props for board header
-actions — never reach for `KanbanActions`.
+**Apply:** use `KanbanBoard`'s own `kanbanSelect`/`kanbanEdit`/`kanbanCreate` props for the board's
+built-in header actions. Reach for `KanbanActions` only when building a custom toolbar outside
+`KanbanBoard`, and gate it yourself — it has no permissions awareness of its own.
 
 ### `KanbanBoard`'s `permissions.isEditable: false` disables card drag but not column-reorder drag
 
@@ -962,7 +964,124 @@ Remount via `key={fileUrl}` when swapping the file in place instead of just chan
 
 Both props stop having any effect the moment a tracker switches to the stepper variant. Separately,
 if `value` matches no `stage.id` (e.g. `stages` was filtered/re-derived and went stale), every stage
-silently renders as `"upcoming"` — no stage is ever active or completed, with no error.
+silently renders as `"upcoming"` — no stage is ever active or completed, with no error. The match is
+also a strict `===`: a numeric `stage.id` compared against a string `value` (or vice versa) never
+matches either, even when the "same" stage is clearly intended.
 
 **Apply:** don't rely on either prop once on the stepper variant. Re-validate `value` against the
-current `stages` list whenever it's filtered.
+current `stages` list whenever it's filtered, and keep `id`/`value` the same primitive type at every
+call site.
+
+### `Table`'s `isVisiblity`, `tableSettings`, `handleExportChange`/`exportOptions`/`exportLabel`, and `onColumnFilter` are dead props
+
+None of these do anything in the current implementation, despite being typed on `TableProps` (and
+some documented on the demo page):
+
+- `isVisiblity` — `Table`'s own destructure never lists it, so a consumer's value is dropped. It's
+  hardcoded `true` into both `Pagination` call sites regardless, and `Pagination` doesn't read it
+  either. It is a misspelling of `isVisibility`, but do not rename it (breaking change) — and do not
+  expect it to do anything if you do.
+- `tableSettings` (`{filters, filterSelected, onFilterSelection}`) — `Table` passes it to
+  `TableSettings`, but `TableSettings`'s function signature never destructures it.
+- `handleExportChange` / `exportOptions` / `exportLabel` — `Table` renders no export UI at all; none
+  of the three are read anywhere, despite `src/Pages/table.tsx` documenting them as if live.
+- `onColumnFilter` — commented out of `Table`'s own destructure (`// onColumnFilter`).
+
+**Apply:** don't reach for any of these expecting an effect. Column visibility is driven by
+`isTableSettings` (shows the Settings gear) + `preferences` (server persistence) + the Manage
+Columns tab — not by `isVisiblity`/`tableSettings`.
+
+### `Table`'s `preferences` prop is silent-by-default, not required
+
+Omitting `preferences` (or leaving `preferences.url` empty, the default) does not throw or disable
+the table — the persistence hooks both early-return when the base URL is falsy. The table works
+fully in memory; it just never persists column order/visibility, density, or grouping across
+reloads. When you do wire a `url`, `token` is sent as a **raw** `Authorization` header value — do
+not prefix it with `"Bearer "` yourself expecting the hook to strip it.
+
+**Apply:** treat `preferences` as opt-in persistence, not a required config block. If settings
+aren't surviving a refresh, check `preferences.url` is actually set before assuming a bug.
+
+### `SearchSelect`'s `height` prop only resizes the `insideSelect` segment, not the field
+
+Despite the name, `height` is read only to size the nested `insideSelect` trigger. The main
+control's height always comes from `size`'s token set — passing `height` with no `insideSelect`
+configured has no visible effect at all.
+
+**Apply:** to change the main field's height, change `size`; `height` only matters when
+`insideSelect` is also passed.
+
+### `SearchSelect`'s `pagination.limit` also drives a "has more" guess, not just page size
+
+`hasMore` is computed as `options.length % pagination.limit === 0` — there is no real end-of-data
+signal from the consumer. A total result count that happens to be an exact multiple of `limit`
+looks indistinguishable from "more pages exist," firing one extra, empty `onScroll` call.
+
+**Apply:** if exact pagination boundaries matter, pad or report a real "no more results" state some
+other way; don't rely on `hasMore` being accurate at a page boundary.
+
+### `RolesPermission`'s `RoleData.permission`/`designation`/`makeSuperAdmin`/`automation`/`trackLocation`/`show_records` are dead weight in this component
+
+None of these fields are read by `RolesPermission` — the roles list only renders
+`roleName`/`createdBy`/`created_at`/`roles_id`. They exist solely to be round-tripped unchanged
+through `onViewRole`/`onEditRole` so the consumer can prefill its own edit form. Setting them has no
+visible effect inside this component.
+
+**Apply:** treat these fields as pass-through-only storage — populate them for your own edit form,
+not to change anything `RolesPermission` itself renders.
+
+### `OrganizationDetails`' `OrganizationItem.uiInvite` is never read
+
+Active vs. invited organizations are decided purely by which array (`activeOrganizations` vs
+`invitedOrganizations`) an item is placed in — `uiInvite` is carried on the type but
+`OrganizationDetails` never inspects it.
+
+**Apply:** don't rely on `uiInvite` to control which section an item renders in — move the item
+between the two arrays instead.
+
+### `OrganizationDetails`' `onSetDefault`/`onAcceptInvite`/`onDeclineInvite` are fire-and-forget despite their `Promise<void>` signature
+
+Unlike `onCreateOrganization`/`onEditOrganization`/`onDeleteOrganization` (all awaited), these three
+are called without `await` — the `switchingOrgIds`/`respondingOrgIds` spinner arrays are entirely
+consumer-managed state, not driven by this component resolving the promise.
+
+**Apply:** don't assume symmetry with the awaited callbacks in the same props interface; manage your
+own loading state for these three around the promise you return.
+
+### `OrganizationDetails`' `CreateOrgFormValues.default`/`defaultOrg` are dead fields
+
+The built-in `CreateOrgModal`'s internal state and submit handler never set or forward them, and the
+public `onCreateOrganization` callback's parameter type doesn't declare them at all — populating
+them in a custom create form has no effect on the built-in flow.
+
+**Apply:** don't rely on these two fields to pre-mark a newly created org as default.
+
+### `SideBar`'s `selectedSubMenu` prop is accepted but never read
+
+`SidebarProps.selectedSubMenu` is threaded through `SideBar` → `MenuItems` → `MenuItemBox`, but the
+component's destructure never includes it — passing it has no effect of any kind.
+
+**Apply:** don't pass `selectedSubMenu` expecting it to highlight a submenu row.
+
+### `SideBar`'s `locked` menu-item flag doesn't lock anything
+
+`MenuProps.locked` only swaps the trailing badge/chevron for a lock icon. The click handler checks
+only `disabled` — a `locked: true, disabled: false` item still fully navigates/expands.
+
+**Apply:** set `disabled: true` alongside `locked: true` to actually prevent interaction.
+
+### `KanbanBoard`'s `kanbanSelect` ignores `permissions`, unlike `kanbanEdit`/`kanbanCreate`
+
+`kanbanEdit`/`kanbanCreate` are only forwarded when `permissions.isEditable`/`isCreatable` allow it;
+`kanbanSelect` is passed through unconditionally regardless of `permissions`. `onOpen` similarly has
+no permission gate at all, asymmetric with the gated `onDelete`.
+
+**Apply:** gate `kanbanSelect.isSelect` (and any `onOpen` affordance) yourself if they should also be
+permission-locked.
+
+### `KanbanBoard`'s `permissions.isViewable: false` hides everything, including header actions
+
+Not just the columns — the select/edit/create header bar disappears too, since the whole component
+returns `null` before rendering anything.
+
+**Apply:** there's no prop for hiding only the board body while keeping header actions visible.

package/dist/Components/Apexcharts/ApexBarChart/ApexBarChart.d.ts

@@ -1,2 +1,3 @@
 import { ApexBarChartProps } from "./ApexBarChartProps";
+/** Bar chart wrapper around react-apexcharts (horizontal/stacked/distributed via props), themed via chartColorsFromTheme + chartBase. */
 export default function ApexBarChart({ data, labels, title, titlePosition, height, width, barColor, xAxisStyle, yAxisStyle, titleStyle, horizontal, distributed, seriesName, series, stacked, showLegend, legendPosition, }: ApexBarChartProps): import("react/jsx-runtime").JSX.Element;

package/dist/Components/Apexcharts/ApexBarChart/ApexBarChart.js

@@ -10,6 +10,7 @@ const react_apexcharts_1 = __importDefault(require("react-apexcharts"));
 const react_2 = require("@chakra-ui/react");
 const chartColorsFromTheme_1 = require("../../../Theme/tokens/builders/chartColorsFromTheme");
 const chartBase_1 = require("../chartBase");
+/** Bar chart wrapper around react-apexcharts (horizontal/stacked/distributed via props), themed via chartColorsFromTheme + chartBase. */
 function ApexBarChart({ data, labels, title, titlePosition, height = 400, width = 500, barColor, xAxisStyle, yAxisStyle, titleStyle, horizontal = false, distributed = false, seriesName = "Data", series, stacked = false, showLegend, legendPosition = "bottom", }) {
     const theme = (0, react_2.useTheme)();
     const palette = theme.colors;

package/dist/Components/Apexcharts/ApexLineChart/ApexLineChart.d.ts

@@ -1,3 +1,4 @@
 import { ApexLineChartProps } from "./ApexLineChartProps";
+/** Line chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 declare const ApexLineChart: ({ data, labels, title, height, width, lineColors, titlePosition, titleStyle, compact, toolbarBreakpointPct, titleClampLines, showTitleEllipsis, showSeries, series: seriesNames, variant, }: ApexLineChartProps) => import("react/jsx-runtime").JSX.Element;
 export default ApexLineChart;

package/dist/Components/Apexcharts/ApexLineChart/ApexLineChart.js

@@ -10,6 +10,7 @@ const react_2 = require("@chakra-ui/react");
 const ToolTip_1 = __importDefault(require("../../ToolTip/ToolTip"));
 const chartColorsFromTheme_1 = require("../../../Theme/tokens/builders/chartColorsFromTheme");
 const chartBase_1 = require("../chartBase");
+/** Line chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 const ApexLineChart = ({ data, labels, title, height, width, lineColors, titlePosition = "center", titleStyle, compact = false, toolbarBreakpointPct = 0.6, titleClampLines, showTitleEllipsis = true, showSeries = true, series: seriesNames, variant = "basic", }) => {
     const theme = (0, react_2.useTheme)();
     const palette = theme.colors;

package/dist/Components/Apexcharts/ApexPieChart/ApexPieChart.d.ts

@@ -1,3 +1,4 @@
 import { ApexPieChartProps } from "./ApexPieChartProps";
+/** Pie/donut chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 declare const ApexPieChart: ({ data, labels, title, height, width, donutColors, chartColor, titlePosition, titleStyle, legendPosition, legendStyle, variant, showDataLabels, minLabelPercent, surfaceColor, donutSize, totalLabel, labelPlacement, }: ApexPieChartProps) => import("react/jsx-runtime").JSX.Element;
 export default ApexPieChart;

package/dist/Components/Apexcharts/ApexPieChart/ApexPieChart.js

@@ -17,6 +17,7 @@ const getValidLegendPosition = (position) => {
     console.warn(`Invalid legend position: ${position}. Defaulting to 'bottom'.`);
     return "bottom";
 };
+/** Pie/donut chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 const ApexPieChart = ({ data, labels, title, height = 400, width = 500, donutColors, chartColor, titlePosition = "center", titleStyle, legendPosition = "bottom", legendStyle, variant = "pie", showDataLabels = true, minLabelPercent = 8, surfaceColor, donutSize = "68%", totalLabel = "Total", labelPlacement = "auto", }) => {
     var _a;
     const { colors: palette } = (0, useCustomTheme_1.useCustomTheme)();

package/dist/Components/Apexcharts/ApexPolarCharts/ApexPolarCharts.d.ts

@@ -1,3 +1,4 @@
 import { ApexPolarChartProps } from "./ApexPolarChartsProps";
+/** Polar-area chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 declare const ApexPolarChart: ({ data, labels, title, height, width, chartColors, titlePosition, titleStyle, legendStyle, variant, }: ApexPolarChartProps) => import("react/jsx-runtime").JSX.Element;
 export default ApexPolarChart;

package/dist/Components/Apexcharts/ApexPolarCharts/ApexPolarCharts.js

@@ -9,6 +9,7 @@ const react_apexcharts_1 = __importDefault(require("react-apexcharts"));
 const react_2 = require("@chakra-ui/react");
 const chartColorsFromTheme_1 = require("../../../Theme/tokens/builders/chartColorsFromTheme");
 const chartBase_1 = require("../chartBase");
+/** Polar-area chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 const ApexPolarChart = ({ data, labels, title, height = 400, width = 500, chartColors, titlePosition = "center", titleStyle, legendStyle, variant = "basic", }) => {
     const theme = (0, react_2.useTheme)();
     const palette = theme.colors;

package/dist/Components/KanbanBoard/KanbanBoardProps.d.ts

@@ -2,11 +2,17 @@ import type { ReactNode } from "react";
 import { OptionProp } from "../Select/SelectProps";
 /** Extra string keys render as label:value rows on the card; number values (also allowed here) are silently never shown. */
 export type Account = {
+    /** Used as the React key and the dnd draggableId — must be unique and stable across renders. */
     id: string;
+    /** Fully replaces AccountCard for this card — onDelete/onOpen/isDeletable and expand/collapse never apply when set. */
     customNode?: () => ReactNode;
+    /** Excluded from the generic row list; shown as separate description text, only when expanded. */
     details?: string;
+    /** No special rendering — just another label:value row like any extra string key. */
     name?: string;
+    /** Same generic row treatment as `name` — not validated or used for an avatar. */
     email?: string;
+    /** Same generic row treatment as `name`/`email` — plain string, not a number. */
     rating?: string;
     [key: string]: string | number | null | undefined | (() => ReactNode);
 };
@@ -14,11 +20,10 @@ export type Account = {
 export type ColumnType = {
     id: string;
     title: string;
+    /** Falls back to `colors.primary[500]` when omitted — used for the accent dot/border. */
     color: string;
     items: Account[];
-    /**
-     * Column-level slot (e.g. totals). Shown below the title when expanded, and in the collapsed narrow rail (rotated).
-     */
+    /** Column-level slot (e.g. totals); shown below the title expanded, and rotated in the collapsed rail. */
     customNode?: () => ReactNode;
 };
 /** Fired after a column rail is collapsed or expanded via the board UI. */
@@ -31,16 +36,21 @@ export type ColumnCollapseChangePayload = {
 };
 /** Props for KanbanBoard — keyed columns (`data`) of draggable `Account` cards. */
 export type KanbanBoardProps = {
+    /** Base columns; `customColumns` below is merged on top, not into, this. */
     data: Record<string, ColumnType>;
     /** Merged on top of `data` — a matching column id in both silently overwrites the `data` entry, not merges its fields. */
     customColumns?: Record<string, ColumnType>;
     /** `isVisible` renders an inline dashed column when others exist, or a centered empty-state overlay when there are none. */
     customizeColumn?: {
         isVisible?: boolean;
+        /** Defaults to "Add column". */
         buttonText?: string;
+        /** Fires from both the inline dashed column and the empty-board overlay variant. */
         onAddColumn?: () => void;
     };
+    /** Never fires for a `customNode` card — it owns its own delete UI, and is not gated by `permissions.isDeletable`. */
     onDelete?: (account: Account) => void;
+    /** Same `customNode` exemption as `onDelete`; unlike delete, `onOpen` has no permission gate at all. */
     onOpen?: (account: Account) => void;
     /** Receives the deleted column's item ids, not the column's own id — the column identity itself is not passed. */
     onColumnDelete?: (colId: (string | number)[]) => void;
@@ -53,13 +63,17 @@ export type KanbanBoardProps = {
         fromIndex: number;
         toIndex: number;
     }) => void;
+    /** Also true (skeletons show) whenever `preferences.baseurl` is set and its own fetch is still loading. */
     isLoading?: boolean;
     kanbanSelect?: {
+        /** Gates the whole select — unlike `kanbanEdit`/`kanbanCreate`, never checked against `permissions`. */
         isSelect?: boolean;
         options?: OptionProp[];
         onSelectChange?: (option?: OptionProp) => void;
         selectPlaceholderText?: string;
+        /** Defaults to `"12.5rem"` when omitted. */
         width?: string;
+        /** Controlled value passed straight to the underlying Select. */
         value?: string;
     };
     /** Button shows only when this `isEditable` AND `permissions.isEditable` (default true) both allow it. */
@@ -74,18 +88,27 @@ export type KanbanBoardProps = {
         onCreate?: () => void;
         label?: string;
     };
+    /** true renders cards via a virtualized react-window list; otherwise all cards mount directly. */
     virtualization?: boolean;
     permissions?: {
+        /** Also gates the `kanbanEdit` button and card drag; column-reorder drag ignores this. */
         isEditable?: boolean;
+        /** Also gates the `kanbanCreate` button. */
         isCreatable?: boolean;
+        /** Also hides the column-delete trash icon on column-header hover, not just per-card delete. */
         isDeletable?: boolean;
+        /** false returns null for the whole board — nothing renders, not even header actions. */
         isViewable?: boolean;
     };
     noItems?: {
+        /** Also requires the column to have zero items — evaluated per column, not board-wide. */
         isVisible?: boolean;
+        /** Defaults to "No items in this column". */
         text?: string;
+        /** Defaults to "Add Item"; hidden entirely when `isEmptyTextOnly` is true. */
         buttonText?: string;
         onClick?: (column: ColumnType) => void;
+        /** When true, the button never renders — only the text line shows. */
         isEmptyTextOnly?: boolean;
     };
     /** When true, columns can collapse to a narrow horizontal rail (full height). */
@@ -100,6 +123,7 @@ export type KanbanBoardProps = {
     onColumnReorder?: (columns: Record<string, ColumnType>) => void;
     /** Same shape as Table's `preferences`; collapse state loads/saves to `json.collapsedColumns` only when `baseurl` is set. */
     preferences?: {
+        /** Must be non-empty to activate preferences loading/saving at all. */
         baseurl: string;
         token: string;
         key?: string;

package/dist/Components/OrganizationDetails/OrganizationDetails.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
 import { OrganizationDetailsProps } from "./OrganizationDetailsProps";
+/** Admin panel for the org list — rename/delete/create/invites/default; not a session switcher. */
 declare const OrganizationDetails: React.FC<OrganizationDetailsProps>;
 export default OrganizationDetails;

package/dist/Components/OrganizationDetails/OrganizationDetails.js

@@ -53,6 +53,7 @@ const DEFAULT_LABELS = {
     copyright: "Pixelize Corp. All rights reserved.",
     termsOfService: "Terms of Service",
 };
+/** Admin panel for the org list — rename/delete/create/invites/default; not a session switcher. */
 const OrganizationDetails = ({ activeOrganizations, invitedOrganizations, isLoading = false, switchingOrgIds = [], respondingOrgIds = [], editingOrgIds = [], isCreating = false, userName, userAvatarUrl, onSetDefault, onAcceptInvite, onDeclineInvite, onDeleteOrganization, onDeleteRequest, onCreateOrganization, onEditOrganization, onBack, footerSlot, labels: labelOverrides, }) => {
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     const labels = (0, react_1.useMemo)(() => ({ ...DEFAULT_LABELS, ...labelOverrides }), [labelOverrides]);

package/dist/Components/OrganizationDetails/OrganizationDetailsProps.d.ts

@@ -6,16 +6,16 @@ export type OrganizationItem = {
     company_url?: string;
     /** 1 when this org is the user's default org. */
     default: number;
-    /** 1 = active/accepted, 0 = pending invite. */
+    /** Not read by OrganizationDetails — active vs. invited comes from which array the item is placed in. */
     uiInvite: number;
-    /** 1 always blocks delete, even if canDelete is explicitly true — not overridable like canRename/canDelete are. */
+    /** Distinct from `default` above — only gates delete-protection, not the Default badge/set-default flow. */
     defaultOrg: number;
     roleName?: string;
     /** True when the current user owns this org; the app computes ownership. */
     isOwner?: boolean;
-    /** Overrides the role-name check for the rename control. */
+    /** Overrides the role-name check for rename; omitted, defaults to roleName === "Super Admin". */
     canRename?: boolean;
-    /** Overrides the role-name check for delete — defaultOrg === 1 still blocks it regardless. */
+    /** Same default-if-omitted as canRename; defaultOrg === 1 still blocks delete regardless. */
     canDelete?: boolean;
     /**
      * Why delete is unavailable for this organization, shown on the disabled
@@ -28,6 +28,7 @@ export type CreateOrgFormValues = {
     company_name: string;
     company_address: string;
     phone?: string;
+    /** Never populated by the built-in CreateOrgModal — dead unless your own submit handler sets it. */
     default?: number;
     defaultOrg?: number;
 };
@@ -89,7 +90,9 @@ export interface OrganizationDetailsProps {
     editingOrgIds?: number[];
     userName?: string;
     userAvatarUrl?: string;
+    /** Not awaited internally despite the Promise signature — drive switchingOrgIds yourself. */
     onSetDefault?: (orgId: number) => void | Promise<void>;
+    /** Same as onSetDefault — not awaited internally; respondingOrgIds is entirely consumer-managed. */
     onAcceptInvite?: (orgId: number) => void | Promise<void>;
     onDeclineInvite?: (orgId: number) => void | Promise<void>;
     /**
@@ -107,6 +110,7 @@ export interface OrganizationDetailsProps {
     onCreateOrganization?: (values: CreateOrganizationValues) => void | Promise<void>;
     /** Called when the user confirms a new name for an organization */
     onEditOrganization?: (orgId: number, newName: string) => void | Promise<void>;
+    /** Back icon renders only when this is provided, not merely disabled when omitted. */
     onBack?: () => void;
     footerSlot?: ReactNode;
     labels?: OrganizationDetailsLabels;

package/dist/Components/RolesPermission/RolesPermission.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
 import { RolesPermissionProps } from "./RolesPermissionProps";
+/** Role list + role/permission-matrix form in one component (switch via `view`). */
 declare const RolesPermission: React.FC<RolesPermissionProps>;
 export default RolesPermission;

package/dist/Components/RolesPermission/RolesPermission.js

@@ -56,6 +56,7 @@ const DEFAULT_KEYS = [
     "import",
     "export",
 ];
+/** Role list + role/permission-matrix form in one component (switch via `view`). */
 const RolesPermission = ({ view, mode = "create", roles, isRolesLoading = false, permissions, permissionKeys = DEFAULT_KEYS, roleName, roleNameError, isSuperAdmin, isTrackLocation, isShowRecords, isEditing = false, isSaving = false, onNewRole, onViewRole, onEditRole, onDeleteRole, onBack, onRoleNameChange, onToggleSuperAdmin, onToggleTrackLocation, onToggleShowRecords, onPermissionChange, onSave, onCancelForm, footerSlot, checkIcon, labels: labelOverrides, padding = "16px", }) => {
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     const labels = (0, react_1.useMemo)(() => ({ ...DEFAULT_LABELS, ...labelOverrides }), [labelOverrides]);

package/dist/Components/RolesPermission/RolesPermissionProps.d.ts

@@ -21,6 +21,7 @@ export type RoleData = {
     permission: Permission[];
     /** Coerced via Number() before reaching onDeleteRole — a non-numeric id silently becomes NaN with no error. */
     roles_id: string;
+    /** designation/makeSuperAdmin/automation/trackLocation/show_records: never read by this component — pass-through only, for the consumer to prefill its own form state on edit/view. */
     designation: string;
     makeSuperAdmin?: boolean;
     automation?: boolean;
@@ -83,9 +84,10 @@ export interface RolesPermissionProps {
     permissions: Permission[];
     /** Columns rendered in the matrix. Defaults to all non-automation keys. */
     permissionKeys?: PermissionKey[];
-    /** Form field values (controlled). */
+    /** Form field values — fully controlled, no internal state; edits are invisible without the matching handler below. */
     roleName: string;
     roleNameError?: string;
+    /** Toggling this does not itself grant matrix permissions — it's cosmetic until the consumer applies that logic. */
     isSuperAdmin: boolean;
     isTrackLocation: boolean;
     isShowRecords: boolean;
@@ -99,14 +101,17 @@ export interface RolesPermissionProps {
     onEditRole?: (role: RoleData) => void;
     /** Called synchronously right before the modal closes — no await, no loading state; errors must be surfaced outside this flow. */
     onDeleteRole?: (roleId: number) => void;
+    /** Back icon renders only when this is provided, not merely disabled when omitted. */
     onBack?: () => void;
     /** Form actions. */
     onRoleNameChange?: (value: string) => void;
     onToggleSuperAdmin?: (checked: boolean) => void;
     onToggleTrackLocation?: (checked: boolean) => void;
     onToggleShowRecords?: (checked: boolean) => void;
+    /** Fires with key "automation" (not "read") for a module named "automation" — see Permission.module. */
     onPermissionChange?: (module: string, key: PermissionKey) => void;
     onSave?: () => void;
+    /** Header back icon renders only when set; the footer Cancel button always renders and no-ops without it. */
     onCancelForm?: () => void;
     /** App-specific sections rendered under the roles list (e.g. ModuleDelete, SignInActivity). */
     footerSlot?: ReactNode;

package/dist/Components/ScrollbarBox/ScrollbarBox.d.ts

@@ -2,12 +2,19 @@ import React, { ReactNode } from "react";
 import { ScrollbarVariant } from "../../Theme/tokens/builders/scrollbar";
 export interface ScrollbarBoxProps {
     children: ReactNode;
+    /** Fixed box height; omit to let content size the box instead of scrolling it. */
     height?: string;
+    /** Caps growth and enables scrolling; without it the box grows unbounded. */
     maxHeight?: string;
+    /** No default (unlike overflowY) — falls through to the browser's normal overflow. */
     overflowX?: string;
+    /** Defaults to "auto" — scrolls only once content exceeds height/maxHeight. */
     overflowY?: string;
+    /** Picks the scrollbar chrome from scrollbarStyles; see scrollbar.ts for what each looks like. */
     variant?: ScrollbarVariant;
+    /** Forwarded to the underlying Box so a consumer can read/scroll the container from outside. */
     scrollContainerRef?: React.Ref<HTMLDivElement> | null;
 }
+/** Scrollable Box with themed scrollbar chrome (scrollbarStyles) applied via variant. */
 declare const ScrollbarBox: React.FC<ScrollbarBoxProps>;
 export default ScrollbarBox;

package/dist/Components/ScrollbarBox/ScrollbarBox.js

@@ -4,6 +4,7 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("@chakra-ui/react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
 const scrollbar_1 = require("../../Theme/tokens/builders/scrollbar");
+/** Scrollable Box with themed scrollbar chrome (scrollbarStyles) applied via variant. */
 const ScrollbarBox = ({ children, height, maxHeight, overflowX, overflowY = "auto", variant = "default", scrollContainerRef, }) => {
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     return ((0, jsx_runtime_1.jsx)(react_1.Box, { ref: scrollContainerRef, height: height, maxHeight: maxHeight, position: "relative", sx: { overflowX, overflowY, ...(0, scrollbar_1.scrollbarStyles)(colors, variant) }, children: children }));

package/dist/Components/SearchSelect/SearchSelectProps.d.ts

@@ -2,58 +2,76 @@
 export type SearchSelectProps = {
     id?: string;
     label?: string;
+    /** Filtered against option.label only — a custom `view` node's visible text isn't searchable. */
     options: Options[];
+    /** Required for selections to stick — the component is fully controlled, no internal selected state. */
     onSelect?: (options: Options | Options[] | undefined) => void;
+    /** Fires 1s after typing stops; local filtering against `options` already runs synchronously regardless. */
     onSearch?: (value: string) => void;
     isOptionLoading?: boolean;
+    /** Overrides rightIcon — replaces it with a spinner in the trailing slot whenever true. */
     isLoading?: boolean;
     loadingText?: string;
     placeholder?: string;
     value?: Options[] | Options;
+    /** Only seeds the initial input text at mount — later prop changes don't resync the input. */
     searchQuery?: string;
     isMultiple?: boolean;
+    /** Visual-only — shows the required asterisk on the label; doesn't block selection or submission. */
     isRequired?: boolean;
     error?: boolean;
+    /** Only rendered when `error` is true — setting this alone shows nothing. */
     errorMessage?: string;
+    /** Hidden whenever `error` is true — mutually exclusive with errorMessage. */
     helperText?: string;
     width?: string | number;
+    /** Only sets the insideSelect segment's height, not the main field's — that's driven by `size`. */
     height?: string | number;
     size?: "xs" | "sm" | "md" | "lg";
     chip?: {
         /** 0 is falsy and falls back to "no limit" (shows every chip) — pass 1+ to actually cap the count. */
         maxChips?: number;
         maxText?: number;
+        /** Also gates the chip's remove (X) icon — omit it and chips can't be removed via the chip itself. */
         onClick?: (options: Options | Options[]) => void;
     };
     information?: {
         isInformation?: boolean;
         informationMessage?: string;
     };
+    /** Wins over `information.isInformation` when both are set; both this and informationMessage must be truthy to show the icon. */
     isInformation?: boolean;
     informationMessage?: string;
     rightIcon?: {
+        /** Must be a rendered element (`<Icon />`); anything else fails isValidElement and falls back to the toggle chevron. */
         icon?: React.ReactNode;
         onClick?: () => void;
     };
     addNew?: {
+        /** Must be explicitly true — icon/text/onClick alone render nothing. */
         enabled: boolean;
         icon?: React.ReactNode;
         text?: string;
         onClick?: () => void;
     };
     isRemoveAllIcon?: boolean;
+    /** Ignored entirely unless `isMultiple` is also true. */
     isSelectAll?: boolean;
     pagination?: {
         /** startIndex is 1-based (current options.length + 1), not a 0-based offset. */
         onScroll?: (startIndex: number, limit: number, query: string) => void;
+        /** Also used to guess whether more pages exist (options.length % limit === 0) — an exact-multiple total triggers one extra scroll fetch. */
         limit?: number;
+        /** Set this synchronously while a page request is in flight, or fast scrolling can re-fire onScroll for the same page. */
         scrollLoading?: boolean;
     };
     /** Not implemented — the option list always renders unvirtualized; use `pagination` to page in large datasets instead. */
     virtualization?: boolean;
     insideSelect?: {
         onSelect?: (options: Options) => void;
+        /** In isMultiple mode, its `id` is stamped onto every newly selected main option as `insideSelectId`. */
         value?: Options;
+        /** The nested picker's own option list — distinct from the top-level `options`, singular name despite being an array. */
         option?: Options[];
         width?: string;
         /** Shown when no value is selected. Defaults to "Select". */

package/dist/Components/SideBar/SideBarProps.d.ts

@@ -16,48 +16,35 @@ export type SidebarProps = {
     handleSecondaryNavClick?: (menu: MenuProps) => void;
     toggle: boolean;
     changeToggle: () => void;
+    /** Falls back to a rendered brand mark (DefaultLogo) tinted by primary color when omitted. */
     logo?: string;
     companyName: string;
     companySubtitle?: string;
+    /** Footer identity block is omitted entirely (not just simplified) when this is not provided. */
     user?: SidebarUser;
+    /** true hides the Add New row completely, rather than disabling it. */
     isDisableAddNew?: boolean;
     onAddNewClick?: () => void;
+    /** Threaded down to MenuItemBox but never read there — currently has no effect. */
     selectedSubMenu?: string | null;
     selectedSecondaryItem?: string | number | null;
+    /** Shows skeleton rows instead of MenuItems; header and footer render normally. */
     isLoading?: boolean;
+    /** Defaults to 15 when isLoading is true; ignored otherwise. */
     loadingLines?: number;
     /** Not a direct render switch — on change it calls `changeToggle()` once; nothing collapses unless that updates `toggle`. */
     open?: boolean;
+    /** Legacy "Switch app" grid — AppSwitcher supersedes it; avoid wiring both into one shell. */
     otherApps?: OtherAppsProps['otherApps'];
-    /**
-     * Below the `lg` breakpoint the sidebar renders as a slide-in overlay above
-     * the content (it does not occupy layout space). `mobileOpen` controls that
-     * overlay's visibility; it has no effect at `lg` and up, where the sidebar is
-     * always inline. Wire it to the NavigationBar hamburger (`onSideBarToggole`).
-     */
+    /** Controls the overlay's visibility below `lg`; no effect once inline at `lg`+. Wire to NavigationBar's `onSideBarToggole`. */
     mobileOpen?: boolean;
     /** Called when the overlay is dismissed (backdrop click, Esc, close button, or swipe). */
     onMobileClose?: () => void;
-    /**
-     * Forces the "mobile navbar" presentation at ANY width: the sidebar leaves the
-     * inline layout and behaves as the slide-in overlay (hamburger + full-screen
-     * content), exactly like below `lg` — but on big screens too. This is a layout
-     * switch, not a close: toggling it never hides the navigation, it only changes
-     * how it is presented. When `false` the breakpoint alone decides (inline at
-     * `lg`+, overlay below `lg`).
-     */
+    /** Forces overlay presentation at any width — a layout switch, not a close; never hides navigation. */
     mobileNav?: boolean;
-    /**
-     * Handler for the footer Hide/Show control that flips `mobileNav`. Render the
-     * control only when provided. Wire it so entering mobile-nav also opens the
-     * overlay (keeps the sidebar visible) and leaving it returns to the docked
-     * sidebar — see the playground for the canonical wiring.
-     */
+    /** Backs the footer Hide/Show control; render it only when this is provided. */
     onToggleMobileNav?: () => void;
-    /**
-     * Overlay peek: the sidebar shows without pinning, and closes itself when the pointer
-     * leaves the panel. Wire to `NavigationBar`'s `onSideBarPeek`.
-     */
+    /** Shows the sidebar without pinning — closes on pointer-leave. Wire to NavigationBar's `onSideBarPeek`. */
     peekOpen?: boolean;
     onPeekEnd?: () => void;
 };
@@ -66,18 +53,26 @@ export type MenuProps = {
     id: string | number;
     title: string;
     icon?: ElementType;
+    /** Ignored when subMenu is non-empty — the row becomes a toggle button instead of a link. */
     url: string;
     disabled?: boolean;
+    /** Shows a lock icon only — does not block the click handler; pair with `disabled` to prevent it. */
     locked?: boolean;
+    /** Runtime also accepts a bare number/string (legacy shorthand) though the type only declares the object shape. */
     badge?: {
+        /** Also triggers the small red dot on the icon when the rail is collapsed. */
         count?: number;
+        /** Chakra colorScheme name; defaults to "teal". */
         color?: string;
+        /** Chakra borderRadius value; defaults to "full". */
         radius?: string | number;
+        /** Chakra Badge variant; defaults to "subtle". */
         variant?: string;
     };
     subMenu?: MenuProps[];
     /** Non-empty on the active menu auto-collapses the main rail and renders a SecondaryBar, regardless of the `toggle` prop. */
     secondaryItems?: MenuProps[];
+    /** First item with a new value renders a section label plus divider; items must be pre-sorted by group. */
     group?: string;
 };
 /** Props for the internal MenuItems renderer — a narrowed slice of SidebarProps. */
@@ -92,24 +87,34 @@ export type RenderMenuType = {
 /** Secondary flyout panel props; `defaultCollapsed` only seeds initial state, then the panel self-manages it. */
 export type SecondaryBarProps = {
     items?: MenuProps[];
+    /** Defaults to true (collapsed) when omitted. */
     defaultCollapsed?: boolean;
+    /** Defaults to "3.5rem". */
     collapsedWidth?: string | number;
+    /** Defaults to "10rem". */
     expandedWidth?: string | number;
     headerFontSize?: string;
     itemFontSize?: string;
+    /** Matched by string equality against either the item's id or title, whichever matches. */
     selected?: string | number | null;
     onItemClick?: (item: MenuProps) => void;
+    /** Also used as the collapsed-state tooltip label. */
     title?: string;
+    /** Shown only in the expanded header — hidden entirely while collapsed. */
     icon?: ElementType;
 };
 /** "Switch app" footer grid; becomes hover popovers when the sidebar is collapsed. */
 export type OtherAppsProps = {
     toggle: boolean;
     otherApps: {
+        /** Used as the React list key — must be unique among otherApps entries. */
         name: string;
+        /** Fills the fallback dot (no icon) and its glow — ignored when `icon` is provided. */
         color: string;
+        /** Shown only in the collapsed-state hover flyout, never in the expanded grid cell. */
         description?: string;
         onClick: () => void;
+        /** A pre-rendered ReactNode, unlike MenuProps.icon (a component reference). */
         icon?: React.ReactNode;
     }[];
 };

package/dist/Components/StageProgress/StageProgressProps.d.ts

@@ -9,7 +9,9 @@ export type StageState = "completed" | "active" | "upcoming";
 export type StageVariant = "chevron" | "bar" | "pills" | "stepper";
 /** One entry in StageProgressProps.stages — the ordered pipeline this tracker renders. */
 export interface Stage {
+    /** Compared to `value` via strict `===`; a numeric id vs a string `value` never matches. */
     id: string | number;
+    /** Truncates with an ellipsis (or a tooltip) under chevron/bar/pills; wraps to 2 lines under stepper. */
     label: string;
     /** Disable selecting this stage individually. */
     disabled?: boolean;
@@ -24,7 +26,9 @@ export interface StageProgressProps {
     value?: string | number;
     /** Skipped when isReadOnly, or when that specific stage's own `disabled` is true. */
     onChange?: (id: string | number, stage: Stage, index: number) => void;
+    /** Default "md"; also sets the loading skeleton's row height. */
     size?: StageSize;
+    /** Default "primary"; resolved per stage via resolveStagePalette, not applied directly. */
     colorScheme?: StageColorScheme;
     /** Render stages before the active one in a distinct "done" style. Default true. */
     markCompleted?: boolean;
@@ -43,50 +47,79 @@ export interface StageProgressProps {
 }
 /** Props for one chevron/bar/pills stage; variant="stepper" renders StepperStage/StepperStageProps instead. */
 export interface StageItemProps {
+    /** Ellipsis-truncates in the fixed-width box; see tooltipThreshold for when a tooltip also appears. */
     label: string;
+    /** 0-based position; with total, picks the chevron's first/last point shape. */
     index: number;
+    /** Stage count; with index, drives first/last chevron-point and bar-corner rounding. */
     total: number;
     state: StageState;
     /** "chevron" | "bar" | "pills" (stepper has its own renderer). */
     variant?: Exclude<StageVariant, "stepper">;
+    /** Default "md"; keys this stage's own pixel/spacing lookup table. */
     size?: StageSize;
+    /** Default "primary"; passed straight into resolveStagePalette for this stage. */
     colorScheme?: StageColorScheme;
+    /** Called with no args — StageProgress wraps id/stage/index into this closure itself. */
     onClick?: () => void;
+    /** Disables all interactivity without dimming opacity (unlike disabled). */
     isReadOnly?: boolean;
+    /** Disables just this stage and dims it to 0.55 opacity. */
     disabled?: boolean;
+    /** Adds a check icon before the label only when this stage is completed. */
     showCheck?: boolean;
+    /** Falls back to this size's own fixed minW when unset, not to content width. */
     minWidth?: string;
+    /** Only scrolls when this item's own state is "active" — a no-op otherwise. */
     scrollIntoViewWhenActive?: boolean;
+    /** Character count (not pixels) above which the label swaps to a hover tooltip. */
     tooltipThreshold?: number;
 }
 /** Props for one stepper-variant node; leftDone/rightDone fill the connector line per side. */
 export interface StepperStageProps {
+    /** Wraps up to 2 lines (noOfLines=2) instead of truncating; ignores tooltipThreshold entirely. */
     label: string;
     /** 1-based step number shown inside the circle. */
     number: number;
     state: StageState;
+    /** Default "md"; keys this node's own circle/font/minWidth lookup table. */
     size?: StageSize;
+    /** Default "primary"; passed straight into resolveStagePalette for this node. */
     colorScheme?: StageColorScheme;
+    /** Called with no args — StageProgress's own onChange(id, stage, index) is wrapped upstream. */
     onClick?: () => void;
+    /** Disables interactivity without dimming opacity (unlike disabled). */
     isReadOnly?: boolean;
+    /** Disables this node and dims it to 0.55 opacity. */
     disabled?: boolean;
+    /** Defaults true here (unlike StageItem's false); StageProgress always overrides it explicitly. */
     showCheck?: boolean;
+    /** Hides (not shortens) the left connector line entirely, regardless of leftDone. */
     isFirst: boolean;
+    /** Hides (not shortens) the right connector line entirely, regardless of rightDone. */
     isLast: boolean;
     /** Connector entering this node is part of a completed segment. */
     leftDone: boolean;
     /** Connector leaving this node is part of a completed segment. */
     rightDone: boolean;
+    /** Only scrolls when this node's own state is "active" — a no-op otherwise. */
     scrollIntoViewWhenActive?: boolean;
 }
 /** Color set for one scheme's states, returned by resolveStagePalette (soft/strong/muted + text). */
 export interface StagePalette {
+    /** Background for "completed" stages, and the active stepper circle's outer glow ring. */
     soft: string;
+    /** Text/icon color for "completed" stages, contrast-walked against soft, not a fixed rung. */
     softText: string;
+    /** Background for "active" stages, and the hover fill for completed/upcoming stages. */
     strong: string;
+    /** Text/icon color on strong; picked between white/black per scheme to clear AA. */
     onStrong: string;
+    /** Hover-only background for an already-"active" stage; other states hover to strong instead. */
     hover: string;
+    /** Background for "upcoming" stages; also the unfilled stepper circle's border and idle connector line. */
     muted: string;
+    /** Text color for "upcoming" stages, chevron/bar/pills and stepper alike. */
     mutedText: string;
 }
 /** Resolve a chevron palette for a given color scheme from the theme. */

package/dist/Components/Table/Table.d.ts

@@ -1,2 +1,3 @@
 import { TableProps } from "./TableProps";
+/** Data table: virtualized-height rows, pagination, filters, selection, and an optional Monday-style grouped board. */
 export default function Table({ data, columns, onSelection, isLoading, isCheckbox, headerBgColor, freezedBgColor, freezedTextColor, tableBorderColor, noBorders, isPagination, onRowClick, selections, isActionFreeze, preferences, paginationMode, infiniteScroll, hasMore, isLoadingMore, groupLoadMore, loadMoreText, loadMorePosition, loadMoreChunkSize, noOfRowsPerPage, totalRecords, onPagination, isTableSettings, headerActions, onGlobalSearch, onNoOfRowsPerPageChange, paginationSelectOptions, tableMaxHeight, minVisibleRows, maxVisibleRows, autoFitViewport, tableSettings, filterSidebar, loadingSkeletonRows, defaultVisibleColumns, density, variant, stripe, groupColors, onAddItem, emptyState, onRefresh, }: TableProps): import("react/jsx-runtime").JSX.Element;

package/dist/Components/Table/Table.js

@@ -32,6 +32,7 @@ const Button_1 = __importDefault(require("../Button/Button"));
 const ToolTip_1 = __importDefault(require("../ToolTip/ToolTip"));
 const lucide_react_1 = require("lucide-react");
 const MotionBox = (0, framer_motion_1.motion)(react_2.Box);
+/** Data table: virtualized-height rows, pagination, filters, selection, and an optional Monday-style grouped board. */
 function Table({ data, columns, onSelection, isLoading, isCheckbox = false, headerBgColor, freezedBgColor, freezedTextColor, tableBorderColor, noBorders = false, isPagination = true, onRowClick, selections, isActionFreeze = true, preferences = {
     url: "",
     token: "",

package/dist/Components/Table/TableProps.d.ts

@@ -18,17 +18,25 @@ export type TableEmptyState = {
 export type TableProps = {
     data: DataObject[];
     columns: TableHeaderProps[];
+    /** Hex override per group value; wins over the auto-assigned palette color. Only visible while grouped (Settings > Group). */
     groupColors?: Record<string | number, string>;
+    /** Renders a "+ add item" control in each group's footer row; no-op in flat (ungrouped) mode. */
     onAddItem?: (groupValue: string | number) => void;
+    /** Seeds the initial row height only — Table Settings > Density (or saved preferences.density) takes over after the first change. */
     density?: TableDensity;
     /** Visual preset. Defaults to `classic` — the table exactly as it shipped. */
     variant?: TableVariant;
+    /** Accepted and forwarded to TableBody but never read there — no visual effect (see COMPONENT-GOTCHAS.md). */
     stripe?: boolean;
     emptyState?: TableEmptyState | ReactNode;
+    /** Dead prop — Table renders no export UI and never reads this; declared for a feature that was never wired up. */
     handleExportChange?: (value: string) => void | undefined;
+    /** Dead prop — same unwired export feature as handleExportChange/exportLabel. */
     exportOptions?: ExportOption[];
+    /** Dead prop — same unwired export feature as handleExportChange/exportOptions. */
     exportLabel?: string;
     isLoading?: boolean;
+    /** sic — misspelling of isVisibility, kept for backward compat. Dead: Table never destructures it, so it has no effect. */
     isVisiblity?: boolean;
     isCheckbox?: boolean;
     headerBgColor?: string;
@@ -41,7 +49,9 @@ export type TableProps = {
     selections?: (string | number)[];
     /** Fires per cell, gated on the column: a column with `node` swallows its clicks. */
     onRowClick?: (row: DataObject, header: Record<string | number, string | number>) => void;
+    /** Sticky-positions the trailing action/link column during horizontal scroll. Defaults true. */
     isActionFreeze?: boolean;
+    /** "server" skips client-side slicing entirely — the parent must supply totalRecords and drive paging via onPagination. */
     paginationMode?: "client" | "server";
     infiniteScroll?: boolean;
     hasMore?: boolean;
@@ -54,24 +64,34 @@ export type TableProps = {
     loadMoreChunkSize?: number;
     noOfRowsPerPage?: number;
     totalRecords?: number;
+    /** record is the page's last row on "next"/"last", its first row on "prev"/"first" — a cursor for server paging. */
     onPagination?: (page: number, noOfRecords: number, record: DataObject | undefined, direction: "next" | "prev" | "first" | "last") => void;
     onNoOfRowsPerPageChange?: (noOfRows: number) => void;
     paginationSelectOptions?: (number | string)[];
+    /** Explicit pixel height; overrides autoFitViewport and minVisibleRows/maxVisibleRows outright when set. */
     tableMaxHeight?: number;
+    /** Floors the auto-computed row count used for sizing only — doesn't add rows or affect pagination. */
     minVisibleRows?: number;
+    /** Caps the auto-computed row count used for sizing (paired with minVisibleRows); ignored once tableMaxHeight is set. */
     maxVisibleRows?: number;
+    /** Further clamps computed height to remaining viewport space below the table, recalculated on resize; ignored once tableMaxHeight is set. */
     autoFitViewport?: boolean;
+    /** Hides columns past this index on first render only — a saved preferences.columns list (or a Settings save) wins on every later render. */
     defaultVisibleColumns?: number;
     loadingSkeletonRows?: number;
     headerActions?: HeaderActionsProps;
     onGlobalSearch?: (searchVal: string) => void;
+    /** Dead prop — Table.tsx has it commented out of its own destructure; never called. */
     onColumnFilter?: (filters: FilterValues) => void;
+    /** Gates the Settings gear (Density / Manage Columns / Group) — the real switch for column-visibility UI, unlike tableSettings or isVisiblity. */
     isTableSettings?: boolean;
+    /** Dead prop — TableSettings receives it but never destructures it; these fields currently do nothing. */
     tableSettings?: {
         filters?: string[];
         filterSelected?: string[];
         onFilterSelection?: (filters: string[]) => void;
     };
+    /** filterMode defaults to "sidebar"; Clear All in "modal" mode doesn't re-apply filters (see COMPONENT-GOTCHAS.md). */
     filterSidebar?: Partial<FilterSidebarProps> & {
         isFilterSidebar?: boolean;
         handleSidebarFilterClick?: (filters: FilterValues) => void;
@@ -79,12 +99,19 @@ export type TableProps = {
         isApplyLoading?: boolean;
         filterMode?: "sidebar" | "modal";
     };
+    /** Server-persists columns/density/grouping as one JSON blob (GET on mount, POST on every Settings save). Omitting url (the default) makes it a silent no-op, not an error — the table just doesn't persist. */
     preferences?: {
+        /** Base REST endpoint for both GET and POST; empty string (the default) disables persistence entirely. */
         url: string;
+        /** Sent as a raw Authorization header value — not "Bearer "-prefixed. */
         token: string;
+        /** Distinguishes multiple saved blobs at the same url/page/name (e.g. per-view settings). */
         key?: string;
+        /** Sent alongside key/page as a query param — a server-side identifier, not rendered anywhere. */
         name?: string;
+        /** Identifies which page/screen owns this table's preferences; sent as a query param. */
         page?: string;
+        /** Scopes the preference blob per organization; sent on both GET and POST. */
         orgId?: string;
     };
     onRefresh?: () => void;

package/dist/Components/UserDetails/UserDetails.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
 import { UserDetailsProps } from "./UserDetailsProps";
+/** Two-pane user directory + detail panel with bundled Add/Change-Role/Deactivate modals. */
 declare const UserDetails: React.FC<UserDetailsProps>;
 export default UserDetails;

package/dist/Components/UserDetails/UserDetails.js

@@ -85,6 +85,7 @@ const DEFAULT_LABELS = {
     deactivateConfirmQuestion: "Are you sure you want to deactivate this user?",
     deactivateConfirmDescription: "will no longer have access to the organization. You can reactivate them later if needed.",
 };
+/** Two-pane user directory + detail panel with bundled Add/Change-Role/Deactivate modals. */
 const UserDetails = ({ users, selectedUser, selectedUserId, roleOptions = [], canManageUsers = false, isUsersLoading = false, isInviteLoading = false, isDeactivateLoading = false, isAddUserLoading = false, isChangeRoleLoading = false, onSelectUser, onRefresh, onBack, onAddUserSubmit, onChangeRoleSubmit, onReinvite, onDeactivate, onAddRoleClick, addUserUpgradeNotice, labels: labelOverrides, minHeight = "90vh", }) => {
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     const labels = (0, react_1.useMemo)(() => ({ ...DEFAULT_LABELS, ...labelOverrides }), [labelOverrides]);

package/dist/Components/UserDetails/UserDetailsProps.d.ts

@@ -10,6 +10,7 @@ export type UserListItem = {
     firstName: string;
     lastName: string;
     email: string;
+    /** Display-only — UserDetails never reads this in the list row itself, only in SelectedUserDetail once selected. */
     role: string;
     profile?: string;
     isActive: boolean;
@@ -29,11 +30,15 @@ export type SelectedUserDetail = {
     /** When null, Change Role and Resend Invitation silently no-op on click (no disabled state) — unlike Deactivate, which greys out. */
     userId?: number;
     name: string;
+    /** Feeds ChangeRoleModal's currentRole — must case-insensitively match a roleOptions[].label or the modal opens with nothing pre-selected. */
     role: string;
+    /** Shown only inside ChangeRoleModal's header — the Personal Information panel does not render this field, only `details`. */
     email: string;
     profilePhoto?: string;
     isActive: boolean;
+    /** Renders the "Pending Invitation" badge only — does not affect which action buttons show. */
     isPending?: boolean;
+    /** Hides Resend Invitation and Deactivate (both gated on !isCurrent) and shows a "You" badge on the avatar. */
     isCurrent?: boolean;
     /** True hides the entire action bar (reinvite/change-role/deactivate), not just the deactivate button. */
     isSuperAdmin?: boolean;
@@ -106,6 +111,7 @@ export interface UserDetailsProps {
     canManageUsers?: boolean;
     /** Loading flags driven by the host app's async calls. */
     isUsersLoading?: boolean;
+    /** Spins only the Resend Invitation button, not the list or either modal. */
     isInviteLoading?: boolean;
     /** Unlike isAddUserLoading/isChangeRoleLoading, the confirm modal closes immediately on click — this flag can't keep it open to show a spinner. */
     isDeactivateLoading?: boolean;
@@ -113,12 +119,15 @@ export interface UserDetailsProps {
     isChangeRoleLoading?: boolean;
     /** Selection + refresh. */
     onSelectUser?: (user: UserListItem) => void;
+    /** Omitting this hides the refresh button entirely, not just disables it. */
     onRefresh?: () => void;
     /** Back navigation handler for the list panel header. */
     onBack?: () => void;
     /** Modal submit / action callbacks. */
     onAddUserSubmit?: (values: AddUserFormValues) => void | Promise<void>;
+    /** Awaited before the modal closes — unlike onDeactivate, which fires and closes immediately. */
     onChangeRoleSubmit?: (payload: ChangeRoleSubmitPayload) => void | Promise<void>;
+    /** Never called when selectedUser.userId is null — the button stays enabled but silently no-ops. */
     onReinvite?: (userId: number) => void;
     /** Not awaited — the confirm modal closes right after this fires, so a slow or failing deactivation gets no in-modal feedback. */
     onDeactivate?: (userId: number) => void;
@@ -140,12 +149,14 @@ export interface AddUserModalProps {
     onSubmit?: (values: AddUserFormValues) => void | Promise<void>;
     onAddRoleClick?: () => void;
     upgradeNotice?: ReactNode;
+    /** A strict subset of UserDetailsLabels — the merged defaults from UserDetails always satisfy it. */
     labels: Required<Pick<UserDetailsLabels, "addNewUser" | "firstName" | "lastName" | "email" | "role" | "firstNamePlaceholder" | "lastNamePlaceholder" | "emailPlaceholder" | "addNewRole" | "cancel" | "save" | "firstNameRequired" | "lastNameRequired" | "emailRequired" | "emailInvalid" | "roleRequired">>;
 }
 /** Reassigns one user's role only — Save stays disabled until a genuinely different role is picked (see currentRole below). */
 export interface ChangeRoleModalProps {
     isOpen: boolean;
     onClose: () => void;
+    /** Submit silently no-ops when null — Save disables only for isUnchanged/no-selection, not for this. */
     userId: number | null;
     email?: string;
     /** Matched to roleOptions by case-insensitive label text; no match silently pre-selects nothing and leaves Save disabled. */
@@ -161,7 +172,9 @@ export interface DeactivateConfirmModalProps {
     isOpen: boolean;
     onClose: () => void;
     userName?: string;
+    /** Effectively unusable — the modal always closes before an async confirm could flip this. */
     isLoading?: boolean;
+    /** Synchronous by type — the modal closes in the same tick this fires, so it can't be awaited. */
     onConfirm: () => void;
     labels: Required<Pick<UserDetailsLabels, "confirmDeactivation" | "deactivateConfirmQuestion" | "deactivateConfirmDescription" | "cancel" | "deactivateUser">>;
 }

package/dist/esm/Components/Apexcharts/ApexBarChart/ApexBarChart.js

@@ -4,6 +4,7 @@ import ReactApexChart from "react-apexcharts";
 import { useTheme } from "@chakra-ui/react";
 import { chartAxisLabelColor, getDefaultSeriesColors, mergeChartTitleStyle, } from "../../../Theme/tokens/builders/chartColorsFromTheme.js";
 import { baseAxisLabels, baseChart, baseGrid, baseLegend, baseTooltip } from "../chartBase.js";
+/** Bar chart wrapper around react-apexcharts (horizontal/stacked/distributed via props), themed via chartColorsFromTheme + chartBase. */
 export default function ApexBarChart({ data, labels, title, titlePosition, height = 400, width = 500, barColor, xAxisStyle, yAxisStyle, titleStyle, horizontal = false, distributed = false, seriesName = "Data", series, stacked = false, showLegend, legendPosition = "bottom", }) {
     const theme = useTheme();
     const palette = theme.colors;

package/dist/esm/Components/Apexcharts/ApexLineChart/ApexLineChart.js

@@ -5,6 +5,7 @@ import { useTheme } from "@chakra-ui/react";
 import ToolTip from "../../ToolTip/ToolTip.js";
 import { getDefaultSeriesColors, mergeChartTitleStyle, } from "../../../Theme/tokens/builders/chartColorsFromTheme.js";
 import { baseAxisLabels, baseChart, baseGrid, baseTooltip } from "../chartBase.js";
+/** Line chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 const ApexLineChart = ({ data, labels, title, height, width, lineColors, titlePosition = "center", titleStyle, compact = false, toolbarBreakpointPct = 0.6, titleClampLines, showTitleEllipsis = true, showSeries = true, series: seriesNames, variant = "basic", }) => {
     const theme = useTheme();
     const palette = theme.colors;

package/dist/esm/Components/Apexcharts/ApexPieChart/ApexPieChart.js

@@ -12,6 +12,7 @@ const getValidLegendPosition = (position) => {
     console.warn(`Invalid legend position: ${position}. Defaulting to 'bottom'.`);
     return "bottom";
 };
+/** Pie/donut chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 const ApexPieChart = ({ data, labels, title, height = 400, width = 500, donutColors, chartColor, titlePosition = "center", titleStyle, legendPosition = "bottom", legendStyle, variant = "pie", showDataLabels = true, minLabelPercent = 8, surfaceColor, donutSize = "68%", totalLabel = "Total", labelPlacement = "auto", }) => {
     var _a;
     const { colors: palette } = useCustomTheme();

package/dist/esm/Components/Apexcharts/ApexPolarCharts/ApexPolarCharts.js

@@ -4,6 +4,7 @@ import ReactApexChart from "react-apexcharts";
 import { useTheme } from "@chakra-ui/react";
 import { chartInk, chartMode, getDefaultSeriesColors, mergeChartTitleStyle, } from "../../../Theme/tokens/builders/chartColorsFromTheme.js";
 import { baseChart, baseLegend, baseTooltip } from "../chartBase.js";
+/** Polar-area chart wrapper around react-apexcharts, themed via chartColorsFromTheme + chartBase. */
 const ApexPolarChart = ({ data, labels, title, height = 400, width = 500, chartColors, titlePosition = "center", titleStyle, legendStyle, variant = "basic", }) => {
     const theme = useTheme();
     const palette = theme.colors;

package/dist/esm/Components/OrganizationDetails/OrganizationDetails.js

@@ -48,6 +48,7 @@ const DEFAULT_LABELS = {
     copyright: "Pixelize Corp. All rights reserved.",
     termsOfService: "Terms of Service",
 };
+/** Admin panel for the org list — rename/delete/create/invites/default; not a session switcher. */
 const OrganizationDetails = ({ activeOrganizations, invitedOrganizations, isLoading = false, switchingOrgIds = [], respondingOrgIds = [], editingOrgIds = [], isCreating = false, userName, userAvatarUrl, onSetDefault, onAcceptInvite, onDeclineInvite, onDeleteOrganization, onDeleteRequest, onCreateOrganization, onEditOrganization, onBack, footerSlot, labels: labelOverrides, }) => {
     const { colors } = useCustomTheme();
     const labels = useMemo(() => ({ ...DEFAULT_LABELS, ...labelOverrides }), [labelOverrides]);

package/dist/esm/Components/RolesPermission/RolesPermission.js

@@ -51,6 +51,7 @@ const DEFAULT_KEYS = [
     "import",
     "export",
 ];
+/** Role list + role/permission-matrix form in one component (switch via `view`). */
 const RolesPermission = ({ view, mode = "create", roles, isRolesLoading = false, permissions, permissionKeys = DEFAULT_KEYS, roleName, roleNameError, isSuperAdmin, isTrackLocation, isShowRecords, isEditing = false, isSaving = false, onNewRole, onViewRole, onEditRole, onDeleteRole, onBack, onRoleNameChange, onToggleSuperAdmin, onToggleTrackLocation, onToggleShowRecords, onPermissionChange, onSave, onCancelForm, footerSlot, checkIcon, labels: labelOverrides, padding = "16px", }) => {
     const { colors } = useCustomTheme();
     const labels = useMemo(() => ({ ...DEFAULT_LABELS, ...labelOverrides }), [labelOverrides]);

package/dist/esm/Components/ScrollbarBox/ScrollbarBox.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { Box } from "@chakra-ui/react";
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
 import { scrollbarStyles, } from "../../Theme/tokens/builders/scrollbar.js";
+/** Scrollable Box with themed scrollbar chrome (scrollbarStyles) applied via variant. */
 const ScrollbarBox = ({ children, height, maxHeight, overflowX, overflowY = "auto", variant = "default", scrollContainerRef, }) => {
     const { colors } = useCustomTheme();
     return (_jsx(Box, { ref: scrollContainerRef, height: height, maxHeight: maxHeight, position: "relative", sx: { overflowX, overflowY, ...scrollbarStyles(colors, variant) }, children: children }));

package/dist/esm/Components/Table/Table.js

@@ -26,6 +26,7 @@ import Button from "../Button/Button.js";
 import ToolTip from "../ToolTip/ToolTip.js";
 import { Filter, EllipsisVertical, X, RefreshCw } from "lucide-react";
 const MotionBox = motion(Box);
+/** Data table: virtualized-height rows, pagination, filters, selection, and an optional Monday-style grouped board. */
 export default function Table({ data, columns, onSelection, isLoading, isCheckbox = false, headerBgColor, freezedBgColor, freezedTextColor, tableBorderColor, noBorders = false, isPagination = true, onRowClick, selections, isActionFreeze = true, preferences = {
     url: "",
     token: "",

package/dist/esm/Components/UserDetails/UserDetails.js

@@ -47,6 +47,7 @@ const DEFAULT_LABELS = {
     deactivateConfirmQuestion: "Are you sure you want to deactivate this user?",
     deactivateConfirmDescription: "will no longer have access to the organization. You can reactivate them later if needed.",
 };
+/** Two-pane user directory + detail panel with bundled Add/Change-Role/Deactivate modals. */
 const UserDetails = ({ users, selectedUser, selectedUserId, roleOptions = [], canManageUsers = false, isUsersLoading = false, isInviteLoading = false, isDeactivateLoading = false, isAddUserLoading = false, isChangeRoleLoading = false, onSelectUser, onRefresh, onBack, onAddUserSubmit, onChangeRoleSubmit, onReinvite, onDeactivate, onAddRoleClick, addUserUpgradeNotice, labels: labelOverrides, minHeight = "90vh", }) => {
     const { colors } = useCustomTheme();
     const labels = useMemo(() => ({ ...DEFAULT_LABELS, ...labelOverrides }), [labelOverrides]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelize-design-library",
-  "version": "2.4.2-beta.39",
+  "version": "2.4.2-beta.40",
   "description": "React component library for Pixelize apps: themeable Chakra-based components, design tokens and light/dark brand theming.",
   "keywords": [
     "react",