@opencxh/ui-kit 3.137.8 → 3.137.10

package/dist/src/content/SettingsPage.d.ts

@@ -0,0 +1,78 @@
+import { default as React, ReactNode } from 'react';
+import { ContentLoadingShape } from '../feedback/ContentLoading';
+import { PageHeaderAction } from './PageHeader';
+/**
+ * What a panel adds to the frame it is rendered in: the record it drilled into,
+ * and the way back out. The settings frame already draws the app breadcrumb and
+ * the page title, so a panel that repeats them produces the double bar this
+ * component exists to remove.
+ */
+export interface SettingsTrailEntry {
+    /** Appended to the frame breadcrumb; usually the detail record's name. */
+    title?: string;
+    /** When set, the frame renders the back affordance and calls this. */
+    onBack?: () => void;
+}
+export interface SettingsFrameApi {
+    /**
+     * `ownerId` scopes the write to one panel instance. Stable across renders,
+     * so it is safe to use as a hook dependency.
+     */
+    setTrail: (ownerId: string, entry: SettingsTrailEntry | null) => void;
+}
+/**
+ * Provided by the settings frame (the shell overlay), consumed by panels that
+ * are federated remotes. Safe across the module-federation boundary because
+ * React and `@opencxh/ui-kit` are both shared singletons — a second copy of
+ * either would hand panels a different context object and the trail would
+ * silently never arrive.
+ */
+export declare const SettingsFrameProvider: React.Provider<SettingsFrameApi | null>;
+export declare function useSettingsFrame(): SettingsFrameApi | null;
+/**
+ * State half of the frame contract, for the host to own. Returns the current
+ * trail plus the stable api to hand down through `SettingsFrameProvider`.
+ */
+export declare function useSettingsFrameHost(): {
+    trail: SettingsTrailEntry | null;
+    api: SettingsFrameApi;
+};
+declare const paddingClasses: {
+    readonly none: "";
+    readonly sm: "px-3 py-3";
+    readonly md: "px-5 py-4";
+};
+export interface SettingsPageProps {
+    children: ReactNode;
+    /**
+     * Primary actions, right-aligned in the sticky footer — the Cancel/Save pair
+     * of a form. Omit entirely on a read-only or list page and no footer renders.
+     */
+    actions?: PageHeaderAction[];
+    /** Left-aligned footer actions, set apart from the primary pair (e.g. Delete). */
+    secondaryActions?: PageHeaderAction[];
+    /** Renders the back affordance in the frame header (or inline when unframed). */
+    onBack?: () => void;
+    backLabel?: string;
+    /** The record's own name, appended to the frame breadcrumb. */
+    title?: string;
+    /** Swaps the body for a skeleton while keeping the footer in place. */
+    loading?: boolean;
+    /**
+     * What the body is about to render. A settings panel is nearly always a form
+     * or a table, and saying which keeps the placeholder from announcing a
+     * heading and two paragraphs that never arrive.
+     */
+    loadingShape?: ContentLoadingShape;
+    padding?: keyof typeof paddingClasses;
+    className?: string;
+    contentClassName?: string;
+}
+/**
+ * The body of one settings panel. Owns the three things every panel used to
+ * re-invent: the scroll container, the content padding, and where the actions
+ * live. Title, description and breadcrumb belong to the frame — pass `title`
+ * and `onBack` to extend them rather than drawing a second header here.
+ */
+export declare const SettingsPage: React.FC<SettingsPageProps>;
+export {};

package/dist/src/content/tableColumns.d.ts

@@ -0,0 +1,67 @@
+import { BadgeProps } from '../feedback/Badge';
+import { TableColumn } from './Table';
+/**
+ * Column builders for the three things table configs kept getting wrong, each
+ * in the same way across apps: a state rendered as prose, a stored code shown
+ * raw, and an id shown instead of the name it points at.
+ *
+ * They all keep the *label* in `accessor` and render only the decoration in
+ * `cell`, because `Table` searches and sorts on the accessor value. Putting the
+ * readable text there means a search for "Active" or for a team's name matches
+ * what the row actually shows — which is exactly what a raw `enabled` boolean
+ * or a bare `teamId` used to break.
+ */
+export interface BadgeColumnConfig<T, V = unknown> {
+    id: string;
+    header: string;
+    accessor: (row: T) => V;
+    /** The text in the badge — and the text this column is searched on. */
+    label: (value: V, row: T) => string;
+    /** Defaults to `default`; give states their own tone (success/error/…). */
+    tone?: (value: V, row: T) => BadgeProps["variant"];
+    /** Return false to render nothing at all for this row. */
+    visible?: (value: V, row: T) => boolean;
+    width?: string | number;
+    sortable?: boolean;
+    align?: TableColumn<T>["align"];
+}
+/** A value that is a state rather than prose — render it as a pill. */
+export declare function badgeColumn<T, V = unknown>(config: BadgeColumnConfig<T, V>): TableColumn<T>;
+export interface BooleanBadgeColumnConfig<T> {
+    id: string;
+    header: string;
+    accessor: (row: T) => boolean | undefined;
+    onLabel: string;
+    offLabel: string;
+    /** Defaults to success/secondary — on reads as healthy, off as merely quiet. */
+    onTone?: BadgeProps["variant"];
+    offTone?: BadgeProps["variant"];
+    width?: string | number;
+    sortable?: boolean;
+}
+/** The on/off case of `badgeColumn`, which is most of them. */
+export declare function booleanBadgeColumn<T>(config: BooleanBadgeColumnConfig<T>): TableColumn<T>;
+export interface LabelsColumnConfig<T> {
+    id: string;
+    header: string;
+    /** One code, a list of them, or nothing. */
+    accessor: (row: T) => string | string[] | undefined | null;
+    /**
+     * Code to readable text. Return `undefined` to fall back to the code itself,
+     * so an unknown value still shows something instead of vanishing.
+     */
+    label: (code: string) => string | undefined;
+    /** Shown when there is nothing at all. Defaults to an em dash. */
+    empty?: string;
+    separator?: string;
+    width?: string | number;
+    searchable?: boolean;
+    sortable?: boolean;
+}
+/**
+ * Stored codes rendered as the words the user picked them by. Covers both
+ * localising an enum (`interactions:created` → "Interaction created") and
+ * resolving a foreign key (a `teamId` → that team's name — pass a lookup as
+ * `label`), because from the table's side those are the same problem.
+ */
+export declare function labelsColumn<T>(config: LabelsColumnConfig<T>): TableColumn<T>;

package/dist/src/feedback/Badge.d.ts

@@ -1,5 +1,11 @@
 import { default as React } from 'react';
-export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+/**
+ * `color` is deliberately omitted from the inherited HTML attributes. It is a
+ * legacy HTML attribute, so `<Badge color="success">` used to type-check while
+ * doing nothing at all — the badge silently rendered as `default`. Omitting it
+ * turns that mistake into a compile error pointing at `variant`.
+ */
+export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'color'> {
     /**
      * The visual variant of the badge
      */

package/dist/src/feedback/ContentLoading.d.ts

@@ -1,4 +1,11 @@
 import { ReactNode } from 'react';
+/**
+ * What is about to appear here. A placeholder only does its job if it has the
+ * geometry of the thing it stands in for: the default `text` shape under a form
+ * or a list announces a heading and two paragraphs, and the real content then
+ * shoves everything sideways when it lands.
+ */
+export type ContentLoadingShape = "text" | "table" | "list" | "form" | "menu" | "cards";
 export interface ContentLoadingProps {
     /**
      * `page` (default) fills the route with its own `<main>` shell and padding.
@@ -6,21 +13,22 @@ export interface ContentLoadingProps {
      * card or scroll container without nesting a second `<main>` landmark.
      */
     variant?: "page" | "inline";
+    /** The shape of what is coming. Defaults to `text`. */
+    shape?: ContentLoadingShape;
+    /** Rows/items/fields/cards to draw, depending on `shape`. */
+    rows?: number;
+    /** Columns, for `table` and `cards`. */
+    columns?: number;
     /**
      * Optional custom skeleton content (overrides default)
      */
     children?: ReactNode;
-    /**
-     * If true, renders a table-style skeleton
-     */
+    className?: string;
+    /** @deprecated Pass `shape="table"`. */
     showTableSkeleton?: boolean;
-    /**
-     * Number of table columns (default: 6)
-     */
+    /** @deprecated Pass `columns`. */
     tableColumns?: number;
-    /**
-     * Number of table rows (default: 8)
-     */
+    /** @deprecated Pass `rows`. */
     tableRows?: number;
 }
-export declare function ContentLoading({ variant, children, showTableSkeleton, tableColumns, tableRows, }: ContentLoadingProps): import("react").JSX.Element;
+export declare function ContentLoading({ variant, shape, rows, columns, children, className, showTableSkeleton, tableColumns, tableRows, }: ContentLoadingProps): import("react").JSX.Element;

package/dist/src/forms/Form.d.ts

@@ -59,6 +59,12 @@ export interface FormGroupItem<T = any> {
     width?: string | number;
     /** Placeholder text */
     placeholder?: string;
+    /**
+     * Visible rows for `textarea`. Defaults to 4, which is right for a note and
+     * far too small for a field that holds an instruction someone actually reads
+     * back while editing (a system prompt).
+     */
+    rows?: number;
     /** Autocomplete attribute */
     autocomplete?: string;
     /** Options for select/radio/checkbox types */

package/dist/src/index.d.ts

@@ -25,7 +25,7 @@ export { ConfirmDialog, type ConfirmDialogProps } from './overlays/ConfirmDialog
 export { Modal, type ModalProps } from './overlays/Modal';
 export { Popover, type PopoverProps } from './overlays/Popover';
 export { Badge, type BadgeProps } from './feedback/Badge';
-export { ContentLoading } from './feedback/ContentLoading';
+export { ContentLoading, type ContentLoadingProps, type ContentLoadingShape } from './feedback/ContentLoading';
 export { EmptyState, type EmptyStateProps } from './feedback/EmptyState';
 export { Kbd, type KbdProps } from './feedback/Kbd';
 export { ProgressBar, type ProgressBarProps } from './feedback/ProgressBar';
@@ -46,9 +46,11 @@ export { PageToolbar, PageToolbarActions, type PageToolbarActionsProps, type Pag
 export { RichText, type RichTextProps } from './content/RichText';
 export { SectionCaption, type SectionCaptionProps } from './content/SectionCaption';
 export { SectionDivider, type SectionDividerProps } from './content/SectionDivider';
+export { SettingsFrameProvider, SettingsPage, useSettingsFrame, useSettingsFrameHost, type SettingsFrameApi, type SettingsPageProps, type SettingsTrailEntry } from './content/SettingsPage';
 export { SettingsRow, SettingsSection, type SettingsRowProps, type SettingsSectionProps } from './content/SettingsRow';
 export { SourceChip, type SourceChipProps } from './content/SourceChip';
 export { Table, dateFilterHandler, selectFilterHandler, type TableAction, type TableColumn, type TableFilter, type TableProps } from './content/Table';
+export { badgeColumn, booleanBadgeColumn, labelsColumn, type BadgeColumnConfig, type BooleanBadgeColumnConfig, type LabelsColumnConfig } from './content/tableColumns';
 export { View, type ViewGroup, type ViewProps } from './content/View';
 export { SidebarMenu, type MenuItem, type MenuItemAction } from './navigation/Sidebar';
 export { TabBar, Tabs, type TabItem, type TabsProps } from './navigation/Tabs';

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@opencxh/ui-kit",
-  "version": "3.137.8",
+  "version": "3.137.10",
   "description": "Theme-aware UI component library for OpenCXH platform",
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"