@spfx-fast/sharepoint-ui 0.4.2 → 0.5.0

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.
-
-For a fast composition guide, read [choosing components](references/choosing-components.md). For theme, locale, RTL, forms, and persistence rules, read [SharePoint patterns](references/sharepoint-patterns.md).
-
-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 `lang` and `dir` on the provider. 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.