@telicent-oss/ds 4.4.2 → 5.0.1

package/dist/llms.txt

@@ -1,6 +1,6 @@
 # Telicent DS Component Manifest
 
-**VERSION:** This file documents @telicent-oss/ds v4.4.2. It shipped inside that package, so it matches the version installed in your project. If that package was built locally rather than installed from npm, the code may be newer than v4.4.2.
+**VERSION:** This file documents @telicent-oss/ds v5.0.1. It shipped inside that package, so it matches the version installed in your project. If that package was built locally rather than installed from npm, the code may be newer than v5.0.1.
 
 > `@telicent-oss/ds` is Telicent's MUI-based React component library. This file is the complete, self-contained reference: setup, theming, every exported component, and copy-paste recipes. An agent that fetches it has what it needs to build a Telicent app UI without reading the source.
 
@@ -32,11 +32,11 @@ Wrap the app in `UIThemeProvider`. It supplies the MUI theme and `CssBaseline` i
 ```tsx
 import { UIThemeProvider } from "@telicent-oss/ds";
 
-<UIThemeProvider theme="DataNavy" dark={false}>
+<UIThemeProvider theme="DocumentPink" dark={false}>
   <App />
 </UIThemeProvider>
 ```
-- `theme` (required): one of `"DataNavy"`, `"DocumentPink"`, `"GraphOrange"`, `"AdminBlue"`, `"Blank"`.
+- `theme` (required): one of `"DocumentPink"`, `"GraphOrange"`, `"AdminBlue"`, `"GeoGreen"`, `"Blank"`.
 - `dark` (optional, default `false`): set it for the dark palette. Dark mode is this prop only — there is no runtime toggle or CSS class.
 
 Read theme colours and tokens in app code with the `useExtendedTheme` hook. This is the sanctioned way to set a colour — use it instead of a Tailwind colour class:
@@ -248,9 +248,22 @@ Usage: https://github.com/telicent-oss/telicent-ds/blob/main/src/components/surf
 
 Demonstrated states:
 - ResizeBaseline — bounds="parent", title="Resize baseline", targetId="map", iconBeforeTitle=<jsx>
-* **`Drawer`**: Collapsible side panel with a built-in toggle tab. `children` is the panel content; `drawerWidth` sets its open width; `initialOpen` sets the starting state; `onVisibilityChange(open)` and `onToggle` report toggles. Style the surface with `PaperProps` / `PaperSx`.
+* **`Drawer`**: Controlled side sheet for a task beside the page (filters, details). Pass `open`/`onClose` and `width`; header, scrolling body and footer are children.
 ```yaml
 Drawer:
+  width: {type: 'string | number', required: false}
+```
+Live: https://telicent-oss.github.io/telicent-ds/?path=/docs/surfaces-drawer--docs
+Usage: https://github.com/telicent-oss/telicent-ds/blob/main/src/components/surfaces/Drawer/Drawer.stories.tsx
+
+Demonstrated states:
+- Default — open=false
+- Width — open=false, width=420
+- CappedAtViewport — open=false, width=1600
+- HeaderBodyFooter — open=false, width=420
+* **`InsetDrawer`** *(deprecated, use `Drawer`)*: The map inset's collapsible side panel with a built-in toggle tab. `children` is the panel content; `drawerWidth` sets its open width; `initialOpen` sets the starting state; `onVisibilityChange(open)` and `onToggle` report toggles. Style the surface with `PaperProps` / `PaperSx`.
+```yaml
+InsetDrawer:
   children: {type: 'React.ReactNode', required: true}
   drawerWidth: {type: 'number', required: false}
   id: {type: 'string', required: false}
@@ -260,8 +273,8 @@ Drawer:
   PaperProps: {type: 'Partial<PaperProps<React.ElementType<any, keyof React.JSX.IntrinsicElements>>>', required: false}
   PaperSx: {type: 'SxProps<Theme>', required: false}
 ```
-Live: https://telicent-oss.github.io/telicent-ds/?path=/docs/component-library-drawer--docs
-Usage: https://github.com/telicent-oss/telicent-ds/blob/main/src/feature-components/Drawer/composites/Drawer.stories.tsx
+Live: https://telicent-oss.github.io/telicent-ds/?path=/docs/component-library-insetdrawer--docs
+Usage: https://github.com/telicent-oss/telicent-ds/blob/main/src/feature-components/Drawer/composites/InsetDrawer.stories.tsx
 
 Demonstrated states:
 - Default — children=<jsx>
@@ -657,6 +670,55 @@ Demonstrated states:
 - Outlined — variant="outlined"
 - ClickableChips
 - DeletableChips
+* **`Badge`**: A count or dot on another element. Put the count in the host's accessible name; the badge is hidden from screen readers.
+```yaml
+Badge: {} # no own props; all inherited from the underlying MUI/DOM element
+```
+Live: https://telicent-oss.github.io/telicent-ds/?path=/docs/data-display-badge--docs
+Usage: https://github.com/telicent-oss/telicent-ds/blob/main/src/components/data-display/Badge/Badge.stories.tsx
+
+Demonstrated states:
+- OnIconButton — badgeContent=2
+- ZeroHidden — badgeContent=0
+- Max — badgeContent=120, max=99
+- Dot — variant="dot", badgeContent=1
+- AnnouncedBadge — badgeContent=3, slotProps={…}
+* **`EntityList`**: Navigational list of entities where each row opens a detail page — users, groups, clients, service accounts. Uses the ARIA list pattern (`<section>` → `<ul>` → `<a href>`) so screen readers announce "link, View Alice", not the grid-pattern "row 3 of 24, cell 1 of 5" that `DataGrid` would. Required props: `items`, `columns`, `getItemKey`, and one of `ariaLabel` or `ariaLabelledBy` (XOR-required at the type level so the landmark is never unnamed). Set `getItemHref` + `getItemLabel` to make rows navigate; omit `getItemHref` for display-only (permission-gated) views — rows render as inert with no chevron, hover tint, or focus outline. Pass `onItemClick(item, href)` to intercept plain left-clicks for SPA routing — modifier-click (cmd/ctrl/shift/alt) and non-primary mouse buttons always fall through to native anchor behaviour, so cmd-click opens a new tab even in SPAs with zero extra code. Columns are sortable iff `getSortValue` is provided; sort state is encoded in the sort button's accessible name via `visuallyHidden`, no `aria-sort` on a non-grid element. `defaultPageSize` seeds initial state and the user then controls the dropdown — the prop is not reactive. Loading state renders skeleton rows that mirror the column layout; empty state is customisable via `renderEmpty`. Reach for `DataGrid` instead when the data is genuinely tabular/analytical — filterable columns, cell editing, column reordering, server-side sort.
+```yaml
+EntityList:
+  ariaLabel: {type: 'string', required: false}
+  ariaLabelledBy: {type: 'string', required: false}
+  columns: {type: 'EntityListColumn<T>[]', required: true}
+  defaultPageSize: {type: 'number', required: false}
+  getItemHref: {type: '(item: T) => string', required: false}
+  getItemKey: {type: '(item: T) => string | number', required: true}
+  getItemLabel: {type: '(item: T) => string', required: false}
+  initialSort: {type: '{ key: string; direction: SortDirection; }', required: false}
+  isLoading: {type: 'boolean', required: false}
+  items: {type: 'T[]', required: true}
+  onItemClick: {type: '(item: T, href: string) => void', required: false}
+  pageSizeOptions: {type: 'number[]', required: false}
+  renderEmpty: {type: '() => ReactNode', required: false}
+```
+Live: https://telicent-oss.github.io/telicent-ds/?path=/docs/data-display-entitylist--docs
+Usage: https://github.com/telicent-oss/telicent-ds/blob/main/src/components/data-display/EntityList/EntityList.stories.tsx
+
+Demonstrated states:
+- Interactive — items=USERS, columns=COLUMNS, ariaLabel="Users", initialSort={…}
+- DisplayOnly — items=USERS, columns=COLUMNS, ariaLabel="Users (read-only)", initialSort={…}
+- WithSPAInterception — items=USERS, columns=COLUMNS, ariaLabel="Users", initialSort={…}
+- Loading — items=[…], columns=COLUMNS, ariaLabel="Users", isLoading=true
+- Empty — items=[…], columns=COLUMNS, ariaLabel="Users"
+* **`Table` / `TableHead` / `TableBody` / `TableRow` / `TableCell`**: Semantic HTML table family — thin passthroughs to MUI's `Table` primitives; the theme carries the visuals. Use for read-only or lightly-interactive structural data: audit logs, activity streams, resource summaries, user lists inside a card. Row-click patterns via `TableRow` `onClick` + `hover`; otherwise no behaviour baked in. Props: `Table` takes `size="small" | "medium"` (default `medium`), `stickyHeader`, `padding`; `TableRow` takes `hover`, `selected`, `onClick`; `TableCell` takes `align`, `padding`, `variant`, `component` (override the rendered tag when semantics differ from visual position). Reach for `EntityList` instead when each row navigates to a detail page — the ARIA list pattern announces each row as a link, which a table can't. Reach for `DataGrid` when the data is interactive/analytical — filterable columns, cell editing, column reordering, virtualisation, server-side sort.
+Live: https://telicent-oss.github.io/telicent-ds/?path=/docs/data-display-table--docs
+Usage: https://github.com/telicent-oss/telicent-ds/blob/main/src/components/data-display/Table/Table.stories.tsx
+
+Demonstrated states:
+- Basic
+- SmallSize — size="small"
+- StickyHeader — stickyHeader=true
+- EmptyState
+- LongContent
 * **`DataGrid`**: Tabular data with pagination, sorting, and themed styling (wraps MUI X `DataGrid`). Import from the `@telicent-oss/ds/data-grid` sub-path, which carries the `@mui/x-data-grid` dependency so apps that don't use grids pay nothing for it. DS bakes `autoHeight`, `disableColumnResize`, `disableRowSelectionOnClick`, `disableColumnMenu`, `pagination`, `pageSizeOptions=[10, 25, 50]`, and initial `pageSize=10`. Row hover is suppressed by default; when `onRowClick` is set, the DS auto-opts `cursor: "pointer"` + `palette.action.hover` back in so interactive grids read as interactive with zero `sx` at the callsite. A nested `ThemeProvider` scopes the palette-driven grid overrides so Paper / MenuItem / IconButton / TablePagination styling inside the grid doesn't leak globally. DS re-exports `GridColDef`, `GridRenderCellParams`, `GridRowParams`, `GridSortModel`. `initialSort` is a DS convenience prop that maps to `initialState.sorting.sortModel`.
 ```yaml
 DataGrid:
@@ -822,7 +884,7 @@ import { UIThemeProvider } from "@telicent-oss/ds";
 
 export function Root() {
   return (
-    <UIThemeProvider theme="DataNavy" dark={false}>
+    <UIThemeProvider theme="DocumentPink" dark={false}>
       <App />
     </UIThemeProvider>
   );
@@ -1006,4 +1068,4 @@ ThemeSwitchRow:
 - Live examples (Storybook): https://telicent-oss.github.io/telicent-ds/
 - Source and issues: https://github.com/telicent-oss/telicent-ds
 
-This reference documents @telicent-oss/ds v4.4.2.
+This reference documents @telicent-oss/ds v5.0.1.

package/package.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/telicent-oss/telicent-ds.git"
   },
   "type": "module",
-  "version": "4.4.2",
+  "version": "5.0.1",
   "private": false,
   "dependencies": {
     "@emotion/react": "^11.10.6",