@spfx-fast/sharepoint-ui 0.4.3 → 0.5.0

package/dist/virtualizer-hooks.js

@@ -1,253 +0,0 @@
-import * as React from "react";
-function viewportLength(element, direction) {
-    if (element === element.ownerDocument.body)
-        return direction === "vertical" ? element.ownerDocument.defaultView?.innerHeight ?? 0 : element.ownerDocument.defaultView?.innerWidth ?? 0;
-    const rect = element.getBoundingClientRect();
-    return direction === "vertical" ? rect.height : rect.width;
-}
-/** Measure a fixed-size viewport and calculate a bounded item window. */
-export function useStaticVirtualizerMeasure(props) {
-    const { defaultItemSize, direction = "vertical", bufferItems: configuredBufferItems, bufferSize: configuredBufferSize } = props;
-    const [measurement, setMeasurement] = React.useState({ virtualizerLength: 0, bufferItems: 0, bufferSize: 0 });
-    const containerSizeRef = React.useRef(0);
-    const elementRef = React.useRef(null);
-    const update = React.useCallback((element = elementRef.current) => {
-        if (!element)
-            return;
-        const size = Math.max(0, viewportLength(element, direction));
-        containerSizeRef.current = size;
-        const visible = Math.ceil(size / Math.max(1, defaultItemSize) + 1);
-        const next = { virtualizerLength: visible + (configuredBufferItems ?? Math.max(Math.ceil(visible / 4), 1)) * 2, bufferItems: configuredBufferItems ?? Math.max(Math.ceil(visible / 4), 1), bufferSize: configuredBufferSize ?? Math.max(defaultItemSize / 2, 1) };
-        setMeasurement(previous => previous.virtualizerLength === next.virtualizerLength && previous.bufferItems === next.bufferItems && previous.bufferSize === next.bufferSize ? previous : next);
-    }, [direction, defaultItemSize, configuredBufferItems, configuredBufferSize]);
-    const observerRef = useResizeObserverRef_unstable(() => update());
-    const scrollRef = React.useCallback((element) => {
-        elementRef.current = element;
-        observerRef(element);
-        if (element)
-            update(element);
-    }, [observerRef, update]);
-    React.useEffect(() => {
-        const element = elementRef.current;
-        const win = element?.ownerDocument.defaultView;
-        if (!element || element !== element.ownerDocument.body || !win)
-            return;
-        const onResize = () => update();
-        win.addEventListener("resize", onResize, { passive: true });
-        return () => win.removeEventListener("resize", onResize);
-    }, [update]);
-    return { ...measurement, scrollRef, containerSizeRef };
-}
-/** Measure only enough variable-size rows to cover the current scroll viewport. */
-export function useDynamicVirtualizerMeasure(props) {
-    const { defaultItemSize, direction = "vertical", numItems, getItemSize, bufferItems: configuredBufferItems, bufferSize: configuredBufferSize, virtualizerContext } = props;
-    const [measurement, setMeasurement] = React.useState({ virtualizerLength: 0, bufferItems: 0, bufferSize: 0 });
-    const containerSizeRef = React.useRef(0);
-    const elementRef = React.useRef(null);
-    const positionRef = React.useRef(0);
-    const update = React.useCallback((element = elementRef.current) => {
-        if (!element)
-            return;
-        containerSizeRef.current = Math.max(0, viewportLength(element, direction));
-        const bufferSize = configuredBufferSize ?? Math.max(defaultItemSize / 2, 1);
-        const progressiveSizes = virtualizerContext.childProgressiveSizes.current;
-        let visible = 0;
-        let covered = 0;
-        let start = Math.max(0, Math.min(Math.floor(virtualizerContext.contextIndex), Math.max(0, numItems - 1)));
-        if (progressiveSizes.length >= numItems) {
-            let low = 0;
-            let high = numItems;
-            while (low < high) {
-                const middle = (low + high) >>> 1;
-                if (progressiveSizes[middle] <= positionRef.current)
-                    low = middle + 1;
-                else
-                    high = middle;
-            }
-            start = Math.min(Math.max(0, numItems - 1), low);
-        }
-        while (start + visible < numItems && covered < containerSizeRef.current + bufferSize * 2) {
-            const estimated = getItemSize(start + visible);
-            const size = Number.isFinite(estimated) && estimated > 0 ? estimated : defaultItemSize;
-            const end = progressiveSizes[start + visible];
-            const beginning = start + visible === 0 ? 0 : progressiveSizes[start + visible - 1];
-            const rowStart = Number.isFinite(end) ? beginning : (start + visible) * defaultItemSize;
-            const rowEnd = Number.isFinite(end) ? end : rowStart + size;
-            if (rowEnd > positionRef.current) {
-                covered += Math.max(0, Math.min(rowEnd, positionRef.current + containerSizeRef.current + bufferSize * 2) - Math.max(rowStart, positionRef.current));
-                visible++;
-            }
-            else
-                visible++;
-        }
-        const nextBufferItems = configuredBufferItems ?? Math.max(Math.ceil(visible / 3), 1);
-        const next = { virtualizerLength: Math.min(numItems, visible + nextBufferItems * 2), bufferItems: nextBufferItems, bufferSize };
-        if (virtualizerContext.contextIndex !== start)
-            virtualizerContext.setContextIndex(start);
-        setMeasurement(previous => previous.virtualizerLength === next.virtualizerLength && previous.bufferItems === next.bufferItems && previous.bufferSize === next.bufferSize ? previous : next);
-    }, [direction, defaultItemSize, numItems, getItemSize, configuredBufferItems, configuredBufferSize, virtualizerContext.contextIndex, virtualizerContext.childProgressiveSizes]);
-    const observerRef = useResizeObserverRef_unstable(() => update());
-    const scrollRef = React.useCallback((element) => { elementRef.current = element; observerRef(element); if (element)
-        update(element); }, [observerRef, update]);
-    const updateScrollPosition = React.useCallback((position) => { positionRef.current = Number.isFinite(position) ? Math.max(0, position) : 0; update(); }, [update]);
-    React.useLayoutEffect(() => { update(); }, [update]);
-    return { ...measurement, scrollRef, containerSizeRef, updateScrollPosition };
-}
-/** Track measured widths/heights by item index for legacy dynamic virtualizer composition. */
-export function useMeasureList(currentIndex, _refLength, totalLength, defaultItemSize) {
-    const widthArray = React.useRef(Array(Math.max(0, totalLength)).fill(defaultItemSize));
-    const heightArray = React.useRef(Array(Math.max(0, totalLength)).fill(defaultItemSize));
-    const refArray = React.useRef([]);
-    const [sizeUpdateCount, setSizeUpdateCount] = React.useState(0);
-    const observer = React.useRef(null);
-    const observerDocument = React.useRef(null);
-    const indexByElement = React.useRef(new WeakMap());
-    React.useEffect(() => {
-        const previousLength = widthArray.current.length;
-        widthArray.current.length = Math.max(0, totalLength);
-        heightArray.current.length = Math.max(0, totalLength);
-        for (let index = previousLength; index < widthArray.current.length; index++)
-            widthArray.current[index] = heightArray.current[index] = defaultItemSize;
-        refArray.current.length = Math.max(0, totalLength);
-    }, [defaultItemSize, totalLength]);
-    React.useEffect(() => () => observer.current?.disconnect(), []);
-    const measure = React.useCallback((element, index) => {
-        const rect = element.getBoundingClientRect();
-        const width = rect.width || defaultItemSize;
-        const height = rect.height || defaultItemSize;
-        if (widthArray.current[index] !== width || heightArray.current[index] !== height) {
-            widthArray.current[index] = width;
-            heightArray.current[index] = height;
-            setSizeUpdateCount(count => count + 1);
-        }
-    }, [defaultItemSize]);
-    const createIndexedRef = React.useCallback((index) => (element) => {
-        const absoluteIndex = Math.max(0, Math.floor(currentIndex + index));
-        const prior = refArray.current[absoluteIndex];
-        if (prior && prior !== element)
-            observer.current?.unobserve(prior);
-        refArray.current[absoluteIndex] = element;
-        if (!element)
-            return;
-        indexByElement.current.set(element, absoluteIndex);
-        element.handleResize = () => measure(element, absoluteIndex);
-        const ResizeObserverCtor = element.ownerDocument.defaultView?.ResizeObserver;
-        if (ResizeObserverCtor && (!observer.current || observerDocument.current !== element.ownerDocument)) {
-            observer.current?.disconnect();
-            const nextObserver = createResizeObserverFromDocument(element.ownerDocument, entries => entries.forEach(entry => {
-                const row = entry.target;
-                const rowIndex = indexByElement.current.get(row);
-                if (rowIndex !== undefined)
-                    measure(row, rowIndex);
-            }));
-            observer.current = nextObserver;
-            observerDocument.current = element.ownerDocument;
-        }
-        observer.current?.observe(element);
-        measure(element, absoluteIndex);
-    }, [currentIndex, measure]);
-    return { widthArray, heightArray, createIndexedRef, refArray, sizeUpdateCount };
-}
-/** Create an observer from the document's own window, including when an SPFx part is rendered in an iframe. */
-export function createResizeObserverFromDocument(targetDocument, callback) {
-    const Observer = targetDocument?.defaultView?.ResizeObserver;
-    return Observer ? new Observer(callback) : null;
-}
-/** Mirror a four-sided LTR observer margin for an RTL root. */
-export function getRTLRootMargin(ltrRootMargin, target, win) {
-    const element = target?.nodeType === 9 ? target.documentElement : target;
-    if (!element || !win || win.getComputedStyle(element).direction !== "rtl")
-        return ltrRootMargin;
-    const margins = ltrRootMargin.trim().split(/\s+/);
-    return margins.length === 4 ? `${margins[0]} ${margins[3]} ${margins[2]} ${margins[1]}` : ltrRootMargin;
-}
-/** Observe a changing element list with native IntersectionObserver and direction-aware margins. */
-export function useIntersectionObserver(callback, options) {
-    const [elements, setElements] = React.useState();
-    const [init, setInit] = React.useState(options);
-    const observer = React.useRef(undefined);
-    const callbackRef = React.useRef(callback);
-    const [directionRevision, setDirectionRevision] = React.useState(0);
-    callbackRef.current = callback;
-    const setObserverInit = React.useCallback((next) => setInit(next), []);
-    React.useEffect(() => {
-        const root = init?.root;
-        const doc = root?.ownerDocument ?? (typeof document === "undefined" ? undefined : document);
-        const MutationObserverCtor = doc?.defaultView?.MutationObserver;
-        if (!MutationObserverCtor || !root)
-            return;
-        const mutationObserver = new MutationObserverCtor(records => {
-            if (records.some(record => record.attributeName === "dir"))
-                setDirectionRevision(revision => revision + 1);
-        });
-        mutationObserver.observe(doc.documentElement, { attributes: true, subtree: true, attributeFilter: ["dir"] });
-        return () => mutationObserver.disconnect();
-    }, [init?.root]);
-    React.useEffect(() => {
-        const root = init?.root;
-        const doc = (root?.nodeType === 1 ? root.ownerDocument : typeof document === "undefined" ? undefined : document);
-        const win = doc?.defaultView;
-        if (!win?.IntersectionObserver)
-            return;
-        const rootMargin = getRTLRootMargin(init?.rootMargin ?? "0px", init?.root, win);
-        const instance = new win.IntersectionObserver((entries, current) => callbackRef.current(entries, current), { ...init, rootMargin });
-        observer.current = instance;
-        elements?.forEach(element => instance.observe(element));
-        return () => {
-            instance.disconnect();
-            if (observer.current === instance)
-                observer.current = undefined;
-        };
-    }, [elements, init, directionRevision]);
-    return { setObserverList: setElements, setObserverInit, observer };
-}
-/** Attach a resize observer callback ref; it is safe when ResizeObserver is unavailable. */
-export function useResizeObserverRef_unstable(resizeCallback) {
-    const callbackRef = React.useRef(resizeCallback);
-    callbackRef.current = resizeCallback;
-    const observed = React.useRef(null);
-    React.useEffect(() => () => { observed.current?.observer.disconnect(); observed.current = null; }, []);
-    return React.useCallback(instance => {
-        const current = observed.current;
-        if (current?.element === instance)
-            return;
-        current?.observer.disconnect();
-        observed.current = null;
-        const Observer = instance?.ownerDocument.defaultView?.ResizeObserver;
-        if (!instance || !Observer)
-            return;
-        const target = { current: instance };
-        const observer = new Observer((entries, currentObserver) => callbackRef.current(entries, currentObserver, target));
-        observed.current = { element: instance, observer };
-        observer.observe(instance);
-    }, []);
-}
-/** Scroll an element to a fixed-size virtual item. */
-export function scrollToItemStatic({ index, itemSize, totalItems, scrollViewRef, axis = "vertical", reversed = false, behavior = "auto" }) {
-    const view = scrollViewRef.current;
-    if (!view || !Number.isFinite(index) || !Number.isFinite(itemSize) || itemSize <= 0 || totalItems <= 0)
-        return;
-    const safeIndex = Math.max(0, Math.min(totalItems - 1, Math.floor(index)));
-    const offset = reversed ? Math.max(0, totalItems * itemSize - itemSize * (safeIndex + 1)) : safeIndex * itemSize;
-    if (axis === "horizontal")
-        view.scrollTo({ left: offset, behavior });
-    else
-        view.scrollTo({ top: offset, behavior });
-}
-/** Scroll an element to a measured item; summing the prefix is O(index), so keep the measured list modest. */
-export function scrollToItemDynamic({ index, itemSizes, totalSize, scrollViewRef, axis = "vertical", reversed = false, behavior = "auto" }) {
-    const view = scrollViewRef.current;
-    const sizes = itemSizes.current;
-    if (!view || !sizes || !Number.isFinite(index) || !sizes.length)
-        return;
-    const safeIndex = Math.max(0, Math.min(sizes.length - 1, Math.floor(index)));
-    let offset = 0;
-    for (let item = 0; item < safeIndex; item++)
-        offset += Number.isFinite(sizes[item]) ? Math.max(0, sizes[item]) : 0;
-    if (reversed)
-        offset = Math.max(0, totalSize - offset - (Number.isFinite(sizes[safeIndex]) ? Math.max(0, sizes[safeIndex]) : 0));
-    if (axis === "horizontal")
-        view.scrollTo({ left: offset, behavior });
-    else
-        view.scrollTo({ top: offset, behavior });
-}

package/scripts/generate-token-index.mjs

@@ -1,43 +0,0 @@
-import { readdir, readFile, writeFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-
-const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const sourceDir = resolve(packageDir, "src");
-const outputPath = resolve(packageDir, "tokens.json");
-const checkOnly = process.argv.includes("--check");
-const components = new Map();
-const declarations = new Map();
-const addTokens = (map, source, text) => {
-  for (const token of text.match(/--spui-[\w-]+/g) ?? []) {
-    if (token === "--spui-palette-") continue;
-    const sources = map.get(token) ?? new Set();
-    sources.add(source);
-    map.set(token, sources);
-  }
-};
-
-for (const file of (await readdir(resolve(sourceDir, "elements"))).filter(name => name.endsWith(".ts")).sort()) {
-  addTokens(components, file.slice(0, -3), await readFile(resolve(sourceDir, "elements", file), "utf8"));
-}
-for (const file of ["appearance.ts", "theme.ts"]) {
-  addTokens(declarations, file.slice(0, -3), await readFile(resolve(sourceDir, file), "utf8"));
-}
-
-const tokens = [...new Set([...components.keys(), ...declarations.keys()])].sort().map(name => ({
-  name,
-  components: [...(components.get(name) ?? [])].sort(),
-  declaredBy: [...(declarations.get(name) ?? [])].sort()
-}));
-const dynamicPrefixes = [{ prefix: "--spui-palette-", declaredBy: ["theme"] }];
-const content = `${JSON.stringify({ generatedFrom: "src/elements/*.ts, src/appearance.ts, src/theme.ts", dynamicPrefixes, tokens }, null, 2)}\n`;
-if (checkOnly) {
-  const current = await readFile(outputPath, "utf8").catch(() => "");
-  if (current !== content) {
-    console.error("Token index is stale. Run npm run tokens:generate --workspace @spfx-fast/sharepoint-ui.");
-    process.exitCode = 1;
-  } else console.log(`Token index is current (${tokens.length} tokens).`);
-} else {
-  await writeFile(outputPath, content);
-  console.log(`Wrote ${tokens.length} component token entries to ${outputPath}.`);
-}

package/scripts/sync-component-catalog-signatures.mjs

@@ -1,55 +0,0 @@
-import { readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import ts from "typescript";
-
-const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const catalogPath = resolve(pkgDir, "components.json");
-const adapterPath = resolve(pkgDir, "src/react.tsx");
-const catalog = JSON.parse(await readFile(catalogPath, "utf8"));
-const adapterText = await readFile(adapterPath, "utf8");
-const source = ts.createSourceFile(adapterPath, adapterText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-const components = new Map();
-
-function collect(node) {
-  if (ts.isFunctionDeclaration(node) && node.name && node.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
-    components.set(node.name.text, node);
-  }
-  if (ts.isVariableStatement(node) && node.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
-    for (const declaration of node.declarationList.declarations) {
-      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
-      function findNamedFunction(candidate) {
-        if (ts.isFunctionExpression(candidate) && candidate.name?.text === declaration.name.text) return candidate;
-        let found;
-        ts.forEachChild(candidate, child => { found ??= findNamedFunction(child); });
-        return found;
-      }
-      const component = findNamedFunction(declaration.initializer);
-      if (component) components.set(declaration.name.text, component);
-    }
-  }
-  ts.forEachChild(node, collect);
-}
-
-collect(source);
-const changed = [];
-for (const entry of catalog.components) {
-  const component = components.get(entry.react);
-  const parameter = component?.parameters[0];
-  if (!parameter) throw new Error(`Cannot find first React parameter for ${entry.react}`);
-  const signature = parameter.getText(source);
-  if (entry.api.reactSignature !== signature) {
-    changed.push(entry.react);
-    entry.api.reactSignature = signature;
-  }
-}
-
-if (process.argv.includes("--check")) {
-  if (changed.length) {
-    console.error(`Catalog React signatures are stale: ${changed.join(", ")}`);
-    process.exitCode = 1;
-  } else console.log(`React signatures match all ${catalog.components.length} adapters.`);
-} else if (changed.length) {
-  await writeFile(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);
-  console.log(`Updated ${changed.length} React signatures: ${changed.join(", ")}`);
-} else console.log(`React signatures already match all ${catalog.components.length} adapters.`);

package/scripts/validate-component-catalog.mjs

@@ -1,44 +0,0 @@
-import { access, readFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-
-const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const catalog = JSON.parse(await readFile(resolve(pkgDir, "components.json"), "utf8"));
-const built = await access(resolve(pkgDir, "src/react.tsx")).then(() => false).catch(() => true);
-const sourceDir = resolve(pkgDir, built ? "dist" : "src");
-const adapter = await readFile(resolve(sourceDir, built ? "react.d.ts" : "react.tsx"), "utf8");
-const barrel = await readFile(resolve(sourceDir, built ? "index.d.ts" : "index.ts"), "utf8");
-const errors = [];
-
-for (const component of catalog.components) {
-  if (typeof component.summary !== "string" || !component.summary.trim()) errors.push(`${component.react}: missing human-readable component summary`);
-  if (!component.api?.reactSignature || !Array.isArray(component.api.slots) || !Array.isArray(component.api.callbackProps)) errors.push(`${component.react}: missing agent API signature, slots, or callback props`);
-  const exportName = component.define ?? component.factory;
-  if (!component.reactOnly && !exportName) errors.push(`${component.react}: missing custom-element definition or native-element factory`);
-  const signature = component.api.reactRefType
-    ? (() => {
-      const declaration = new RegExp(`export const ${component.react} = (?:/\\* @__PURE__ \\*/ )?React\\.forwardRef<${component.api.reactRefType},`);
-      const declarationIndex = adapter.search(declaration);
-      const generic = component.api.generic ? `<${component.api.generic}>` : "";
-      const forwardedRef = component.api.forwardRefParameterType ? `forwardedRef: ${component.api.forwardRefParameterType}` : "forwardedRef";
-      const functionSignature = `function ${component.react}${generic}(${component.api.reactSignature}, ${forwardedRef})`;
-      return declarationIndex >= 0 && adapter.indexOf(functionSignature, declarationIndex) >= declarationIndex;
-    })()
-    : adapter.includes(`export function ${component.react}${component.api.generic ? `<${component.api.generic}>` : ""}(${component.api.reactSignature})`);
-  if (!signature) errors.push(`${component.react}: catalog API signature is stale`);
-  if (!new RegExp(`\\b${component.react}\\b`).test(adapter)) errors.push(`${component.react}: missing React adapter export`);
-  for (const helper of component.api.reactHelpers ?? []) {
-    if (!new RegExp(`\\bexport\\s+(?:const|function|type|interface)\\s+${helper}\\b`).test(adapter)) errors.push(`${component.react}: missing catalogued React helper ${helper}`);
-  }
-  if (component.reactOnly) continue;
-  const source = await readFile(resolve(sourceDir, `elements/${component.module}.${built ? "js" : "ts"}`), "utf8").catch(() => null);
-  if (!source) { errors.push(`${component.tag}: missing source module ${component.module}`); continue; }
-  const literalRegistration = new RegExp(`customElements\\.define\\(["']${component.tag}["']`).test(source);
-  const sharedFactoryRegistration = source.includes(`"${component.tag}"`) && /customElements\.define\(tag,/.test(source);
-  const partRegistration = component.tag.startsWith("spui-teaching-popover-") && source.includes(`partTag("${component.tag.slice("spui-teaching-popover-".length)}")`) && /function definePart\(/.test(source) && /customElements\.define\(tag,/.test(source);
-  if (component.registered !== false && !literalRegistration && !sharedFactoryRegistration && !partRegistration && !(source.includes(`"${component.tag}"`) && /customElements\.define\(name/.test(source))) errors.push(`${component.tag}: missing custom-element definition`);
-  if (exportName && !new RegExp(`\\b${exportName}\\b`).test(barrel)) errors.push(`${exportName}: missing public element/factory export`);
-}
-if (!catalog.frameworkCompatibility?.spfx || catalog.components.length === 0) errors.push("Catalog requires SPFx compatibility and components.");
-if (errors.length) { console.error(`Catalog check failed:\n- ${errors.join("\n- ")}`); process.exitCode = 1; }
-else console.log(`Validated ${catalog.components.length} component entries against React adapters and custom-element exports.`);

package/skills/sharepoint-ui/SKILL.md

@@ -1,12 +0,0 @@
----
-name: sharepoint-ui
-description: Build or change accessible, theme-aware SharePoint Framework interfaces with @spfx-fast/sharepoint-ui. Use when an SPFx web part needs reusable controls, SharePoint-style cards, tokens, RTL, custom elements, or rich text saved through SharePoint.
----
-
-# SharePoint UI component skill
-
-Use the package manifest at `../../components.json` to find exact React names, custom-element tags, and leaf entry points. The source repository checks it with `npm run catalog:check --workspace @spfx-fast/sharepoint-ui`. Use the package's TypeScript declarations as the final API authority. Do not infer that an unlisted Fluent v9 component exists; the library is still growing toward parity.
-
-Start with [`QUICKSTART.md`](../../QUICKSTART.md) for the shared composition contract and copy-ready examples. Use [choosing components](references/choosing-components.md) to select controls and [SharePoint patterns](references/sharepoint-patterns.md) for locale, RTL, forms, and persistence.
-
-Prefer leaf imports. Keep SharePoint permissions, data fetching, and writes in an SPFx service. Controls emit state; they do not save records implicitly. Validate keyboard use, theme contrast on the target surface, and RTL when relevant.

package/skills/sharepoint-ui/references/choosing-components.md

@@ -1,20 +0,0 @@
-# Choosing components
-
-- Actions: `Button`.
-- People and entities: `Avatar` with a name and optional image; use theme-derived `color="colorful"` for stable initials colors.
-- Repeated SharePoint records: `ViewCard` for document, person, task, approval, or list-item content; compose details through slots.
-- Filter and selected-value chips: use `Tag` inside a labelled `TagGroup`; set `dismissible` and update the backing array in `onDismiss`.
-- Searchable multi-select values: use `TagPicker` with `TagPickerOption` children, stable values, and a controlled `selectedValues` array.
-- User-provided scores: use `Rating` with a visible label and controlled `value`; set `step={0.5}` when half-star scores are useful.
-- Short text and multiline text: `TextField` and `TextArea`.
-- Typography and semantic labels: `Text` for heading/body/emphasis styles, and `Label` for form-control labels. Non-React code can use `spui-text` with `defineText()`; use the `createLabel()` factory when native `for` association is needed.
-- Fixed choices: `Select` or `RadioGroup`.
-- Searchable choices: `ComboBox` and `ComboOption`.
-- Numeric/date/range values: `SpinButton`, `DatePicker`, and `Slider`.
-- Rich formatted notes: `RichTextEditor`; it is a lightweight SharePoint-oriented editor, not a collaborative document surface.
-- Navigation and disclosure: `Link` for URLs, `Divider` to separate content groups, and `Accordion` with `AccordionItem` for progressive disclosure. Prefer an explicit link name and preserve native anchor behavior.
-- Persistent feedback: `Alert` for live status/urgent information; `MessageBar` for page-level notices. Use `Skeleton` for loading placeholders, and `Badge`, `Spinner`, or `ProgressBar` for compact status/progress.
-- Brief feedback: mount one `Toaster` near the app root and call `dispatchToast` from `useToastController()`. Use persistent `Alert`/`MessageBar` content as well when the user must be able to return to the information later.
-- Confirmation: `Dialog`.
-
-Import React adapters from `@spfx-fast/sharepoint-ui/react`. For non-React use, import the matching leaf module, call its `define*()` function once, and use the tag from `components.json`; `Label` is the exception because its factory returns a native `<label>`. Check the source catalog before substituting a native element for a missing library family.

package/skills/sharepoint-ui/references/sharepoint-patterns.md

@@ -1,17 +0,0 @@
-# SharePoint patterns
-
-## Theme and layout
-
-Wrap a React surface in `SharePointUIProvider` and pass the SharePoint `ThemeProvider` values through `applySharePointTheme()` at the web-part boundary. Set the provider `lang`; it derives `dir` from the BCP 47 language tag. Set `dir` explicitly only to override that direction. Use tokens and CSS parts to customize; avoid copying a component's internal markup. Glass derives its values from the selected SharePoint/base appearance.
-
-## Forms and events
-
-Give every field a visible label. Use controlled values when the surrounding form owns state and wire the component's `onValueChange`/`onCheckedChange` callback. Native form behavior is used where possible; custom elements use `ElementInternals` where supported. Verify browser form reset and disabled behavior for the exact field before depending on it.
-
-## SharePoint persistence
-
-Use SPFx `SPHttpClient` or the project's existing data service for SharePoint requests. Show loading, success, and error states. Read important writes back and compare the saved result. `RichTextEditor` returns allowlist-normalized HTML; never render arbitrary saved HTML with unsanitized `innerHTML`.
-
-## Agent handoff
-
-State which controls were selected and why, list data fields and write locations, theme/locale assumptions, and the keyboard or tenant checks performed. Treat browser timing, host heap, and page long tasks as host-inclusive unless measured in isolation.