pixelize-design-library 2.4.2-beta.36 → 2.4.2-beta.37

package/COMPONENT-GOTCHAS.md

@@ -0,0 +1,135 @@
+# Component Gotchas & Decision Guide
+
+For anyone — human or AI — consuming `pixelize-design-library` in an app. Read this **before**
+choosing a component or a prop value, not after something looks wrong. Every entry below compiles
+cleanly, accepts what you pass, and produces the wrong result with no warning — TypeScript cannot
+catch any of these, and a unit suite that mocks the library won't either.
+
+This file ships inside the published package (`node_modules/pixelize-design-library/COMPONENT-GOTCHAS.md`)
+so it's available without checking out the library's source repo.
+
+---
+
+## Choosing between components
+
+### Segmented control look — `SegmentedControl` / `Toggle/TableToggle`
+
+Both take `variant?: "default" | "brandSlide" | "underlineSlide"` (default `"default"` — always
+opt-in, never assume a non-default look).
+
+| Context | `variant` | Look |
+| --- | --- | --- |
+| Most call sites — settings rows, filters, table view switches | `"default"` | Neutral chip |
+| The primary, hard-to-miss view switcher on a page (not a dense toolbar) | `"brandSlide"` | Solid brand-filled pill slides behind the active segment |
+| A dense toolbar, table header, or anywhere a boxed control feels heavy | `"underlineSlide"` | Thin brand-colored bar glides under the active label, no fill/chip |
+
+Pick by density and emphasis, not by taste. When unsure, or migrating an existing call site, leave
+it on `"default"` — it's the only variant guaranteed to match previously-shipped screenshots.
+
+### Which "select" component — seven components overlap in name, not purpose
+
+**Not picking a value from an options list at all:**
+
+| Doing | Component | Why not the others |
+| --- | --- | --- |
+| Triggering a labelled *action* (export, row menu, "...") | `Dropdown` | A menu-button, not a form field — nothing is "selected" and persisted |
+| Typing free-text tags (e.g. email addresses), no options list | `MultiSelect` | Despite the name, there is nothing to pick from — see gotcha below |
+| Choosing which *fields/columns* to include, in a modal, from a checkbox grid | `FieldSelectModal` | Multi-checkbox selection UI, not an inline field control |
+
+**Picking one or more values from an options list, inline in a form:**
+
+| List length / need | Component | Why |
+| --- | --- | --- |
+| Short, always-visible list, no search needed | `Select` | Native `<select>` wrapper — lightest option, but the popup is OS-painted and can't be themed |
+| New build, want themed/custom-rendered rows (icons, descriptions), no huge list | `SelectV2` | Fully React-rendered popup — **prefer this for new work** over `Select` |
+| Long list needing search + chips + select-all + infinite scroll | `SearchSelect` | The full-featured picker; virtualizes |
+| Search-as-you-type with avatars/colour swatches/a pinned "add new" row | `SelectSearch` | Lighter than `SearchSelect`; reach for it for that specific row-content need |
+
+Default when unsure: `SelectV2` for a themed field, `Select` if the native popup is genuinely fine.
+
+---
+
+## Known gotchas (silent failures)
+
+### `Drawer` / `Modal` / `ProfileCard` drop any child that isn't a named slot
+
+All three match children by exact type (`child.type === XHeader/XBody/XFooter`) and render only
+those matches — nothing else in `children` is ever read. Two consequences: a sibling among the
+slots (a nested `Modal`, `AlertDialog`, a confirm dialog, a portal after the footer) silently never
+mounts; and a slot wrapped in a `<>...</>` fragment is dropped too, because the matching doesn't
+unwrap fragments — a fragment's `.type` is `Fragment`, never the slot component.
+
+**Apply:** put a confirm dialog **outside** the `Drawer`/`Modal`/`ProfileCard`, as a sibling in a
+wrapping fragment — never among the header/body/footer slots. When a ternary picks between bodies,
+branch into a variable rendered inside one body slot, rather than returning fragment-wrapped slots
+per branch.
+
+### `Select`'s `onChange` never fires for the built-in placeholder
+
+`Select` resolves the changed value against its `options` list and calls `onChange` only on a hit.
+The built-in `placeholder` renders as its own empty-value option, which isn't in `options` — so
+picking it resolves to no match and nothing fires. An "Any / All / None" reset built on the
+placeholder alone is a dead control; the value snaps back and no filter clears.
+
+**Apply:** fine for a plain pick-one-of-N. For a clearable filter, add an explicit
+`{ id: "", label: "Any" }` entry to `options` instead of relying on the placeholder.
+
+### `MultiSelect` is an email-chip input, not a picker
+
+Despite the name, `MultiSelect` takes **no `options` prop at all**. Typed text is validated as an
+email address and rejected if it doesn't match — there is no way to choose from a product/entity
+list.
+
+**Apply:** use `SearchSelect` with `isMultiple` to pick multiple values from an options list.
+
+### `RadioButton` has a closed prop list — no `...rest`, no `name`
+
+It forwards only a fixed set of props (`label`, `colorScheme`, `isChecked`, `onChange`,
+`isDisabled`, `size`, `value`, `defaultChecked`, plus label/tooltip props) to the underlying radio
+— a `data-*` hook, `aria-describedby`, or a `ref` cannot reach it.
+
+**Apply:** it still joins an external `RadioGroup` correctly (grouping comes from context, no
+`name` prop needed) — don't avoid it just for grouping. Reach for the library's Chakra escape
+hatch only when you need something outside that closed list.
+
+### `Table`'s `onRowClick` is dead if every column has a `node` renderer
+
+Row-click is gated **per column**, not per row: a column supplying a custom `node` renderer
+swallows the click on that cell. Give every column a `node` and `onRowClick` becomes dead code —
+accepted, typed, never called.
+
+**Apply:** leave at least one column without a `node`, or put an explicit control inside a `node`
+renderer instead of relying on row click.
+
+### `InputTextArea`'s `width` defaults to the number `500`, and no `id` means no label
+
+`width` defaults to `500`, forwarded straight through — `500` isn't a sizing-scale key, so it
+renders a literal `500px`, not a max and not responsive. It only shows up on a narrow screen.
+Separately, `id` feeds both the visible label and the field itself with no fallback — omit it and
+the label is associated with nothing; the field has no accessible name.
+
+**Apply:** pass `width="100%"` **and** `id` at every call site.
+
+### `error` without `errorMessage` renders the literal word "Error" — and erases `helperText`
+
+Every field that shows validation errors (`TextInput`, `InputTextArea`, `Select`, `MultiSelect`,
+`SelectV2`, `SearchSelect`, `SelectSearch`, `Search`, `Checkbox`, the `DatePicker` variants,
+`PhoneNumberInput`) falls back to the literal word **"Error"** when `error` is `true` but
+`errorMessage` is empty. Worse, `helperText` only renders when `!error` — so the guidance
+disappears exactly when it's needed.
+
+**Apply:** never pass `error` without `errorMessage`. Gate `error` on a `touched` flag so a field
+whose defaults arrive asynchronously doesn't open already red.
+
+### A wrapper presetting a prop must destructure with a default, not rely on JSX prop order
+
+Wrapping a library component to preset a prop (e.g. `Table`'s `variant`) as
+`<Table variant="studio" {...props} />` silently reverts to the library's own default the moment a
+caller passes `variant={undefined}` — a later spread always wins in JSX, even with `undefined`,
+and the library component resolves that `undefined` via its own default parameter.
+
+**Apply:**
+```tsx
+const AppTable = ({ variant = 'studio', ...props }: TableProps) => <Table variant={variant} {...props} />;
+```
+Applies to any library prop with a default value, not just `Table`'s `variant`.

package/README.md

@@ -2,6 +2,11 @@
 
 A comprehensive React component library built with TypeScript, providing a rich set of UI components for modern web applications.
 
+> **Building with this library (including via an AI assistant)?** Read
+> [COMPONENT-GOTCHAS.md](./COMPONENT-GOTCHAS.md) first — it documents known silent-failure traps
+> and which near-duplicate component to pick for what. It ships with this package, so it's
+> available at `node_modules/pixelize-design-library/COMPONENT-GOTCHAS.md` too.
+
 ## Features
 
 - 🎨 **Modern Design System** - Consistent and beautiful components

package/dist/Components/Common/ErrorMessage.js

@@ -4,8 +4,8 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("@chakra-ui/react");
 const lucide_react_1 = require("lucide-react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
-// `id` lets a field point `aria-describedby` here so the message is part of the control's
-// description on every focus. `role="alert"` alone announces once, when it first renders.
+// `id` lets a field point `aria-describedby` here; `role="alert"` announces once, on render.
+// Always pass `errorMessage` when `error` is true — omitted, this renders the literal word "Error", and every caller hides `helperText` while `error` is true.
 const ErrorMessage = ({ errorMessage, id }) => {
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     return ((0, jsx_runtime_1.jsxs)(react_1.Flex, { id: id, align: "center", color: colors.semanticText.error, fontSize: "0.875rem", role: "alert", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.Info, { width: "0.875rem" }), (0, jsx_runtime_1.jsx)(react_1.Text, { ml: "0.188rem", children: errorMessage !== null && errorMessage !== void 0 ? errorMessage : "Error" })] }));

package/dist/Components/Drawer/DrawerProps.d.ts

@@ -3,5 +3,6 @@ export type DrawerProps = Pick<ChakraDrawerProps, "isOpen" | "onClose" | "placem
     size?: "xs" | "sm" | "md" | "lg" | "xl" | "full";
     placement?: "top" | "right" | "bottom" | "left";
     vaiant?: "solid" | "outline" | "ghost" | "link";
+    /** Only DrawerHeader/DrawerBody/DrawerFooter render; other elements and fragment-wrapped slots are silently dropped. */
     children?: React.ReactNode;
 };

package/dist/Components/InputTextArea/InputTextAreaProps.d.ts

@@ -1,4 +1,5 @@
 import { TextareaProps } from "@chakra-ui/react";
+/** width defaults to 500 → literal "500px", not responsive (pass "100%"); id is required or the label has no accessible association. */
 export type InputTextAreaProps = Pick<TextareaProps, "placeholder" | "value" | "onChange" | "onBlur" | "name" | "id" | "size" | "resize" | "isDisabled" | "isReadOnly" | "isRequired" | "variant" | "autoComplete"> & {
     label?: string;
     error?: boolean;

package/dist/Components/Modal/ModalProps.d.ts

@@ -5,6 +5,7 @@ export type ChakraModelProps = Pick<ModalProps, "isOpen" | "onClose" | "finalFoc
     overlaybackdropInvert?: string;
     overlaybackdropBlur?: string;
     size: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "full";
+    /** Only ModalHeader/ModalBody/ModalFooter render; other elements and fragment-wrapped slots are silently dropped. */
     children?: React.ReactNode;
     isLoading?: boolean;
 };

package/dist/Components/MultiSelect/MultiSelectProps.d.ts

@@ -1,3 +1,4 @@
+/** No `options` prop — typed text is validated as an email, not picked from a list; use `SearchSelect isMultiple`. */
 export type MultiSelectProps = {
     value: MultiSelctOPtions[];
     onValueChange: (options: MultiSelctOPtions[]) => void;

package/dist/Components/ProfileCard/ProfileCardProps.d.ts

@@ -3,6 +3,7 @@ export type ProfileCardVariant = "elevated" | "outline" | "filled" | "unstyled";
 /** @deprecated Misspelling kept for existing callers — use "outline". */
 export type ProfileCardVariantLegacy = "outlein";
 export type ProfileCardProps = Pick<CardProps, "direction" | "maxW" | "align" | "justify" | "overflow"> & {
+    /** Only direct ProfileCardHeader/Body/Footer children render — no wrapping fragment, no other siblings. */
     children: React.ReactNode;
     variant?: ProfileCardVariant | ProfileCardVariantLegacy;
     size?: "sm" | "md" | "lg";

package/dist/Components/RadioButton/RadioButtonProps.d.ts

@@ -1,4 +1,5 @@
 import { RadioProps, RadioGroupProps } from '@chakra-ui/react';
+/** Closed prop list, no ...rest — for aria-* or a ref use Chakra's Radio (Primitives barrel) instead. Still joins an external RadioGroup correctly via Chakra's own context. */
 export type ChakraRadioProps = Pick<RadioProps, "size" | "colorScheme" | "isChecked" | "onChange" | "isDisabled" | "value" | "defaultChecked"> & {
     label: string;
     labelFontSize?: string;

package/dist/Components/Select/SelectProps.d.ts

@@ -10,6 +10,7 @@ export type chakraSelectProps = Pick<SelectProps, "placeholder" | "size" | "vari
     options: OptionProp[];
     width?: string | number;
     height?: string | number;
+    /** Selecting the built-in placeholder (value="") never fires this unless `options` has an explicit `id: ""` entry. */
     onChange: (selectedOption: OptionProp | undefined) => void;
     formControlStyle?: React.CSSProperties;
     isInformation?: boolean;

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

@@ -36,6 +36,7 @@ export type TableProps = {
     onSelection?: (selected: (string | number)[]) => void;
     isPagination?: boolean;
     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;
     isActionFreeze?: boolean;
     paginationMode?: "client" | "server";

package/dist/esm/Components/Common/ErrorMessage.js

@@ -2,8 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Flex, Text, } from "@chakra-ui/react";
 import { Info } from "lucide-react";
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
-// `id` lets a field point `aria-describedby` here so the message is part of the control's
-// description on every focus. `role="alert"` alone announces once, when it first renders.
+// `id` lets a field point `aria-describedby` here; `role="alert"` announces once, on render.
+// Always pass `errorMessage` when `error` is true — omitted, this renders the literal word "Error", and every caller hides `helperText` while `error` is true.
 const ErrorMessage = ({ errorMessage, id }) => {
     const { colors } = useCustomTheme();
     return (_jsxs(Flex, { id: id, align: "center", color: colors.semanticText.error, fontSize: "0.875rem", role: "alert", children: [_jsx(Info, { width: "0.875rem" }), _jsx(Text, { ml: "0.188rem", children: errorMessage !== null && errorMessage !== void 0 ? errorMessage : "Error" })] }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelize-design-library",
-  "version": "2.4.2-beta.36",
+  "version": "2.4.2-beta.37",
   "description": "React component library for Pixelize apps: themeable Chakra-based components, design tokens and light/dark brand theming.",
   "keywords": [
     "react",
@@ -28,7 +28,8 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "COMPONENT-GOTCHAS.md"
   ],
   "dependencies": {
     "@fontsource-variable/inter": "^5.2.8",
@@ -151,7 +152,6 @@
     "jest": "^29.7.0",
     "jest-axe": "^11.0.0",
     "jest-environment-jsdom": "^29.7.0",
-    "path": "^0.12.7",
     "postcss": "^8.5.4",
     "prettier": "^3.3.2",
     "prop-types": "^15.8.1",