@persona/design-system 0.10.9 → 0.10.11

package/dist/{useTableColumns-DJFy0Gp8.d.mts → useTableColumns-BEKJNrb1.d.mts}

@@ -1,4 +1,4 @@
-import { C as RowAction, O as SortProps, _ as DataTableColumns, l as DataTableColumnFormat } from "./types-BeFBvQ1c.mjs";
+import { C as RowAction, O as SortProps, _ as DataTableColumns, l as DataTableColumnFormat } from "./types-D5txFacG.mjs";
 import { ColumnDef, Row, RowData, Table } from "@tanstack/react-table";
 
 //#region src/components/DataTable/useTableColumns.d.ts
@@ -69,4 +69,4 @@ declare function useTableColumns<TData extends RowData, TFormat extends {
 }[]];
 //#endregion
 export { UseTableColumnsParams as n, useTableColumns as r, RenderFormatFn as t };
-//# sourceMappingURL=useTableColumns-DJFy0Gp8.d.mts.map
+//# sourceMappingURL=useTableColumns-BEKJNrb1.d.mts.map

package/dist/useTableColumns.d.mts

@@ -1,2 +1,2 @@
-import { n as UseTableColumnsParams, r as useTableColumns, t as RenderFormatFn } from "./useTableColumns-DJFy0Gp8.mjs";
+import { n as UseTableColumnsParams, r as useTableColumns, t as RenderFormatFn } from "./useTableColumns-BEKJNrb1.mjs";
 export { RenderFormatFn, UseTableColumnsParams, useTableColumns };

package/dist/useTruncation.d.mts

@@ -1,4 +1,4 @@
-import { i as ComboboxOption } from "./ComboboxBase-Mb8HyeAI.mjs";
+import { i as ComboboxOption } from "./ComboboxBase-Brgv5nxk.mjs";
 import { MutableRefObject, RefObject } from "react";
 
 //#region src/components/Combobox/useTruncation.d.ts

package/dist/useValueControlError.d.mts

@@ -0,0 +1,26 @@
+import { ReactNode } from "react";
+
+//#region src/components/DataTable/TableControls/FiltersV2/value-controls/useValueControlError.d.ts
+interface ValueControlErrorInputProps {
+  hasError?: boolean;
+  'aria-describedby'?: string;
+  'aria-errormessage'?: string;
+}
+/**
+ * Error state for a text-like value control (`Input`). Returns the props that
+ * put the input in its error state (red border, `aria-invalid`, linked to the
+ * message) and the message element to render after the input, styled like
+ * `FormField`'s `errorText`.
+ *
+ * With no `errorMessage` both are empty, so the control renders exactly as it
+ * did without validation. The message is a sibling rather than a wrapper, so
+ * the input keeps its place in the tree (and its focus) when the message
+ * appears or clears while the user types.
+ */
+declare function useValueControlError(errorMessage: string | undefined): {
+  inputProps: ValueControlErrorInputProps;
+  errorText: ReactNode;
+};
+//#endregion
+export { useValueControlError };
+//# sourceMappingURL=useValueControlError.d.mts.map

package/dist/utils.d.mts

@@ -1,4 +1,4 @@
-import { d as FilterRuleValue } from "./types-DLnCkvTt.mjs";
+import { d as FilterRuleValue } from "./types-BJqmRXFV.mjs";
 
 //#region src/components/DataTable/TableControls/FiltersV2/value-controls/utils.d.ts
 /**

package/dist/{validation-Tgg3AhuP.d.mts → validation-BDQdQ1cY.d.mts}

@@ -1,5 +1,5 @@
-import { m as FilterStateV2, u as FilterRule } from "./types-DLnCkvTt.mjs";
-import { t as FieldRegistry } from "./FieldRegistry-C2NVPhMO.mjs";
+import { m as FilterStateV2, u as FilterRule } from "./types-BJqmRXFV.mjs";
+import { t as FieldRegistry } from "./FieldRegistry-CJwGpUVK.mjs";
 
 //#region src/components/DataTable/TableControls/FiltersV2/validation.d.ts
 /**
@@ -48,4 +48,4 @@ declare function pruneToRegistry(state: FilterStateV2, registry: FieldRegistry |
 declare function hasCompleteValue(rule: FilterRule, registry: FieldRegistry): boolean;
 //#endregion
 export { isFilterStateV2 as n, pruneToRegistry as r, hasCompleteValue as t };
-//# sourceMappingURL=validation-Tgg3AhuP.d.mts.map
+//# sourceMappingURL=validation-BDQdQ1cY.d.mts.map

package/dist/validation.d.mts

@@ -1,2 +1,2 @@
-import { n as isFilterStateV2, r as pruneToRegistry, t as hasCompleteValue } from "./validation-Tgg3AhuP.mjs";
+import { n as isFilterStateV2, r as pruneToRegistry, t as hasCompleteValue } from "./validation-BDQdQ1cY.mjs";
 export { hasCompleteValue, isFilterStateV2, pruneToRegistry };

package/dist/{value-control-resolver-XQbGCdsP.d.mts → value-control-resolver-BFJZEWDn.d.mts}

@@ -1,4 +1,4 @@
-import { d as FilterRuleValue, f as FilterRuleValueChange, l as FilterOperator, o as FilterField, u as FilterRule } from "./types-DLnCkvTt.mjs";
+import { d as FilterRuleValue, f as FilterRuleValueChange, l as FilterOperator, o as FilterField, u as FilterRule } from "./types-BJqmRXFV.mjs";
 import { ReactNode } from "react";
 
 //#region src/components/DataTable/TableControls/FiltersV2/FilterBar/value-control-resolver.d.ts
@@ -41,9 +41,15 @@ interface ResolveValueControlOptions {
    * with chips over a vertically expansive list.
    */
   layout?: 'popover' | 'inline';
+  /**
+   * Validation error for the current value. When omitted,
+   * `resolveValueControl` fills it from the condition operator's `validate`
+   * (see `FilterConditionOperator`), so a host resolver receives it too.
+   */
+  errorMessage?: string;
 }
 type ValueControlResolver = (opts: ResolveValueControlOptions) => ReactNode | undefined;
-declare function resolveValueControl(opts: ResolveValueControlOptions, hostResolver?: ValueControlResolver): ReactNode;
+declare function resolveValueControl(options: ResolveValueControlOptions, hostResolver?: ValueControlResolver): ReactNode;
 //#endregion
 export { ValueControlResolver as n, resolveValueControl as r, ResolveValueControlOptions as t };
-//# sourceMappingURL=value-control-resolver-XQbGCdsP.d.mts.map
+//# sourceMappingURL=value-control-resolver-BFJZEWDn.d.mts.map

package/dist/value-control-resolver.d.mts

@@ -1,2 +1,2 @@
-import { n as ValueControlResolver, r as resolveValueControl, t as ResolveValueControlOptions } from "./value-control-resolver-XQbGCdsP.mjs";
+import { n as ValueControlResolver, r as resolveValueControl, t as ResolveValueControlOptions } from "./value-control-resolver-BFJZEWDn.mjs";
 export { ResolveValueControlOptions, ValueControlResolver, resolveValueControl };

package/dist/variables/charting.mjs

@@ -100,7 +100,7 @@ const chartingDark = {
 		Color.CoreBlue600,
 		Color.CoreOrange700,
 		Color.CoreTeal900,
-		Color.CoreYellow900,
+		Color.CoreYellow800,
 		Color.CoreBlue700,
 		Color.CoreSlate600,
 		Color.CoreTeal800

package/dist/variables/charting.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"charting.mjs","names":[],"sources":["../../src/variables/charting.ts"],"sourcesContent":["// Generated by design-system/scripts/generate-charting-tokens.mjs from\n//   design-system/tokens/charting/light.json\n//   design-system/tokens/charting/dark.json\n// Do not edit by hand — edit the token source and regenerate.\n// This module is where charting palettes map onto core primitives, per colour mode.\n/* oxlint-disable persona-web/no-core-color-tokens */\nimport { Color } from '@persona/design-tokens';\n\n/** Charting palettes: ordered colour lists, named as `ChartingColors` names them. */\nexport interface ChartingTokens {\n  Sequential: readonly Color[];\n  Categorical: readonly Color[];\n  Qualitative: readonly Color[];\n  SequentialMono: readonly Color[];\n  SequentialDivergent: readonly Color[];\n}\n\nexport const chartingLight: ChartingTokens = {\n  Sequential: [\n    Color.CorePurple400,\n    Color.CorePurple300,\n    Color.CorePurple200,\n    Color.CoreTeal400,\n    Color.CoreTeal200,\n    Color.CoreTeal100,\n    Color.CoreSlate400,\n    Color.CoreSlate300,\n  ],\n  Categorical: [\n    Color.CorePurple500,\n    Color.CorePurple700,\n    Color.CoreTeal400,\n    Color.CoreTeal800,\n    Color.CoreGreen400,\n    Color.CoreGreen800,\n    Color.CoreOrange400,\n    Color.CoreOrange700,\n    Color.CoreYellow400,\n    Color.CoreYellow800,\n    Color.CoreRed400,\n    Color.CoreRed600,\n    Color.CoreBlue400,\n    Color.CoreBlue700,\n  ],\n  Qualitative: [\n    Color.CoreBlue500,\n    Color.CoreYellow1000,\n    Color.CoreOrange800,\n    Color.CoreGreen900,\n    Color.CoreGreen700,\n    Color.CoreBlue800,\n    Color.CoreOrange700,\n    Color.CoreTeal900,\n    Color.CoreYellow900,\n    Color.CoreBlue700,\n    Color.CoreSlate600,\n    Color.CoreTeal800,\n  ],\n  SequentialMono: [\n    Color.CoreBlue900,\n    Color.CoreBlue800,\n    Color.CoreBlue700,\n    Color.CoreBlue600,\n    Color.CoreBlue500,\n    Color.CoreBlue400,\n    Color.CoreBlue300,\n    Color.CoreBlue200,\n  ],\n  SequentialDivergent: [\n    Color.CoreBlue900,\n    Color.CoreBlue800,\n    Color.CoreBlue600,\n    Color.CoreBlue400,\n    Color.CoreBlue200,\n    Color.CoreOrange200,\n    Color.CoreOrange400,\n    Color.CoreOrange600,\n    Color.CoreOrange800,\n    Color.CoreOrange900,\n  ],\n};\n\nexport const chartingDark: ChartingTokens = {\n  Sequential: [\n    Color.CorePurple400,\n    Color.CorePurple300,\n    Color.CorePurple200,\n    Color.CoreTeal400,\n    Color.CoreTeal200,\n    Color.CoreTeal100,\n    Color.CoreSlate400,\n    Color.CoreSlate300,\n  ],\n  Categorical: [\n    Color.CorePurple500,\n    Color.CorePurple700,\n    Color.CoreTeal400,\n    Color.CoreTeal800,\n    Color.CoreGreen400,\n    Color.CoreGreen800,\n    Color.CoreOrange400,\n    Color.CoreOrange700,\n    Color.CoreYellow400,\n    Color.CoreYellow800,\n    Color.CoreRed400,\n    Color.CoreRed600,\n    Color.CoreBlue400,\n    Color.CoreBlue700,\n  ],\n  Qualitative: [\n    Color.CoreBlue500,\n    Color.CoreYellow900,\n    Color.CoreOrange800,\n    Color.CoreGreen800,\n    Color.CoreGreen700,\n    Color.CoreBlue600,\n    Color.CoreOrange700,\n    Color.CoreTeal900,\n    Color.CoreYellow900,\n    Color.CoreBlue700,\n    Color.CoreSlate600,\n    Color.CoreTeal800,\n  ],\n  SequentialMono: [\n    Color.CoreBlue900,\n    Color.CoreBlue800,\n    Color.CoreBlue700,\n    Color.CoreBlue600,\n    Color.CoreBlue500,\n    Color.CoreBlue400,\n    Color.CoreBlue300,\n    Color.CoreBlue200,\n  ],\n  SequentialDivergent: [\n    Color.CoreBlue900,\n    Color.CoreBlue800,\n    Color.CoreBlue600,\n    Color.CoreBlue400,\n    Color.CoreBlue200,\n    Color.CoreOrange200,\n    Color.CoreOrange400,\n    Color.CoreOrange600,\n    Color.CoreOrange800,\n    Color.CoreOrange900,\n  ],\n};\n"],"mappings":";;AAiBA,MAAa,gBAAgC;CAC3C,YAAY;EACV,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,aAAa;EACX,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,aAAa;EACX,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,gBAAgB;EACd,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,qBAAqB;EACnB,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACF;AAED,MAAa,eAA+B;CAC1C,YAAY;EACV,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,aAAa;EACX,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,aAAa;EACX,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,gBAAgB;EACd,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,qBAAqB;EACnB,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACF"}
+{"version":3,"file":"charting.mjs","names":[],"sources":["../../src/variables/charting.ts"],"sourcesContent":["// Generated by design-system/scripts/generate-charting-tokens.mjs from\n//   design-system/tokens/charting/light.json\n//   design-system/tokens/charting/dark.json\n// Do not edit by hand — edit the token source and regenerate.\n// This module is where charting palettes map onto core primitives, per colour mode.\n/* oxlint-disable persona-web/no-core-color-tokens */\nimport { Color } from '@persona/design-tokens';\n\n/** Charting palettes: ordered colour lists, named as `ChartingColors` names them. */\nexport interface ChartingTokens {\n  Sequential: readonly Color[];\n  Categorical: readonly Color[];\n  Qualitative: readonly Color[];\n  SequentialMono: readonly Color[];\n  SequentialDivergent: readonly Color[];\n}\n\nexport const chartingLight: ChartingTokens = {\n  Sequential: [\n    Color.CorePurple400,\n    Color.CorePurple300,\n    Color.CorePurple200,\n    Color.CoreTeal400,\n    Color.CoreTeal200,\n    Color.CoreTeal100,\n    Color.CoreSlate400,\n    Color.CoreSlate300,\n  ],\n  Categorical: [\n    Color.CorePurple500,\n    Color.CorePurple700,\n    Color.CoreTeal400,\n    Color.CoreTeal800,\n    Color.CoreGreen400,\n    Color.CoreGreen800,\n    Color.CoreOrange400,\n    Color.CoreOrange700,\n    Color.CoreYellow400,\n    Color.CoreYellow800,\n    Color.CoreRed400,\n    Color.CoreRed600,\n    Color.CoreBlue400,\n    Color.CoreBlue700,\n  ],\n  Qualitative: [\n    Color.CoreBlue500,\n    Color.CoreYellow1000,\n    Color.CoreOrange800,\n    Color.CoreGreen900,\n    Color.CoreGreen700,\n    Color.CoreBlue800,\n    Color.CoreOrange700,\n    Color.CoreTeal900,\n    Color.CoreYellow900,\n    Color.CoreBlue700,\n    Color.CoreSlate600,\n    Color.CoreTeal800,\n  ],\n  SequentialMono: [\n    Color.CoreBlue900,\n    Color.CoreBlue800,\n    Color.CoreBlue700,\n    Color.CoreBlue600,\n    Color.CoreBlue500,\n    Color.CoreBlue400,\n    Color.CoreBlue300,\n    Color.CoreBlue200,\n  ],\n  SequentialDivergent: [\n    Color.CoreBlue900,\n    Color.CoreBlue800,\n    Color.CoreBlue600,\n    Color.CoreBlue400,\n    Color.CoreBlue200,\n    Color.CoreOrange200,\n    Color.CoreOrange400,\n    Color.CoreOrange600,\n    Color.CoreOrange800,\n    Color.CoreOrange900,\n  ],\n};\n\nexport const chartingDark: ChartingTokens = {\n  Sequential: [\n    Color.CorePurple400,\n    Color.CorePurple300,\n    Color.CorePurple200,\n    Color.CoreTeal400,\n    Color.CoreTeal200,\n    Color.CoreTeal100,\n    Color.CoreSlate400,\n    Color.CoreSlate300,\n  ],\n  Categorical: [\n    Color.CorePurple500,\n    Color.CorePurple700,\n    Color.CoreTeal400,\n    Color.CoreTeal800,\n    Color.CoreGreen400,\n    Color.CoreGreen800,\n    Color.CoreOrange400,\n    Color.CoreOrange700,\n    Color.CoreYellow400,\n    Color.CoreYellow800,\n    Color.CoreRed400,\n    Color.CoreRed600,\n    Color.CoreBlue400,\n    Color.CoreBlue700,\n  ],\n  Qualitative: [\n    Color.CoreBlue500,\n    Color.CoreYellow900,\n    Color.CoreOrange800,\n    Color.CoreGreen800,\n    Color.CoreGreen700,\n    Color.CoreBlue600,\n    Color.CoreOrange700,\n    Color.CoreTeal900,\n    Color.CoreYellow800,\n    Color.CoreBlue700,\n    Color.CoreSlate600,\n    Color.CoreTeal800,\n  ],\n  SequentialMono: [\n    Color.CoreBlue900,\n    Color.CoreBlue800,\n    Color.CoreBlue700,\n    Color.CoreBlue600,\n    Color.CoreBlue500,\n    Color.CoreBlue400,\n    Color.CoreBlue300,\n    Color.CoreBlue200,\n  ],\n  SequentialDivergent: [\n    Color.CoreBlue900,\n    Color.CoreBlue800,\n    Color.CoreBlue600,\n    Color.CoreBlue400,\n    Color.CoreBlue200,\n    Color.CoreOrange200,\n    Color.CoreOrange400,\n    Color.CoreOrange600,\n    Color.CoreOrange800,\n    Color.CoreOrange900,\n  ],\n};\n"],"mappings":";;AAiBA,MAAa,gBAAgC;CAC3C,YAAY;EACV,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,aAAa;EACX,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,aAAa;EACX,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,gBAAgB;EACd,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,qBAAqB;EACnB,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACF;AAED,MAAa,eAA+B;CAC1C,YAAY;EACV,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,aAAa;EACX,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,aAAa;EACX,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,gBAAgB;EACd,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACD,qBAAqB;EACnB,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACP;CACF"}

package/dist/variables/keyframes.d.mts

@@ -3,6 +3,7 @@ import * as _$styled_components0 from "styled-components";
 //#region src/variables/keyframes.d.ts
 declare const rotate: _$styled_components0.Keyframes;
 declare const fadeIn: _$styled_components0.Keyframes;
+declare const fadeOut: _$styled_components0.Keyframes;
 //#endregion
-export { fadeIn, rotate };
+export { fadeIn, fadeOut, rotate };
 //# sourceMappingURL=keyframes.d.mts.map

package/dist/variables/keyframes.mjs

@@ -13,7 +13,15 @@ const fadeIn = keyframes`
     opacity: 1;
   }
 `;
+const fadeOut = keyframes`
+  0% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0;
+  }
+`;
 //#endregion
-export { fadeIn, rotate };
+export { fadeIn, fadeOut, rotate };
 
 //# sourceMappingURL=keyframes.mjs.map

package/dist/variables/keyframes.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"keyframes.mjs","names":[],"sources":["../../src/variables/keyframes.ts"],"sourcesContent":["import { keyframes } from 'styled-components';\n\nexport const rotate = keyframes`\n  100% {\n    transform: rotate(360deg);\n  }\n`;\n\nexport const fadeIn = keyframes`\n  0% {\n    opacity: 0;\n  }\n  100% {\n    opacity: 1;\n  }\n`;\n"],"mappings":";;AAEA,MAAa,SAAS,SAAS;;;;;AAM/B,MAAa,SAAS,SAAS"}
+{"version":3,"file":"keyframes.mjs","names":[],"sources":["../../src/variables/keyframes.ts"],"sourcesContent":["import { keyframes } from 'styled-components';\n\nexport const rotate = keyframes`\n  100% {\n    transform: rotate(360deg);\n  }\n`;\n\nexport const fadeIn = keyframes`\n  0% {\n    opacity: 0;\n  }\n  100% {\n    opacity: 1;\n  }\n`;\n\nexport const fadeOut = keyframes`\n  0% {\n    opacity: 1;\n  }\n  100% {\n    opacity: 0;\n  }\n`;\n"],"mappings":";;AAEA,MAAa,SAAS,SAAS;;;;;AAM/B,MAAa,SAAS,SAAS;;;;;;;;AAS/B,MAAa,UAAU,SAAS"}

package/dist/variables/transitions.d.mts

@@ -1,11 +1,18 @@
 //#region src/variables/transitions.d.ts
+/**
+ * Durations for CSS. Which step a motion takes depends on its use, not on the nearest number: see the
+ * motion scale in `skills/ui-authoring/STANDARD.md`. Closes run one step faster than opens, nothing
+ * over `Medium` is a state change, and `OneSecond` is for loop periods only.
+ */
 declare enum TransitionDuration {
   ExtraFast = "100ms",
   Faster = "150ms",
   Fast = "200ms",
+  MediumFast = "300ms",
   Medium = "400ms",
   OneSecond = "1000ms"
 }
+/** The same steps in seconds, for framer-motion. */
 declare enum TransitionDurationInSeconds {
   ExtraFast = 0.1,
   Faster = 0.15,
@@ -14,6 +21,29 @@ declare enum TransitionDurationInSeconds {
   Medium = 0.4,
   OneSecond = 1
 }
+/**
+ * Timing functions for CSS. `Enter` decelerates something arriving, `Exit` accelerates something
+ * leaving, and `Move` is for anything already on screen changing (colour, size, position) and for
+ * the reduced-motion fade. `Linear` is for loops only.
+ */
+declare enum TransitionEasing {
+  Enter = "cubic-bezier(0, 0, 0.2, 1)",
+  Exit = "cubic-bezier(0.4, 0, 1, 1)",
+  Move = "cubic-bezier(0.4, 0, 0.2, 1)",
+  Linear = "linear"
+}
+type CubicBezier = [number, number, number, number];
+/** `TransitionEasing`'s curves as control points, for framer-motion's `ease`. */
+declare const TransitionEasingCurve: Readonly<Record<'Enter' | 'Exit' | 'Move', CubicBezier>>;
+/**
+ * Under `prefers-reduced-motion: reduce`, an enter or exit keeps a short opacity fade on the same
+ * cue, with no translate, scale or size change. It is never instant.
+ */
+declare const ReducedMotionFade: {
+  readonly duration: TransitionDuration.Faster;
+  readonly durationInSeconds: TransitionDurationInSeconds.Faster;
+  readonly easing: TransitionEasing.Move;
+};
 //#endregion
-export { TransitionDuration, TransitionDurationInSeconds };
+export { ReducedMotionFade, TransitionDuration, TransitionDurationInSeconds, TransitionEasing, TransitionEasingCurve };
 //# sourceMappingURL=transitions.d.mts.map

package/dist/variables/transitions.mjs

@@ -1,12 +1,19 @@
 //#region src/variables/transitions.ts
+/**
+* Durations for CSS. Which step a motion takes depends on its use, not on the nearest number: see the
+* motion scale in `skills/ui-authoring/STANDARD.md`. Closes run one step faster than opens, nothing
+* over `Medium` is a state change, and `OneSecond` is for loop periods only.
+*/
 let TransitionDuration = /* @__PURE__ */ function(TransitionDuration) {
 	TransitionDuration["ExtraFast"] = "100ms";
 	TransitionDuration["Faster"] = "150ms";
 	TransitionDuration["Fast"] = "200ms";
+	TransitionDuration["MediumFast"] = "300ms";
 	TransitionDuration["Medium"] = "400ms";
 	TransitionDuration["OneSecond"] = "1000ms";
 	return TransitionDuration;
 }({});
+/** The same steps in seconds, for framer-motion. */
 let TransitionDurationInSeconds = /* @__PURE__ */ function(TransitionDurationInSeconds) {
 	TransitionDurationInSeconds[TransitionDurationInSeconds["ExtraFast"] = .1] = "ExtraFast";
 	TransitionDurationInSeconds[TransitionDurationInSeconds["Faster"] = .15] = "Faster";
@@ -16,7 +23,49 @@ let TransitionDurationInSeconds = /* @__PURE__ */ function(TransitionDurationInS
 	TransitionDurationInSeconds[TransitionDurationInSeconds["OneSecond"] = 1] = "OneSecond";
 	return TransitionDurationInSeconds;
 }({});
+/**
+* Timing functions for CSS. `Enter` decelerates something arriving, `Exit` accelerates something
+* leaving, and `Move` is for anything already on screen changing (colour, size, position) and for
+* the reduced-motion fade. `Linear` is for loops only.
+*/
+let TransitionEasing = /* @__PURE__ */ function(TransitionEasing) {
+	TransitionEasing["Enter"] = "cubic-bezier(0, 0, 0.2, 1)";
+	TransitionEasing["Exit"] = "cubic-bezier(0.4, 0, 1, 1)";
+	TransitionEasing["Move"] = "cubic-bezier(0.4, 0, 0.2, 1)";
+	TransitionEasing["Linear"] = "linear";
+	return TransitionEasing;
+}({});
+/** `TransitionEasing`'s curves as control points, for framer-motion's `ease`. */
+const TransitionEasingCurve = {
+	Enter: [
+		0,
+		0,
+		.2,
+		1
+	],
+	Exit: [
+		.4,
+		0,
+		1,
+		1
+	],
+	Move: [
+		.4,
+		0,
+		.2,
+		1
+	]
+};
+/**
+* Under `prefers-reduced-motion: reduce`, an enter or exit keeps a short opacity fade on the same
+* cue, with no translate, scale or size change. It is never instant.
+*/
+const ReducedMotionFade = {
+	duration: "150ms",
+	durationInSeconds: .15,
+	easing: "cubic-bezier(0.4, 0, 0.2, 1)"
+};
 //#endregion
-export { TransitionDuration, TransitionDurationInSeconds };
+export { ReducedMotionFade, TransitionDuration, TransitionDurationInSeconds, TransitionEasing, TransitionEasingCurve };
 
 //# sourceMappingURL=transitions.mjs.map

package/dist/variables/transitions.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"transitions.mjs","names":[],"sources":["../../src/variables/transitions.ts"],"sourcesContent":["export enum TransitionDuration {\n  ExtraFast = '100ms',\n  Faster = '150ms',\n  Fast = '200ms',\n  Medium = '400ms',\n\n  OneSecond = '1000ms',\n}\n\nexport enum TransitionDurationInSeconds {\n  ExtraFast = 0.1,\n  Faster = 0.15,\n  Fast = 0.2,\n  MediumFast = 0.3,\n  Medium = 0.4,\n\n  OneSecond = 1,\n}\n"],"mappings":";AAAA,IAAY,qBAAL,yBAAA,oBAAA;AACL,oBAAA,eAAA;AACA,oBAAA,YAAA;AACA,oBAAA,UAAA;AACA,oBAAA,YAAA;AAEA,oBAAA,eAAA;;KACD;AAED,IAAY,8BAAL,yBAAA,6BAAA;AACL,6BAAA,4BAAA,eAAA,MAAA;AACA,6BAAA,4BAAA,YAAA,OAAA;AACA,6BAAA,4BAAA,UAAA,MAAA;AACA,6BAAA,4BAAA,gBAAA,MAAA;AACA,6BAAA,4BAAA,YAAA,MAAA;AAEA,6BAAA,4BAAA,eAAA,KAAA;;KACD"}
+{"version":3,"file":"transitions.mjs","names":[],"sources":["../../src/variables/transitions.ts"],"sourcesContent":["/**\n * Durations for CSS. Which step a motion takes depends on its use, not on the nearest number: see the\n * motion scale in `skills/ui-authoring/STANDARD.md`. Closes run one step faster than opens, nothing\n * over `Medium` is a state change, and `OneSecond` is for loop periods only.\n */\nexport enum TransitionDuration {\n  ExtraFast = '100ms',\n  Faster = '150ms',\n  Fast = '200ms',\n  MediumFast = '300ms',\n  Medium = '400ms',\n\n  OneSecond = '1000ms',\n}\n\n/** The same steps in seconds, for framer-motion. */\nexport enum TransitionDurationInSeconds {\n  ExtraFast = 0.1,\n  Faster = 0.15,\n  Fast = 0.2,\n  MediumFast = 0.3,\n  Medium = 0.4,\n\n  OneSecond = 1,\n}\n\n/**\n * Timing functions for CSS. `Enter` decelerates something arriving, `Exit` accelerates something\n * leaving, and `Move` is for anything already on screen changing (colour, size, position) and for\n * the reduced-motion fade. `Linear` is for loops only.\n */\nexport enum TransitionEasing {\n  Enter = 'cubic-bezier(0, 0, 0.2, 1)',\n  Exit = 'cubic-bezier(0.4, 0, 1, 1)',\n  Move = 'cubic-bezier(0.4, 0, 0.2, 1)',\n  Linear = 'linear',\n}\n\ntype CubicBezier = [number, number, number, number];\n\n/** `TransitionEasing`'s curves as control points, for framer-motion's `ease`. */\nexport const TransitionEasingCurve: Readonly<Record<'Enter' | 'Exit' | 'Move', CubicBezier>> = {\n  Enter: [0, 0, 0.2, 1],\n  Exit: [0.4, 0, 1, 1],\n  Move: [0.4, 0, 0.2, 1],\n};\n\n/**\n * Under `prefers-reduced-motion: reduce`, an enter or exit keeps a short opacity fade on the same\n * cue, with no translate, scale or size change. It is never instant.\n */\nexport const ReducedMotionFade = {\n  duration: TransitionDuration.Faster,\n  durationInSeconds: TransitionDurationInSeconds.Faster,\n  easing: TransitionEasing.Move,\n} as const;\n"],"mappings":";;;;;;AAKA,IAAY,qBAAL,yBAAA,oBAAA;AACL,oBAAA,eAAA;AACA,oBAAA,YAAA;AACA,oBAAA,UAAA;AACA,oBAAA,gBAAA;AACA,oBAAA,YAAA;AAEA,oBAAA,eAAA;;KACD;;AAGD,IAAY,8BAAL,yBAAA,6BAAA;AACL,6BAAA,4BAAA,eAAA,MAAA;AACA,6BAAA,4BAAA,YAAA,OAAA;AACA,6BAAA,4BAAA,UAAA,MAAA;AACA,6BAAA,4BAAA,gBAAA,MAAA;AACA,6BAAA,4BAAA,YAAA,MAAA;AAEA,6BAAA,4BAAA,eAAA,KAAA;;KACD;;;;;;AAOD,IAAY,mBAAL,yBAAA,kBAAA;AACL,kBAAA,WAAA;AACA,kBAAA,UAAA;AACA,kBAAA,UAAA;AACA,kBAAA,YAAA;;KACD;;AAKD,MAAa,wBAAkF;CAC7F,OAAO;EAAC;EAAG;EAAG;EAAK;EAAE;CACrB,MAAM;EAAC;EAAK;EAAG;EAAG;EAAE;CACpB,MAAM;EAAC;EAAK;EAAG;EAAK;EAAE;CACvB;;;;;AAMD,MAAa,oBAAoB;CAC/B,UAAA;CACA,mBAAA;CACA,QAAA;CACD"}

package/llms.txt

@@ -16,7 +16,7 @@ For exact prop types, prefer the published type declarations (`dist/**/*.d.mts`,
 - [ui-authoring](skills/ui-authoring/SKILL.md): design tokens, PDS implementation guidelines, table guidelines (DataTable vs TableBox vs TableLayout), routing/link adapters (react-router, TanStack, custom), localization (PDSProvider strings/locale), loading states, testing, Storybook
 - [Product UI standard](skills/ui-authoring/STANDARD.md): the rules every screen meets (11 px minimum for copy and 8 px for labels inside charts and diagrams, WCAG AA contrast, reduced motion, status not by colour alone), the screen brief, the `pds/*` oxlint rules that check it (`@persona/design-system/lint`), and the `new-screen` skill for building one screen
 - [Tokens](skills/ui-authoring/TOKENS.md): semantic color tokens (Fg / Surface / Border / Action / Input / Feedback / Status / Opacity) with recipes and a dark-mode checklist; Spacing / Typography catalog, radius, elevation, charts
-- [Patterns](skills/ui-authoring/PATTERNS.md): forms, layout, index tables, indicators, feedback, empty states, charts, panels
+- [Patterns](skills/ui-authoring/PATTERNS.md): forms, layout, index tables, versioned resource headers, indicators, feedback, empty states, charts, panels
 - [Components](skills/ui-authoring/COMPONENTS.md): which PDS component to use (and its import path); APIs live in that component's `.mdx` when one exists, otherwise in `dist/components/<Name>/index.d.mts`
 - [design-system-component-authoring](skills/design-system-component-authoring/SKILL.md): authoring a new PDS component in this repo — clarifying scope, component conventions, prop interface patterns
 
@@ -39,7 +39,8 @@ their own subpaths.
 - Overlays: `Modal`, `WizardModal` (`patterns/WizardModal`), `RightPanel`, `Popover`, `Tooltip` / `TextUnderlineTooltip`, `DropdownMenu`, `FloatingPanel`
 - Modal close button: localize the default with `PDSProvider strings={{ closeModal: translatedLabel }}` (English: "Close"), or override one modal with `contentProps.closeButtonLabel`.
 - Forms: `ConfigFormGroup`, `FormField` (`TextField`, `TextAreaField`, `TableBoxField`), `Input`, `TextArea`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Toggle`, `DatePicker`, `RichTextEditor` (tiptap-based Markdown/HTML editor with menu bar and optional floating toolbar), `FloatingToolbar` (tiptap bubble-menu toolbar)
-- Status: `Sticker` (status badges), `Badge` (counts), `StatusIndicator`
+- Combobox server search: `filterMode='server'` requires controlled `query` / `onQueryChange`, `selectedOptions` for selected labels, and flat `options`. Only native edits change the query; selection/display events never report it. PDS skips Fuse and hides Select all. Consumers own requests/pages; wire `onScrollEnd={loadMore}` for repeatable near-end reports and `isLoadingMore` for a loading row. Callers dedupe loading/exhausted requests; PDS re-checks short lists only on open/count changes and has no request lock. Use generic `footerAction` for error retry. Nested/grouped options and `onInputChange` remain client-mode features. See skills/ui-authoring/COMPONENTS.md.
+- Status: `StatusIndicator` (named lifecycle status, including version and deployment status), `Badge` (counts); `Sticker` is for tags and complementary labels, not status
 - Saved views: `TableControls` (or `DataTable.controls`) requires `onSetDefaultView` and `onUnsetDefaultView` together, or neither. Editable views offer "Set as default" / "Unset default" based on `view.isDefault`; the design system confirms before calling either callback and warns that both changes affect the entire organization. Consumers own persistence and must remove their own confirmations to avoid double prompts. Compact controls omit saved views. Pass `starredDefaultView` to star the default view: the `isDefault` view is pinned first with a star icon, cannot be dragged, hidden, deleted or unset, and its menu offers only Save, Duplicate and Reset (its name field still renames it); every other view gets the full menu. Rename and Duplicate on it call `onViewNameChange` / `onDuplicateView` with its id; Save calls `onSaveView()` with no id, saving whatever the consumer treats as the current view. A null `currentView` is shown as the starred view, so `onSaveView` and toolbar Save must treat null as the starred view; while an `isDefault` view exists, pass its id as `currentView` rather than null. A lazy default is a consumer-owned placeholder view with `isDefault: true`. While a view is the default the built-in tab is not shown and a `null` `currentView` is displayed as the starred view; with no `isDefault` view the built-in tab is shown starred and read-only.
 - DataTable filters: pass `filtersV2` (`TableControlsFiltersV2Props` / `FilterBarProps`) through `DataTable.controls` or directly to `TableControls` for a first-class FilterBar; defaults visible with size derived from `compact`. Hosts own V2 data filtering and feed `onChange` back to `initialState` for active-filter messaging; hydration needs no remount key. Precedence: `filterPanel` → `filtersV2` → legacy `filters`. Legacy `filters` supports `input`, `select`, `multiselect`, `combobox`, and `daterange` with optional `filterResolver`. With `clientFiltering`, `column.filter` generates legacy-only controls backed by TanStack column-filter state, not V2 filtering.
 - SmartTextInput: when method chains are allowed (`ValueType.MethodChain` or `{{...}}` interpolation), you MUST pass `renderFunctionForm`. PDS does not build the function-parameter form, so without it the dialog opened by placing the cursor in a call like `convert_to(...)` shows only the function name over an empty body. It receives `FunctionFormRenderProps` and must call `onComplete(nodes)` or `onCancel()`. In persona-web, `useDashboardSmartTextInputProps` supplies it (backed by `InputMethodChain/FunctionForm`). See components/SmartTextInput/SmartTextInput.mdx.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persona/design-system",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "description": "React components for Persona UI",
   "keywords": [
     "tanstack-intent"
@@ -41,6 +41,7 @@
     "./components/ButtonGroup": "./dist/components/ButtonGroup/index.mjs",
     "./components/Card": "./dist/components/Card/index.mjs",
     "./components/CardV2": "./dist/components/CardV2/index.mjs",
+    "./components/Chart": "./dist/components/Chart/index.mjs",
     "./components/Checkbox": "./dist/components/Checkbox/index.mjs",
     "./components/CodeHighlight": "./dist/components/CodeHighlight/index.mjs",
     "./components/CodeHighlight/PrismWithLanguages": "./dist/components/CodeHighlight/PrismWithLanguages.mjs",
@@ -155,6 +156,7 @@
     "./mixins/hoverable": "./dist/mixins/hoverable.mjs",
     "./mixins/input": "./dist/mixins/input.mjs",
     "./mixins/menuItem": "./dist/mixins/menuItem.mjs",
+    "./mixins/motion": "./dist/mixins/motion.mjs",
     "./mixins/print": "./dist/mixins/print/index.mjs",
     "./mixins/scrollbar": "./dist/mixins/scrollbar.mjs",
     "./mixins/text": "./dist/mixins/text.mjs",
@@ -182,6 +184,7 @@
     "build": "tsdown && node scripts/assert-no-node-imports.mjs && node scripts/assert-styled-components-interop.mjs && node scripts/assert-parser-declarations.mjs",
     "release": "scripts/release.sh --dry-run",
     "skills:validate": "intent validate skills",
+    "typecheck:charts": "node scripts/typecheck-charts.mjs",
     "tokens:generate": "node scripts/generate-semantic-tokens.mjs && node scripts/generate-charting-tokens.mjs",
     "tokens:check": "node scripts/generate-semantic-tokens.mjs --check && node scripts/generate-charting-tokens.mjs --check",
     "skills:stale": "intent stale"
@@ -242,8 +245,8 @@
     "@faker-js/faker": "^10.5.0",
     "@figma/code-connect": "^1.4.4",
     "@oxlint/plugins": "1.72.0",
-    "@persona/design-tokens": "0.4.23",
-    "@persona/icons": "0.1.12",
+    "@persona/design-tokens": "0.4.25",
+    "@persona/icons": "0.1.14",
     "@storybook/react": "^10.6.2",
     "@storybook/react-vite": "^10.6.2",
     "@tanstack/intent": "^0.3.6",
@@ -276,6 +279,7 @@
     "react-dom": "^17.0.2",
     "react-router-dom": "^6.30.5",
     "recharts": "^2.13.3",
+    "recharts-v3": "npm:recharts@^3.2.1",
     "storybook": "^10.6.2",
     "styled-components": "^5.3.5",
     "tsdown": "^0.21.0",
@@ -284,7 +288,7 @@
   },
   "peerDependencies": {
     "@persona/design-tokens": ">=0.4.17",
-    "@persona/icons": ">=0.1.0",
+    "@persona/icons": ">=0.1.14",
     "@tanstack/react-router": ">=1.0.0",
     "@testing-library/dom": ">=8",
     "@testing-library/react": ">=12",
@@ -293,6 +297,7 @@
     "react": ">=17",
     "react-dom": ">=17",
     "react-router-dom": "^6.30.1 || ^7.18.2",
+    "recharts": "^2.13.3 || ^3",
     "styled-components": "^5.3.5"
   },
   "peerDependenciesMeta": {
@@ -304,6 +309,9 @@
     },
     "oxlint": {
       "optional": true
+    },
+    "recharts": {
+      "optional": true
     }
   },
   "publishConfig": {
@@ -319,6 +327,7 @@
       "./components/ButtonGroup": "./dist/components/ButtonGroup/index.mjs",
       "./components/Card": "./dist/components/Card/index.mjs",
       "./components/CardV2": "./dist/components/CardV2/index.mjs",
+      "./components/Chart": "./dist/components/Chart/index.mjs",
       "./components/Checkbox": "./dist/components/Checkbox/index.mjs",
       "./components/CodeHighlight": "./dist/components/CodeHighlight/index.mjs",
       "./components/CodeHighlight/PrismWithLanguages": "./dist/components/CodeHighlight/PrismWithLanguages.mjs",
@@ -433,6 +442,7 @@
       "./mixins/hoverable": "./dist/mixins/hoverable.mjs",
       "./mixins/input": "./dist/mixins/input.mjs",
       "./mixins/menuItem": "./dist/mixins/menuItem.mjs",
+      "./mixins/motion": "./dist/mixins/motion.mjs",
       "./mixins/print": "./dist/mixins/print/index.mjs",
       "./mixins/scrollbar": "./dist/mixins/scrollbar.mjs",
       "./mixins/text": "./dist/mixins/text.mjs",

package/skills/new-screen/SKILL.md

@@ -44,6 +44,39 @@ Put this in the PR body before building, so the design source is consulted first
 - **Intent:** who uses the screen, to do what, in one line
 - **Source:** the live product, a Figma link, or none (say so if a source couldn't be reached)
 - **PDS version:** from the app's lockfile
+- **State changes:** the table below
+
+### State changes
+
+Give every state change on the screen one row: open and close, enter and exit, loading to loaded,
+empty, error, success, selection, disabled, and any value that updates in place.
+
+| State change | Motion | Reason |
+| ------------ | ------ | ------ |
+| Review dialog opens | `Modal`, built in | |
+| Review dialog closes | `Modal`, built in | |
+| Case list loads | `IndexViewLayoutShimmer`, built in | Built in; the shimmer holds still under reduced motion |
+| Save fails | instant | An error shouldn't wait on an animation |
+| Result count updates | instant | The number is the content |
+| Edited value is highlighted | Feedback on a surface: `TransitionDuration.Fast`, `TransitionEasing.Move` | No PDS component highlights an edit |
+
+Motion is one of these, in this order:
+
+1. **A PDS component's own motion.** Name the component's export and add nothing on top.
+2. **A usage row from the motion scale** ([STANDARD.md](../ui-authoring/STANDARD.md#motion-scale)),
+   for motion the screen authors itself: its `TransitionDuration` (CSS) or
+   `TransitionDurationInSeconds` (framer-motion) step and its `TransitionEasing` or
+   `TransitionEasingCurve`, plus `fadeIn` or `rotate` from `variables/keyframes`. Say why no
+   component covers it. No literal durations or timing functions.
+3. **`instant`**, with a reason.
+
+**Reduced motion.** Any file the screen adds that animates keeps a short opacity fade with no
+movement under reduced motion (`ReducedMotionFade`, 150 ms): a `prefers-reduced-motion` block in CSS
+(`pds/reduced-motion` checks this), or `useReducedMotion()` in framer-motion. The state changes at
+the same cue, never instantly.
+If a component's own motion ignores reduced motion, pick `instant` or another component that honours
+it. If neither works, keep the component and note the gap in the PR body as a PDS gap, not a
+departure: no screen bends the PDH-F3 floor. Don't override the component from the screen.
 
 ## Before you hand it over
 

package/skills/ui-authoring/COMPONENTS.md

@@ -17,6 +17,7 @@ exists. If there is no `.mdx`, use the published type declarations
 | `Button` | Triggering an action. Use `IconButton` when there is no label | `@persona/design-system/components/Button` |
 | `ButtonGroup` | Choosing among related modes in a compact connected button set (often icons, e.g. alignment). Use `Toggle` for a single on/off setting; `RadioGroup` for a visible list of labeled choices | `@persona/design-system/components/ButtonGroup` |
 | `Card` + `Card.Section` | Grouping related content and actions so they're easier to scan. Collapsible sections on long settings pages | `@persona/design-system/components/CardV2` |
+| `ChartFrame`, `ChartLegend`, `ChartPopover` | Experimental (beta). Charts built on `recharts` (optional peer, 2.x or 3.x): `ChartFrame` lays out legend and plot, `ChartLegend` keys and toggles series, `ChartPopover` is the `<Tooltip>` content. Colour series with `useChartColors` / `resolveSeriesColors`; style hand-built Recharts parts with `useChartStyles`. See Storybook Charts → Design | `@persona/design-system/components/Chart` |
 | `Checkbox` | Selecting one or more options from a visible list | `@persona/design-system/components/Checkbox` |
 | `Combobox` | Picking from a long list that needs search (single or multi). Use `RadioGroup` when every choice should stay visible (one); `Checkbox` when every choice should stay visible (several); `Select` for a short closed list with no search | `@persona/design-system/components/Combobox` |
 | `ConfigFormGroup` | Form fields — spacing a group of config fields and setting `configField` via context. Pair with `TextField` / `TextAreaField` | `@persona/design-system/components/ConfigFormGroup` |
@@ -63,7 +64,7 @@ exists. If there is no `.mdx`, use the published type declarations
 | `Spinner` | Showing that something is loading | `@persona/design-system/components/Spinner` |
 | `Stack` | Flex column — laying out children vertically with token spacing | `@persona/design-system/components/Stack` |
 | `StatusIndicator` | Showing a named status (open, pending, completed, failed, …) | `@persona/design-system/components/StatusIndicator` |
-| `Sticker` | Status badge — tagging nearby content with status or label metadata | `@persona/design-system/components/Sticker` |
+| `Sticker` | Tags and complementary labels on nearby content — not status (use `StatusIndicator`) | `@persona/design-system/components/Sticker` |
 | `SwatchPicker` | Picking a color from a swatch list. Wrap with `FormField` | `@persona/design-system/components/SwatchPicker` |
 | `TabBar`, `Tab` | Tabs — switching between related views or content sections | `@persona/design-system/components/TabBar` |
 | `Table` | Displaying rows and columns with sticky headers, sort, and checkbox selection. Use `DataTable` when you need filtering, bulk actions, or search | `@persona/design-system/components/Table` |
@@ -81,6 +82,23 @@ exists. If there is no `.mdx`, use the published type declarations
 | `VersionHistory` | Show previous versions of a file and let the user compare or restore one | `@persona/design-system/components/VersionHistory` |
 
 
+## Server-backed Combobox
+
+`filterMode='server'` requires flat `options`, a controlled `query` / `onQueryChange` pair and
+`selectedOptions` for every selected value, including off-page values. Query text is separate from
+the selected label: only native edits call `onQueryChange`; selection and menu transitions do not
+change it. `onInputChange` and grouped/nested browsing stay client-mode only. PDS bypasses Fuse and
+hides built-in Select all in server mode. Missing selection metadata has a `String(value)` safety
+fallback, not a selection cache. Your hook owns debounce, requests, cancellation and accumulated
+pages. Wire `onScrollEnd={loadMore}` for near-end reports and `isLoadingMore` for the optional loading
+row. Calls may repeat; the caller ignores duplicate/loading/exhausted requests. PDS has no
+`hasMore` or request lock and re-checks short lists only on open/count changes, not loading changes.
+Use generic `footerAction` for error retries. Keep `isOptionsLoading={isInitialLoading || isSearching}`
+for initial/replacement searches (`isSearching` includes debounce and page-1 requests); clear stale
+options if a replacement fails. Existing prop
+types and FormField/table wrappers remain client-only; separate `ComboboxServer*Props` types are
+exported for direct server Combobox use. See Combobox.mdx.
+
 ## Testing
 
 ```tsx