@spfx-fast/sharepoint-ui 0.4.2 → 0.4.3

package/AGENTS.md

@@ -2,11 +2,14 @@
 
 Use this page as the short route from a SharePoint task to a working component. The library is designed for SPFx 1.24 and React 18, but its custom elements can be used without React.
 
+For the predictable cross-component pattern and copy-ready Tooltip/Persona composition, start with [`QUICKSTART.md`](./QUICKSTART.md). Component pages and their linked JSON slices supply the exact component-specific props, slots, and callback signatures.
+
 ## Pick the smallest entry point
 
 - In an SPFx React web part, import the React adapter from `@spfx-fast/sharepoint-ui/react` and import only the components used.
 - In plain HTML or another framework, import a leaf definition such as `@spfx-fast/sharepoint-ui/elements/button`, then call `defineButton()` once. For native form labels, use `createLabel()` from `@spfx-fast/sharepoint-ui/elements/label`; it returns a real `<label>` so `htmlFor`/`for` association works.
 - `defineSharePointUIElements()` registers the full current catalog; use it only when the whole catalog is needed.
+- Set `brandColor` in `SharePointUIProvider` theme data to derive matching accent, focus, selection, surface, hover, and border tokens. Explicit design tokens override the derived values; the theme API also has a framework-free `@spfx-fast/sharepoint-ui/theme` entry point.
 
 For temporary feedback, mount one `Toaster` near the app root and dispatch from descendants with `useToastController()`. For a controller outside the Toaster subtree or when an app has multiple toast regions, set `toasterId` on the target Toaster and pass the same ID to `useToastController(toasterId)`. The controller supports both `updateToast(id, update)` and Fluent's `updateToast({ toastId, content, ...options })` form. Use a permanent status surface as well when the information must remain available after the toast expires.
 
@@ -33,7 +36,7 @@ Use `ContextMenu` for commands attached to a surface: right-click its trigger, o
 
 Use `SearchBox` for a free-form query, not `ComboBox` when users are choosing from suggestions. It supports controlled `value` or initial `defaultValue`, `onValueChange`, Enter submission through `onSearch`, and a localized clear button. The custom element participates in form value/reset and required validation.
 
-Use `Nav` for app destinations: `NavItem` and `NavSubItem` preserve native anchor navigation when given `href`; `NavCategoryItem` only expands/collapses its category. Any of these accepts an `Avatar` through `avatar={<Avatar name="Team" image={photoUrl} size={28} />}`; the React adapter marks it decorative so the item text stays the accessible name. Direct custom elements use `slot="avatar"` and should mark the Avatar `decorative`. Keep destination activation and category disclosure separate. `selectedValue`/`openCategories` are controlled; use `defaultSelectedValue`/`defaultOpenCategories` for initial state. `multiple` allows several categories open. Items follow normal Tab and native Enter/Space behavior. At 640px and below Nav becomes a 44px menu button with a theme-derived drawer at the logical start; Escape, outside click, and destination selection dismiss it. Use controlled `open`/`onOpenChange` or `defaultOpen`, and localize `openLabel`/`closeLabel` or provider strings `navigationMenu`/`navigationClose`. Set/inherit `dir="rtl"` for Arabic and other RTL locales. The desktop rail defaults to 260px (`--spui-nav-width`).
+Use `Nav` for app destinations: `NavItem` and `NavSubItem` preserve native anchor navigation when given `href`; `NavCategoryItem` only expands/collapses its category. Any of these accepts an `Avatar` through `avatar={<Avatar name="Team" image={photoUrl} size={28} />}`; the React adapter marks it decorative so the item text stays the accessible name. Direct custom elements use `slot="avatar"` and should mark the Avatar `decorative`. Keep destination activation and category disclosure separate. `selectedValue`/`openCategories` are controlled; use `defaultSelectedValue`/`defaultOpenCategories` for initial state. `multiple` allows several categories open. Items follow normal Tab and native Enter/Space behavior. At 640px and below Nav becomes a 44px menu button with a theme-derived drawer at the logical start; Escape, outside click, and destination selection dismiss it. Use controlled `open`/`onOpenChange` or `defaultOpen`, and localize `openLabel`/`closeLabel` or provider strings `navigationMenu`/`navigationClose`. Set the provider `lang`; it derives LTR/RTL, and an explicit `dir` overrides that choice. The desktop rail defaults to 260px (`--spui-nav-width`).
 
 For a Fluent-shaped application shell, compose `NavDrawer` with `NavDrawerHeader`, `NavDrawerBody`, and `NavDrawerFooter`; choose `type="overlay"` or `type="inline"`. Its default `tabbable={false}` follows roving arrow navigation; opt into `tabbable` when each destination should be a Tab stop. Use `selectedCategoryValue`/`defaultSelectedCategoryValue` for the selected category and the Fluent callback names `onNavItemSelect`/`onNavCategoryItemToggle` when sharing code with Fluent. `AppItem` is a destination, `AppItemStatic` is decorative identity text, and `SplitNavItem` keeps its primary destination independent from optional action, menu, and toggle buttons; add matching tooltip slots for accessible labels. Connect `Hamburger.onClick` to the owning controlled `open` state.
 
@@ -146,11 +149,14 @@ For a people stack with named overflow details, compose `AvatarGroupItem` childr
 - React refs are supported on 157 catalogued adapters and target the rendered root element (normally the custom-element host; `InfoLabel` targets its `span`; standalone `Option`/`OptionGroup` render a `div` outside a ComboBox). `Input` and `TextArea` refs also expose `focus()` and `select()`. `npm run verify:react-refs` checks every ref-enabled catalog entry in Chromium.
 - Override CSS variables for broad design changes and `::part(...)` for one component detail. Fonts inherit through `--spui-font-family`.
 - In tests, prefer role/name queries and stable user-visible semantics. Add `data-testid` to the component host only when semantics are insufficient; custom elements accept it directly, and React adapters forward it to the host. Avoid selectors based on shadow DOM internals or generated IDs.
-- Set `lang` and `dir` for content language and reading direction. Supply localized provider strings for every built-in label used by the page.
+- Set `lang` for content language; `SharePointUIProvider` derives `dir` from it. Set `dir` only when the region's direction should override its language. Supply localized provider strings for every built-in label used by the page.
 - Use the `fluent`, `ios`, `windows`, or `linux` base appearance. The no-host-theme accent fallback is stone (`DEFAULT_ACCENT`, `#78716c`); SharePoint semantic theme colors override it when provided. Accent hover, focus fallback, and glass tint derive from the active accent. `glass` derives surface and spacing from its selected base appearance and theme.
 
 ## Data and rich text
 
+- For metadata-driven React forms, render `<SharePointField field={field} value={values[name]} onValueChange={...} options={lookupOptions[name]} />` from `@spfx-fast/sharepoint-ui/react`. It selects the matching control, applies accessible field labels and constraints, and supports rich-text Notes. The host supplies Lookup/User options from an authorized data source; built-in Choice values come from SharePoint metadata. For custom layouts, use `getSharePointFieldAdapter(field)` and render its recipe explicitly. Use `serializeSharePointFieldValues(fields, valuesByInternalName)` for one PATCH body: omitted values stay untouched, `null` clears optional fields, and invalid or unknown values throw. It validates supplied values only; new-item forms must include every required value. `getSharePointListItemUrl(webUrl, listId, itemId)` constructs the item endpoint; the host still owns authorization, ETag, and REST entity-type metadata. The adapter's `required`, `readOnly`, `step`, `min`, `max`, and `maxLength` metadata should drive the UI. Generic and focused serializers reject read-only or empty required values and enforce configured numeric precision and bounds. URL recipes expose `urlFormat` (`hyperlink` or `picture`) for record views. Use `getSharePointNextPageUrl(webUrl, nextLink)` to safely follow same-origin OData pages. `getSharePointLookupOptionsUrl(field, sourceWebUrl)` builds lookup requests. These helpers validate and shape data but do not send requests or replace SharePoint permissions and server validation; people search remains tenant-authorized app work.
+
+- Forward SharePoint adapter `min`, `max`, and `maxLength` to matching controls when present. The serializers enforce those numeric bounds and text limits too; SharePoint remains the final validator.
 - Use `ColorPicker` when users need a theme-aware color choice. Its `value` is `#RRGGBB`, `alpha` is `0`–`1`, and `onValueChange(value, alpha)` receives both values. Pass `colors` for app-specific swatches; tenant accent, success, warning, and danger swatches are included by default. The element submits `#RRGGBB` or `#RRGGBBAA` as a native form value.
 
 - Use `Table` for compact composable rows and `DataGrid` for virtualized/editable data. Compose `TableHeader`, `TableBody`, `TableRow`, `TableHeaderCell`, and `TableCell`; use `TableSelectionCell` for selection, `TableCellLayout`/`TableCellActions` for concise record content, `TableResizeHandle` for consumer-controlled width, and `createTableColumn` for reusable column definitions. Sorting and resizing emit requests: keep that state in the host and pass it back through `sortDirection` or `value`.
@@ -163,10 +169,24 @@ For a people stack with named overflow details, compose `AvatarGroupItem` childr
 - For framework-neutral Tree, import `defineTree` from `@spfx-fast/sharepoint-ui/elements/tree`, assign `items`, `expandedKeys`, and `selectedKeys` properties, and listen for `spui-tree-expanded-change` and `spui-tree-selection-change`.
 - Localize React defaults with `SharePointUIProvider` strings: `Tree`/`FlatTree` use `treeLabel`, `treeToggleLabel`, `treeEmptyMessage`; `Toolbar`, `Breadcrumb`, and `MenuBar` use their matching `*Label` strings; `SplitButton`, `Hamburger`, and `SplitNavItem` use `splitButtonMenuLabel`, `navigationToggle`, and `splitNavItemActionLabel`; virtualized lists use `virtualizerLabel`; row selection and resize handles use `dataGridSelectRow` and `tableResizeHandle`. Explicit labels take precedence. Direct custom elements use their `label`/`aria-label` attributes.
 - Use `Tag` inside a labelled `TagGroup` for filters and selected values. A dismissible React Tag calls `onDismiss(value, label)`; update the parent array to remove it. Semantic colors and `brand` appearance derive from the active SharePoint theme. For framework-neutral use, import `defineTag` and `defineTagGroup` from `@spfx-fast/sharepoint-ui/elements/tags` and listen for `spui-dismiss`.
-- Use `TagPicker` when users need to search and select multiple values. Supply unique stable option values, a visible label, and controlled `selectedValues`/`onChange`; disabled options cannot be selected. Its `name` submits repeated values in native forms. For framework-neutral use, import `defineTagPicker` from `@spfx-fast/sharepoint-ui/elements/tag-picker`, assign the `value` array, and listen for `spui-change`.
+- Use `TagPicker` when users need to search and select multiple values. Supply unique stable option values, a visible label, and controlled `selectedValues`/`onChange`; disabled options cannot be selected. Its popup flips and sizes within the viewport and clipping ancestors, including SharePoint sections; set `positioning` for placement, alignment, fallback, offset, or explicit boundary control. Its `name` submits repeated values in native forms. For framework-neutral use, import `defineTagPicker` from `@spfx-fast/sharepoint-ui/elements/tag-picker`, assign the `value` array, and listen for `spui-change`.
 - Use `Rating` for a labelled star score. `value` is controlled; `defaultValue` initializes an uncontrolled rating. Use `step={0.5}` for half stars, set `max` for the scale, and provide `itemLabel` when the radio option labels need custom localization.
 - For framework-neutral `spui-virtual-list`, assign `items`, `renderItem`, and `itemKey` after importing `defineVirtualList`. Set `axis="horizontal"` or its `axis` property, `item-size`/`itemSize` for the estimated width or height, and `measure-items`/`measureItems` to track rendered sizes. `row-height` remains the vertical compatibility alias. Set `--spui-list-width` for a horizontal viewport; direction follows inherited `dir`, including logical RTL scrolling. Use `scrollToIndex(index, "start" | "center" | "end", behavior)` for programmatic navigation.
 - `RichTextEditor` emits allowlist-normalized HTML. Store it in a SharePoint rich-text field and render it back through the editor or another sanitizer-aware view; do not inject saved HTML with raw `innerHTML`. After inserting a table, click a cell to enable row/column insertion and deletion; table removal is available from any selected cell. Editing controls disable for merged cells so row/column changes cannot corrupt their spans. Localize the toolbar through `SharePointUIProvider.strings` (for example, `richTextInsertRowBelow` and `richTextDeleteTable`).
+- Pass a SharePoint multiline field's metadata as React `field={column}` so the editor derives the maximum content mode the field can store. `RichText: false` selects plain text; `RestrictedMode: true` removes enhanced rich actions; `RichTextMode: "Compatible"` selects compatible rich formatting; `"FullHtml"` selects the broad sanitized HTML mode. Explicit `contentMode` may narrow but never exceed that capability ceiling; `allowHyperlink={false}` can further disable links, but cannot override `AllowHyperlink: false`. For framework-neutral custom elements, spread `getRichTextEditorFieldOptions(column)` instead. If no restrictions are available, the editor keeps the broad sanitized HTML mode.
+- Connect the editor's `linkPicker` to the SPFx app's existing page/file picker; this keeps tenant-specific picker dependencies out of the UI package. Return `null` on cancel, otherwise map the selected item's absolute URL and optional label into `RichTextEditorLink`. The editor validates the URL and leaves it for review before Apply.
+
+```tsx
+import { RichTextEditor, type RichTextEditorLink } from "@spfx-fast/sharepoint-ui/react";
+
+const linkPicker = async (current: RichTextEditorLink | null) => {
+  const selected = await pageFilePicker.open({ initialUrl: current?.href });
+  return selected ? { href: selected.url, text: selected.name, title: selected.name } : null;
+};
+
+<RichTextEditor value={html} onValueChange={setHtml} linkPicker={linkPicker}
+  onLinkPickerError={error => console.error("SharePoint link picker failed", error)} />
+```
 - Persist through `SPHttpClient` in the web part. Include loading, saved, and error states, and verify important writes by reading the item back.
 
 ## Before handing off a web part

package/QUICKSTART.md

@@ -0,0 +1,133 @@
+# SharePoint UI quickstart
+
+Install `@spfx-fast/sharepoint-ui`. Use the component page’s React export, properties, slots, and callback table as the source of truth.
+
+## React in an SPFx web part
+
+Wrap the web part view once. Pass the current page culture; the provider applies the locale and text direction. Keep SharePoint reads, writes, and business rules in the web part.
+
+```tsx
+import { Button, SharePointUIProvider, ViewCard } from "@spfx-fast/sharepoint-ui/react";
+
+type Request = { id: number; title: string; status: string };
+
+export function RequestList({
+  requests,
+  locale,
+  openRequest,
+}: {
+  requests: Request[];
+  locale: string;
+  openRequest: (id: number) => void;
+}) {
+  return (
+    <SharePointUIProvider lang={locale}>
+      {requests.map(request => (
+        <ViewCard key={request.id} kind="list-item" title={request.title} description={request.status}>
+          <Button slot="actions" onClick={() => openRequest(request.id)}>Open</Button>
+        </ViewCard>
+      ))}
+    </SharePointUIProvider>
+  );
+}
+```
+
+In the web part, pass `this.context.pageContext.cultureInfo.currentUICultureName` as `locale`. For a single control, import its React export from `/react`; import only what the view uses.
+
+Set `brandColor` on the provider theme to derive a coordinated accent, focus, selection, surface, hover, and border palette. Explicit design tokens override the derived values; see the [theme guide](https://vystartasv.github.io/sharepoint-ui/guides/theming-and-direction/).
+
+## The shared component pattern
+
+- Every React adapter is a named export from `@spfx-fast/sharepoint-ui/react`. React imports register the element automatically; do not call `defineX()` in React.
+- Put `SharePointUIProvider` once around the view. Theme, font, locale, direction, and provider strings flow to descendants.
+- Compose components with children. Use a named slot or a component-specific prop only when its page documents one; the `Slots` table shows the exact names.
+- When an API has controlled state, pass its state prop and update it in the documented callback. `defaultX` supplies initial state where supported. State names and callback arguments are component-specific; copy them from that component’s page rather than guessing.
+- Styling and host attributes belong on the component host. Use inherited theme tokens, documented CSS custom properties or `::part` hooks; do not target shadow-DOM internals.
+- Keep labels, accessible names, and app behavior in the host view. The component handles its documented interaction and reports changes; the web part handles SharePoint data and persistence.
+
+Use composition like this:
+
+```tsx
+import { Avatar, Button, Persona, Tooltip } from "@spfx-fast/sharepoint-ui/react";
+
+export function RequestActions({ openRequest, photoUrl }: { openRequest: () => void; photoUrl: string }) {
+  return (
+    <>
+      <Tooltip content="Opens the request details">
+        <Button onClick={openRequest}>Open request</Button>
+      </Tooltip>
+      <Persona
+        name="Ada Lovelace"
+        primaryText="Ada Lovelace"
+        secondaryText="Engineering"
+        avatar={<Avatar name="Ada Lovelace" image={photoUrl} decorative />}
+      />
+    </>
+  );
+}
+```
+
+`Tooltip` uses its children as the trigger and its `content` as the tooltip. `Persona` accepts identity text directly and an optional composed `Avatar`. Other components follow the same import, provider, children, and host-styling rules; use their own page for their specific props, slots, and callback signatures. For Tooltip controlled visibility, use `open` with `onOpenChange`; `visible` and `onVisibleChange` remain compatibility aliases.
+
+For a responsive command shelf, let `Overflow` move lower-priority actions into its menu. `useStoredOverflowCompactMode` remembers a per-browser compact spacing choice; include the app and site in its key so separate workspaces do not share a setting:
+
+```tsx
+import { Button, Overflow, OverflowItem, ToggleButton, useStoredOverflowCompactMode } from "@spfx-fast/sharepoint-ui/react";
+
+function RequestCommands({ siteId }: { siteId: string }) {
+  const { compact, setCompact } = useStoredOverflowCompactMode(`requests:${siteId}`);
+  return <>
+    <ToggleButton pressed={compact} onPressedChange={setCompact}>Compact commands</ToggleButton>
+    <Overflow label="Request actions" density={compact ? "compact" : "comfortable"}>
+      <OverflowItem id="open" priority={2}><Button>Open</Button></OverflowItem>
+      <OverflowItem id="share" priority={1}><Button>Share</Button></OverflowItem>
+    </Overflow>
+  </>;
+}
+```
+
+For custom elements, set `density="compact"` on `<spui-overflow>` and persist the toggle with the app's preferred storage. Token-sized controls remain at least 44px tall on coarse-pointer devices; explicit component sizes stay in effect.
+
+## Another framework or plain HTML
+
+Import only the component’s leaf factory, register it once, then use its documented custom-element tag:
+
+```ts
+import { defineButton } from "@spfx-fast/sharepoint-ui/elements/button";
+
+defineButton();
+```
+
+```html
+<spui-button appearance="primary">Open</spui-button>
+```
+
+## SPFx 1.24 Copilot UX components
+
+For a Copilot surface that reads SharePoint data, updates the visible-state context, and saves through `SPHttpClient`, use the [SPFx CLI template](https://github.com/vystartasv/sharepoint-ui/tree/main/templates/spfx-fast-copilot-access-review) or the [complete tenant-connected example](https://github.com/vystartasv/sharepoint-ui/tree/main/examples/spfx124-copilot-ux). Both are framework-free and import only the custom elements they use.
+
+For a metadata-driven form, use `<SharePointField>` from `/react` or `<spui-sharepoint-field>` without React. Both select the control from SharePoint metadata, apply accessible labels and field rules, and support rich-text Notes. Load Lookup/User options in the host; Choice values come from field metadata. For custom elements, register once and set object data as properties:
+
+```ts
+import { defineSharePointField } from "@spfx-fast/sharepoint-ui/elements/sharepoint-fields";
+
+defineSharePointField();
+const control = document.querySelector("spui-sharepoint-field")!;
+control.field = column;
+control.value = item[column.InternalName];
+control.options = lookupOptions;
+control.addEventListener("spui-field-value-change", event => updateDraft(event.detail.field, event.detail.value));
+```
+
+For custom layouts, request definitions with `getSharePointFieldMetadataUrl(webUrl, listId)` and inspect each `getSharePointFieldAdapter(field)` recipe. Use `serializeSharePointFieldValues(fields, valuesByInternalName)` to assemble a PATCH body: omitted values stay untouched and `null` clears optional fields. New-item forms must include every required value. `getSharePointListItemUrl(webUrl, listId, itemId)` builds a validated item endpoint; the host supplies authorization, ETag, and REST entity-type metadata. Generic and focused serializers reject empty required values and read-only writes, enforce configured numeric precision and bounds, and reject values over the configured text length. `getSharePointNextPageUrl(webUrl, nextLink)` safely resolves same-origin OData paging links; `getSharePointLookupOptionsUrl(field, sourceWebUrl)` builds lookup requests. The app supplies authorized fetches, people search, permissions, and persistence.
+
+Forward adapter `min`, `max`, and `maxLength` to matching controls when present. The serializers enforce numeric bounds and text lengths too; SharePoint remains the final validator.
+
+## Build from a component page
+
+1. Copy the React export or custom-element tag and its property/slot table.
+2. Use the matching component JSON slice linked from that page for exact types and callbacks.
+3. Use the shared `agentContract` included in every component JSON slice, then follow that component’s exact state props, callbacks, and slots.
+4. Keep app state and persistence in the host; connect documented callbacks to it.
+
+The same pattern applies across components. Add `SharePointUIProvider` once at the view root for React; custom elements inherit theme and direction from their host context. Each component slice links to its module event inventory. `detailPropertiesComplete` tells whether the listed event detail keys are exhaustive. Events are module-scoped: when several tags share a module, check the event target before handling them. Use the [component conventions guide](https://vystartasv.github.io/sharepoint-ui/guides/component-patterns/) for human-readable composition examples and the component page plus its JSON slice for exact APIs.

package/README.md

@@ -32,8 +32,10 @@ defineButton();
 <spui-button appearance="primary">Save</spui-button>
 ```
 
-**Docs and live catalog:** [spfx-fast.github.io/sharepoint-ui-docs](https://vystartasv.github.io/sharepoint-ui-docs/)
+**Docs:** [component catalog](https://vystartasv.github.io/sharepoint-ui/) · **Agent quickstart:** [build from a component page](https://vystartasv.github.io/sharepoint-ui/agents/QUICKSTART.md) · **Agent references:** [instructions and API slices](https://vystartasv.github.io/sharepoint-ui/agents/)
 
 The docs cover theming, RTL, accessibility, forms, rich-text persistence, and every component. See [AGENTS.md](./AGENTS.md) for agent guidance and [components.json](./components.json) for the API catalog.
 
+For framework-independent theme helpers, import from `@spfx-fast/sharepoint-ui/theme`. Set `brandColor` in `SharePointUIDesignTheme` to derive coordinated accent, focus, selection, surface, hover, and border colors.
+
 [MIT License](./LICENSE)

package/components.json

@@ -340,15 +340,39 @@
           "host className/style"
         ],
         "reactSignature": "{ children, selectedValue, defaultSelectedValue, selectedValues, defaultSelectedValues, selectionMode = \"single\", layout = \"grid\", size = \"medium\", shape = \"square\", spacing = \"medium\", focusMode = \"arrow\", columns = 6, onSelectionChange, ...props }: SwatchPickerProps",
-        "reactRefType": "HTMLElement"
+        "reactRefType": "HTMLElement",
+        "relatedReactApis": [
+          {
+            "name": "useSavedSwatchPalettes(store)",
+            "description": "Load, save, remove, and refresh named palettes through a stable host-owned store. Use the app's SharePoint data service for tenant-wide persistence; the hook adds no network or storage dependency. See the saved palettes guide for a complete React recipe."
+          },
+          {
+            "name": "SwatchPaletteStore",
+            "description": "Implement list, save, and remove with the app's current persistence service. Keep the store object stable across React renders."
+          },
+          {
+            "name": "SavedSwatchPalette",
+            "description": "A named palette record with an id and color entries containing value, color, and optional label."
+          },
+          {
+            "name": "SharePointThemeSwatches",
+            "description": "Compose inside SwatchPicker to render every color in the nearest SharePointUIProvider theme palette. Pass palette to override the provider palette, or labelForColor to localize accessible color names."
+          },
+          {
+            "name": "getSharePointThemeColorPresets(palette, labelForKey?)",
+            "description": "Framework-neutral helper that maps every non-empty SharePoint palette entry, including custom tenant keys, to named swatch data."
+          },
+          {
+            "name": "SharePointThemeColorPreset",
+            "description": "A named palette key, controlled value, CSS color, and accessible label."
+          }
+        ]
       },
       "react": "SwatchPicker",
       "tag": "spui-swatch-picker",
       "define": "defineSwatchPicker",
       "summary": "Render accessible color and image swatches as a keyboard-operable single- or multi-selection grid or row.",
-      "highValueAdditions": [
-        "Offer reusable named theme-color presets alongside caller-defined palettes."
-      ]
+      "highValueAdditions": []
     },
     {
       "module": "swatch-picker",
@@ -449,7 +473,13 @@
       "module": "overflow",
       "category": "actions",
       "api": {
-        "reactSignature": "{ children, label, minimumVisible = 0, overflowDirection = \"end\", overflowAxis = \"horizontal\", hasHiddenItems = false, overflowContent, padding = 10, onOverflowChange, onOverflowItemSelect, ...props }: ElementProps & { children?: React.ReactNode; label?: string; minimumVisible?: number; overflowDirection?: \"start\" | \"end\"; overflowAxis?: OverflowAxis; hasHiddenItems?: boolean; overflowContent?: React.ReactNode; padding?: number; onOverflowChange?: (event: null, data: OverflowState) => void; onOverflowItemSelect?: (id: string) => void }",
+        "reactSignature": "{ children, label, minimumVisible = 0, overflowDirection = \"end\", overflowAxis = \"horizontal\", density = \"comfortable\", hasHiddenItems = false, overflowContent, padding = 10, onOverflowChange, onOverflowItemSelect, ...props }: ElementProps & { children?: React.ReactNode; label?: string; minimumVisible?: number; overflowDirection?: \"start\" | \"end\"; overflowAxis?: OverflowAxis; density?: OverflowDensity; hasHiddenItems?: boolean; overflowContent?: React.ReactNode; padding?: number; onOverflowChange?: (event: null, data: OverflowState) => void; onOverflowItemSelect?: (id: string) => void }",
+        "relatedReactApis": [
+          {
+            "name": "useStoredOverflowCompactMode(storageKey, defaultCompact?)",
+            "description": "Persist this browser's compact command-shelf choice; use the returned compact value as Overflow density and setCompact or toggleCompact from a ToggleButton. Scope storageKey to the app and SharePoint site. Custom-element consumers can set density=compact directly and persist it with their own preference store."
+          }
+        ],
         "callbackProps": [
           "onOverflowChange",
           "onOverflowItemSelect"
@@ -465,10 +495,8 @@
           "named ::part hooks"
         ]
       },
-      "summary": "Keep priority actions visible as space changes and render the overflowed actions through the existing Menu primitives without cloning or moving controls.",
-      "highValueAdditions": [
-        "Add a priority-aware responsive command shelf with group labels and persisted compact mode."
-      ]
+      "summary": "Keep priority actions visible as space changes, move the rest into a menu, and let a stored user preference switch the shelf to compact spacing.",
+      "highValueAdditions": []
     },
     {
       "react": "OverflowProvider",
@@ -586,7 +614,8 @@
           "motion accepts slide attraction physics: { kind: \"slide\", duration?: number }; duration follows Embla’s 20–60 recommendation"
         ],
         "highValueAdditions": [
-          "Enable drag with keyboard-equivalent announcements and preserve end padding when slides are centered."
+          "Enable drag with keyboard-equivalent announcements and preserve end padding when slides are centered.",
+          "Use CarouselNav appearance=thumbnails with CarouselNavImageButton for a horizontally scrollable image-preview strip."
         ],
         "reactRefType": "HTMLElement"
       },
@@ -918,8 +947,11 @@
           "default",
           "leading",
           "eyebrow",
+          "title",
+          "subtitle",
+          "description",
           "status",
-          "footer"
+          "actions"
         ],
         "styling": [
           "SharePointUIProvider tokens",
@@ -1452,6 +1484,37 @@
       },
       "summary": "Edit a single-line value with an accessible label and controlled change events."
     },
+    {
+      "react": "SharePointField",
+      "tag": "spui-sharepoint-field",
+      "define": "defineSharePointField",
+      "module": "sharepoint-fields",
+      "category": "forms",
+      "summary": "Render SharePoint field metadata with accessible controls in React or as a framework-free custom element.",
+      "api": {
+        "reactSignature": "{ field, value, defaultValue, options: providedOptions, onValueChange, disabled = false, hint, validationMessage, renderUnsupported, addChoiceLabel = \"Add another choice\", emptyOptionLabel = \"Select an option\", className, style, ...hostProps }: SharePointFieldProps",
+        "callbackProps": [
+          "onValueChange"
+        ],
+        "slots": [],
+        "styling": [
+          "SharePointUIProvider tokens",
+          "Field label, hint, and validation states",
+          "id, ARIA, data attributes, className, and style"
+        ],
+        "customElementProperties": [
+          "field",
+          "value",
+          "defaultValue",
+          "options",
+          "onValueChange",
+          "renderUnsupported"
+        ],
+        "customElementEvents": [
+          "spui-field-value-change"
+        ]
+      }
+    },
     {
       "react": "SearchBox",
       "tag": "spui-search-box",
@@ -1487,7 +1550,7 @@
       "module": "text",
       "category": "typography",
       "api": {
-        "reactSignature": "{ as = \"span\", size = 300, weight, font = \"base\", align = \"start\", italic = false, underline = false, strikethrough = false, truncate = false, wrap = true, block = false, children, ...props }: TextProps",
+        "reactSignature": "{ as = \"span\", size = 300, weight, font = \"base\", align = \"start\", italic = false, underline = false, strikethrough = false, truncate = false, wrap = true, block = false, children, style, ...props }: TextProps",
         "callbackProps": [],
         "slots": [
           "default"
@@ -1817,7 +1880,7 @@
       "registered": false,
       "note": "Uses a native HTML label to preserve browser label association and click-to-focus behavior; createLabel returns an HTMLLabelElement for non-React consumers.",
       "api": {
-        "reactSignature": "{ htmlFor, size = \"medium\", weight = \"regular\", required = false, disabled = false, children, style, ...props }: React.LabelHTMLAttributes<HTMLLabelElement> & { size?: LabelSize; weight?: LabelWeight; required?: LabelRequired; disabled?: boolean }",
+        "reactSignature": "{ htmlFor, size = \"medium\", weight = \"regular\", required = false, disabled = false, children, style, ...props }: LabelProps",
         "reactRefType": "HTMLLabelElement",
         "callbackProps": [],
         "slots": [
@@ -1976,6 +2039,10 @@
       "api": {
         "reactSignature": "inputProps: ComboBoxProps",
         "relatedReactApis": [
+          {
+            "name": "ComboBoxProps.requiredMessage",
+            "description": "Sets the native form validation message; defaults to SharePointUIProvider.strings.required."
+          },
           {
             "name": "ComboBoxProps.selectedLabel",
             "description": "In multiselect mode, names the selected-options group; defaults to SharePointUIProvider.strings.selectedOptionsLabel."
@@ -2240,14 +2307,69 @@
       "api": {
         "reactSignature": "inputProps: RichTextEditorProps",
         "relatedReactApis": [
+          {
+            "name": "RichTextEditorProps.field",
+            "description": "Pass SharePoint Note metadata directly; the editor derives its capability ceiling. contentMode and allowHyperlink may narrow that ceiling, but cannot enable features the field forbids."
+          },
+          {
+            "name": "RichTextEditorProps.contentMode",
+            "description": "Choose plain, restricted, rich, or sanitized html output. With field metadata, this prop may narrow but cannot exceed the destination field's capabilities. Omit it for field-derived mode or unconstrained sanitized html."
+          },
+          {
+            "name": "getRichTextEditorFieldOptions(field)",
+            "description": "Maps SharePoint RichText, RestrictedMode, RichTextMode, and AllowHyperlink metadata to editor capabilities. Explicit restrictions are preserved; missing restrictions default to sanitized html. React consumers can pass field={metadata} directly."
+          },
           {
             "name": "RichTextEditorProps.editorLabel",
             "description": "Accessible name used when no aria-label or visible label is supplied; defaults to SharePointUIProvider.strings.richTextEditorLabel."
+          },
+          {
+            "name": "RichTextEditorProps color labels",
+            "description": "SharePointUIProvider.strings.richTextTextColor, richTextHighlightColor, richTextCustomColor, richTextThemeAccent, richTextFontFamily, richTextFontSize, and colorSwatch localize color and font controls and their palette labels. These are available for compatible-rich and FullHtml fields; restricted/plain fields hide them. Safe inline font/color styles are sanitized before values are emitted."
+          },
+          {
+            "name": "RichTextEditorProps.onValueChange",
+            "description": "Receives sanitized HTML after edits. With a controlled value prop, update that prop from this callback; the editor preserves its live selection while React applies the committed value."
+          },
+          {
+            "name": "RichTextEditorProps.onImageUpload",
+            "description": "Upload the selected file and return its URL string, or return { src, alt } to provide meaningful image alternative text. The object form requires alt; use alt: \"\" only for decorative images. String results use filename-based alternative text."
+          },
+          {
+            "name": "RichTextEditor mobile selection",
+            "description": "On touch devices, press and hold text to use the browser's native selection handles. The editor does not force blur or refocus during the gesture; toolbar formatting uses the saved range."
+          },
+          {
+            "name": "RichTextEditorProps.onImageUploadError",
+            "description": "Receives the failed image filename and error when the application-managed upload fails or returns an unsafe URL."
+          },
+          {
+            "name": "RichTextEditorProps.linkPicker",
+            "description": "Opens the host application's SharePoint picker with the current link, then fills the editor for review before the user applies it. Return null to cancel."
+          },
+          {
+            "name": "RichTextEditorProps.onLinkPickerError",
+            "description": "Receives an error when the host-provided SharePoint link picker fails."
+          },
+          {
+            "name": "SharePointUIProvider.strings.richTextLink*",
+            "description": "Customize the link editor's accessible name, field labels, action labels, picker states, and validation messages for the active language."
+          },
+          {
+            "name": "SharePointUIProvider.strings.richText*",
+            "description": "Localize the text-style menu, block names, formatting buttons, table actions, link editor, image controls, and required message."
+          },
+          {
+            "name": "RichTextEditor full HTML formatting",
+            "description": "Subscript, superscript, and left/center/right/justified paragraph alignment are available only when the effective contentMode is html. Localize them with SharePointUIProvider.strings.richTextSubscript, richTextSuperscript, richTextAlignLeft, richTextAlignCenter, richTextAlignRight, and richTextAlignJustify."
           }
         ],
         "callbackProps": [
           "onValueChange",
-          "onImageUpload"
+          "onImageUpload",
+          "onImageUploadError",
+          "linkPicker",
+          "onLinkPickerError"
         ],
         "slots": [],
         "styling": [
@@ -2258,7 +2380,10 @@
         ],
         "reactRefType": "HTMLElement"
       },
-      "summary": "Edit sanitized rich HTML with controlled or uncontrolled form values, accessible formatting history, table editing, and application-managed durable image upload for SharePoint persistence."
+      "summary": "Edit sanitized content with block styles, font family and size, text and highlight colors where the SharePoint field permits them, lists, tables, safe links, and host-managed images. Field metadata selects plain, restricted, compatible-rich, or FullHtml behavior.",
+      "highValueAdditions": [
+        "Preview SharePoint page titles and destination details before inserting internal links."
+      ]
     },
     {
       "react": "Spinner",
@@ -2396,7 +2521,7 @@
         ],
         "reactRefType": "HTMLElement"
       },
-      "summary": "Group related messages with consistent spacing and optional entry motion."
+      "summary": "Stack related status messages with optional entry, exit, and reflow motion."
     },
     {
       "react": "MessageBarTitle",
@@ -3149,6 +3274,7 @@
           "onMultiSortChange",
           "onFilterValueChange",
           "onCellEdit",
+          "onCellEditError",
           "validateCellEdit",
           "getRowHeight",
           "onCellsEdit",
@@ -3166,7 +3292,7 @@
         "editing": {
           "columnOptions": "editable?: boolean; editType?: text | number | date",
           "activation": "Enter, F2, or double-click",
-          "commit": "Enter or focus leaving the editor; async onCellEdit errors keep the editor open",
+          "commit": "Enter or focus leaving the editor; async onCellEdit errors keep the editor open and call onCellEditError",
           "cancel": "Escape",
           "validation": "validateCellEdit returns an accessible error message",
           "persistence": "Callback receives row id, column id, previous value, new value, and item. The host owns SharePoint persistence and should supply refreshed items after save."
@@ -3505,8 +3631,12 @@
       "module": "tag-picker",
       "category": "form",
       "api": {
-        "reactSignature": "{ children, label, selectedLabel, selectedOptions, defaultSelectedOptions, selectedValues, defaultSelectedValues, inputValue, open, defaultOpen, positioning, disableAutoFocus = false, inline = false, noPopover = false, disabled, onOpenChange, onOptionSelect, onInputValueChange, onChange, ...props }: TagPickerProps",
+        "reactSignature": "{ children, label, selectedLabel, requiredMessage, selectedOptions, defaultSelectedOptions, selectedValues, defaultSelectedValues, inputValue, open, defaultOpen, positioning, disableAutoFocus = false, inline = false, noPopover = false, disabled, onOpenChange, onOptionSelect, onInputValueChange, onChange, ...props }: TagPickerProps",
         "relatedReactApis": [
+          {
+            "name": "TagPickerProps.requiredMessage",
+            "description": "Sets the native form validation message; defaults to SharePointUIProvider.strings.required."
+          },
           {
             "name": "TagPickerProps.selectedLabel",
             "description": "Names the selected-options group; defaults to SharePointUIProvider.strings.selectedOptionsLabel."
@@ -3517,7 +3647,7 @@
           },
           {
             "name": "TagPickerProps.positioning",
-            "description": "Positions the options surface relative to the control; supports placement shorthands, alignment, fallbacks, and offsets."
+            "description": "Positions and sizes the options surface within viewport or clipping-ancestor boundaries; supports placement, alignment, fallbacks, offsets, and custom bounds."
           },
           {
             "name": "TagPickerProps.disableAutoFocus",
@@ -3542,10 +3672,9 @@
         ],
         "reactRefType": "HTMLElement"
       },
-      "summary": "Search, choose, and remove multiple values with keyboard and native form support.",
+      "summary": "Search, choose, and remove multiple values with keyboard, native form support, and popup placement that adapts to SharePoint sections.",
       "highValueAdditions": [
-        "Add composed control, input, selected-tag group, and list primitives while preserving the single state engine.",
-        "Position the options surface against viewport and clipping ancestors, including SharePoint sections."
+        "Add composed control, input, selected-tag group, and list primitives while preserving the single state engine."
       ]
     },
     {
@@ -3703,7 +3832,13 @@
       "module": "rating",
       "category": "forms",
       "api": {
-        "reactSignature": "{ value, defaultValue = 0, max = 5, step = 1, size = \"extra-large\", color = \"neutral\", label, itemLabel, iconFilled, iconOutline, fullValueInput, halfValueInput, name, disabled = false, readOnly = false, required = false, onChange, ...props }: RatingProps",
+        "reactSignature": "{ value, defaultValue = 0, max = 5, step = 1, size = \"extra-large\", color = \"neutral\", label, requiredMessage, itemLabel, iconFilled, iconOutline, fullValueInput, halfValueInput, name, disabled = false, readOnly = false, required = false, onChange, ...props }: RatingProps",
+        "relatedReactApis": [
+          {
+            "name": "RatingProps.requiredMessage",
+            "description": "Sets the native form validation message; defaults to SharePointUIProvider.strings.required."
+          }
+        ],
         "callbackProps": [
           "itemLabel",
           "onChange"
@@ -4896,7 +5031,7 @@
       "module": "nav",
       "category": "navigation",
       "api": {
-        "reactSignature": "{ children, label = \"Navigation\", selectedValue, defaultSelectedValue, selectedCategoryValue, defaultSelectedCategoryValue, openCategories, defaultOpenCategories = [], open, defaultOpen, collapsed, defaultCollapsed, collapsible = false, multiple = true, density = \"medium\", openLabel, closeLabel, onItemSelect, onCategoryToggle, onNavItemSelect, onNavCategoryItemToggle, onOpenChange, onCollapsedChange, onClick, onClickCapture, onKeyDown, onKeyDownCapture, onKeyUp, onKeyUpCapture, onKeyPress, onKeyPressCapture, onFocus, onFocusCapture, onBlur, onBlurCapture, onAuxClick, onAuxClickCapture, onContextMenu, onContextMenuCapture, onDoubleClick, onDoubleClickCapture, onMouseDown, onMouseDownCapture, onMouseMove, onMouseMoveCapture, onMouseOut, onMouseOutCapture, onMouseOver, onMouseOverCapture, onMouseUp, onMouseUpCapture, onGotPointerCapture, onGotPointerCaptureCapture, onLostPointerCapture, onLostPointerCaptureCapture, onPointerCancel, onPointerCancelCapture, onPointerDown, onPointerDownCapture, onPointerMove, onPointerMoveCapture, onPointerOut, onPointerOutCapture, onPointerOver, onPointerOverCapture, onPointerUp, onPointerUpCapture, onMouseEnter, onMouseLeave, onPointerEnter, onPointerLeave, ...props }: Omit<ElementProps, \"onSelect\" | \"onClick\" | \"onClickCapture\"> & { onClick?: React.MouseEventHandler<HTMLElement>; onClickCapture?: React.MouseEventHandler<HTMLElement>; children?: React.ReactNode; label?: string; selectedValue?: string | null; defaultSelectedValue?: string | null; selectedCategoryValue?: string | null; defaultSelectedCategoryValue?: string | null; openCategories?: readonly string[]; defaultOpenCategories?: readonly string[]; open?: boolean; defaultOpen?: boolean; collapsed?: boolean; defaultCollapsed?: boolean; collapsible?: boolean; multiple?: boolean; density?: \"small\" | \"medium\" | \"large\"; tabbable?: boolean | \"true\" | \"false\"; openLabel?: string; closeLabel?: string; onItemSelect?: (value: string, href: string | null, label: string) => void; onCategoryToggle?: (value: string, open: boolean, openCategories: string[]) => void; onNavItemSelect?: (event: SharePointUIEvent, data: NavReactItemSelectData) => void; onNavCategoryItemToggle?: (event: SharePointUIEvent, data: NavReactCategoryToggleData) => void; onOpenChange?: (open: boolean) => void; onCollapsedChange?: (collapsed: boolean) => void }",
+        "reactSignature": "{ children, label = \"Navigation\", selectedValue, defaultSelectedValue, selectedCategoryValue, defaultSelectedCategoryValue, openCategories, defaultOpenCategories = [], open, defaultOpen, collapsed, defaultCollapsed, fullWidth = false, collapsible = false, multiple = true, density = \"medium\", openLabel, closeLabel, onItemSelect, onCategoryToggle, onNavItemSelect, onNavCategoryItemToggle, onOpenChange, onCollapsedChange, onClick, onClickCapture, onKeyDown, onKeyDownCapture, onKeyUp, onKeyUpCapture, onKeyPress, onKeyPressCapture, onFocus, onFocusCapture, onBlur, onBlurCapture, onAuxClick, onAuxClickCapture, onContextMenu, onContextMenuCapture, onDoubleClick, onDoubleClickCapture, onMouseDown, onMouseDownCapture, onMouseMove, onMouseMoveCapture, onMouseOut, onMouseOutCapture, onMouseOver, onMouseOverCapture, onMouseUp, onMouseUpCapture, onGotPointerCapture, onGotPointerCaptureCapture, onLostPointerCapture, onLostPointerCaptureCapture, onPointerCancel, onPointerCancelCapture, onPointerDown, onPointerDownCapture, onPointerMove, onPointerMoveCapture, onPointerOut, onPointerOutCapture, onPointerOver, onPointerOverCapture, onPointerUp, onPointerUpCapture, onMouseEnter, onMouseLeave, onPointerEnter, onPointerLeave, ...props }: Omit<ElementProps, \"onSelect\" | \"onClick\" | \"onClickCapture\"> & { onClick?: React.MouseEventHandler<HTMLElement>; onClickCapture?: React.MouseEventHandler<HTMLElement>; children?: React.ReactNode; label?: string; selectedValue?: string | null; defaultSelectedValue?: string | null; selectedCategoryValue?: string | null; defaultSelectedCategoryValue?: string | null; openCategories?: readonly string[]; defaultOpenCategories?: readonly string[]; open?: boolean; defaultOpen?: boolean; collapsed?: boolean; defaultCollapsed?: boolean; fullWidth?: boolean; collapsible?: boolean; multiple?: boolean; density?: \"small\" | \"medium\" | \"large\"; tabbable?: boolean | \"true\" | \"false\"; openLabel?: string; closeLabel?: string; onItemSelect?: (value: string, href: string | null, label: string) => void; onCategoryToggle?: (value: string, open: boolean, openCategories: string[]) => void; onNavItemSelect?: (event: SharePointUIEvent, data: NavReactItemSelectData) => void; onNavCategoryItemToggle?: (event: SharePointUIEvent, data: NavReactCategoryToggleData) => void; onOpenChange?: (open: boolean) => void; onCollapsedChange?: (collapsed: boolean) => void }",
         "callbackProps": [
           "onItemSelect",
           "onCategoryToggle",
@@ -5398,7 +5533,7 @@
           "host className/style",
           "named ::part hooks"
         ],
-        "reactSignature": "{ children, label, appearance, slot = \"navigation\", ...props }: ElementProps & { children?: React.ReactNode; label?: string; appearance?: \"brand\"; slot?: string }",
+        "reactSignature": "{ children, label, appearance, slot = \"navigation\", ...props }: ElementProps & { children?: React.ReactNode; label?: string; appearance?: \"brand\" | \"thumbnails\"; slot?: string }",
         "slots": [
           "navigation buttons"
         ],
@@ -5407,11 +5542,11 @@
       "react": "CarouselNav",
       "tag": "spui-carousel-nav",
       "define": "defineCarouselNav",
-      "signature": "{ children, label, appearance, ...props }: ElementProps & { children?: React.ReactNode; label?: string; appearance?: \"brand\" }",
+      "signature": "{ children, label, appearance, ...props }: ElementProps & { children?: React.ReactNode; label?: string; appearance?: \"brand\" | \"thumbnails\" }",
       "slots": [
         "navigation buttons"
       ],
-      "summary": "Group carousel position buttons with RTL-aware roving keyboard focus."
+      "summary": "Group carousel position buttons with RTL-aware roving keyboard focus; use the scrollable thumbnails appearance with image buttons for gallery navigation."
     },
     {
       "module": "carousel",
@@ -5422,7 +5557,8 @@
           "SharePointUIProvider tokens",
           "CSS custom properties",
           "host className/style",
-          "named ::part hooks"
+          "named ::part hooks",
+          "appearance: brand or thumbnails"
         ],
         "reactSignature": "{ children, index, label, selected = false, disabled = false, ...props }: ElementProps & { children?: React.ReactNode; index: number; label?: string; selected?: boolean; disabled?: boolean }",
         "slots": [
@@ -5806,8 +5942,12 @@
     }
   ],
   "agentContract": {
+    "composition": "Import named components from @spfx-fast/sharepoint-ui/react. Put one SharePointUIProvider around the view. Compose with children by default; use only the slots and component props listed for that component.",
     "reactProps": "Each component entry exposes its React parameter signature; callback props describe emitted value/state changes.",
+    "state": "State props, initial default props, callback names, and callback arguments vary by component. Follow that component's signature and callbackProps; update controlled state in its callback.",
     "slots": "Use the listed slots for content. Prefer ViewCard over custom markup for common SharePoint records.",
+    "customElements": "Import the component's define function from @spfx-fast/sharepoint-ui/elements/{module} and register it once. Set objects and callbacks as DOM properties. For event names and statically visible detail keys, use the source module's event inventory at https://vystartasv.github.io/sharepoint-ui/agents/events/{module}.json; it is module-scoped, so check event.target when composed tags emit events.",
+    "styling": "Theme, typography, locale, and direction inherit from SharePointUIProvider. Style the host with tokens, documented CSS variables, or ::part hooks; do not target shadow-DOM internals.",
     "localization": "Set lang and dir from the host language. SPFx uses pageContext.cultureInfo.currentUICultureName and isRightToLeft. Supply SharePointUIProvider strings for built-in control labels.",
     "theme": "Call applySharePointTheme at the SPFx web-part boundary; it forwards SharePoint palette, semantic colors, effects, spacing, font ramps, and default font styles as --spui-* variables. React can use SharePointUIProvider appearance and density (compact, comfortable, touch), theme.brandColor for derived accent/state roles, fluentTokens for raw Fluent variables, theme for typed semantic/design roles, and tokens for direct --spui-* overrides. Nested providers merge semantic groups and inherit density. Explicit theme roles override generated brand roles; direct tokens and element inline styles override these. Hex brand colors derive an AA-aware black-or-white on-accent foreground; set colors.accentForeground for other CSS color formats. CSS custom properties and ::part hooks remain public styling surfaces.",
     "persistence": "Keep SharePoint reads and writes in the web part or its service; controls expose values and do not persist data.",