@spfx-fast/sharepoint-ui 0.4.3 → 0.5.0

package/QUICKSTART.md

@@ -1,133 +1,18 @@
-# SharePoint UI quickstart
+# Quick start
 
-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.
+Import components from `@spfx-fast/sharepoint-ui/react`, the stylesheet once, and wrap the app in `SharePointThemeProvider`.
 
 ```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>
-  </>;
-}
+import { Button, Card, Checkbox, Field, Input, SharePointThemeProvider } from "@spfx-fast/sharepoint-ui/react";
+import "@spfx-fast/sharepoint-ui/styles.css";
+
+<SharePointThemeProvider>
+  <Card>
+    <Field id="person-name" label="Name" required><Input name="name" required /></Field>
+    <label><Checkbox name="remember" /> Remember me</label>
+    <Button>Save</Button>
+  </Card>
+</SharePointThemeProvider>
 ```
 
-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.
+Use role and accessible name locators such as `getByRole("textbox", { name: "Name" })`. Add `data-agent-id` when the page has duplicate names.

package/README.md

@@ -1,41 +1,34 @@
 # @spfx-fast/sharepoint-ui
 
-Theme-aware UI components for SharePoint Framework 1.24. React 18.3.1+ is optional; custom elements work without React.
-
-## Install
+Small themeable React components for SharePoint Framework. Uses native HTML and a compact semantic theme token set.
 
 ```sh
 npm install @spfx-fast/sharepoint-ui
 ```
 
-## React
-
-```tsx
-import { SharePointUIProvider, Button, TextField } from "@spfx-fast/sharepoint-ui/react";
-
-export function Example() {
-  return <SharePointUIProvider lang="en-GB">
-    <TextField label="Work item" />
-    <Button appearance="primary">Save</Button>
-  </SharePointUIProvider>;
-}
-```
+React 18.3.1 is a peer dependency supplied by the SharePoint Framework host.
 
-## Custom elements
+## Usage
 
-```js
-import { defineButton } from "@spfx-fast/sharepoint-ui/elements/button";
-defineButton();
+```tsx
+import { Button, Card, Checkbox, Input, SharePointThemeProvider } from "@spfx-fast/sharepoint-ui/react";
+import "@spfx-fast/sharepoint-ui/styles.css";
+
+<SharePointThemeProvider>
+  <Card>
+    <Input aria-label="Search" placeholder="Search" />
+    <label><Checkbox name="includeArchived" /> Include archived</label>
+    <Button>Search</Button>
+  </Card>
+</SharePointThemeProvider>
 ```
 
-```html
-<spui-button appearance="primary">Save</spui-button>
-```
+The provider reads the SharePoint theme CSS variables from its host page. Override tokens with `theme` or ordinary CSS custom properties to customize the result.
 
-**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/)
+## SharePoint list workflows
 
-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.
+Use `FilterBar` with `ListView` for labelled search and filters, empty/loading states, and paging. Add `ViewSwitcher` when users can choose between list and card layouts. These components keep query and paging state in the host app.
 
-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.
+Use `FileDropzone` to collect selected or dropped files and `AttachmentList` to show upload status and remove actions. Upload files through the host's SPFx service; validate files on the host before saving.
 
-[MIT License](./LICENSE)
+Each control exposes native roles and visible labels. For browser agents, locate controls by role and accessible name first, then use `data-agent-id` only when names are duplicated. See the [agent interaction guide](https://vystartasv.github.io/sharepoint-ui/agents/) for locator and verification examples.