@webority/ui-react 0.88.1 → 0.89.0

package/dist/types/components/AppTour.d.ts

@@ -1,12 +1,15 @@
 import "@webority/ui-elements/elements/tour";
 declare const AppTour: import("react").ForwardRefExoticComponent<{
+    /** Runs the tour. Set it back to false from onClose. */
     open: boolean;
     onClose: (reason: 'finished' | 'skipped' | 'alreadySeen' | 'noTargets', details: {
         index: number | null;
         position: number | null;
         total: number | null;
     }) => void;
+    /** Names the tour in the seen store. */
     tourId: string;
+    /** The steps, in order. A step whose target is missing or hidden is dropped. */
     steps: {
         target: string;
         title?: string;
@@ -18,11 +21,13 @@ declare const AppTour: import("react").ForwardRefExoticComponent<{
         advanceOn?: 'click';
         actionLabel?: string;
     }[];
+    /** Remembers that a person has seen the tour: it is asked before showing and written when the tour finishes or is skipped, with that outcome. Read through a ref, so an inline object does not restart a running tour. */
     seenStore?: {
         isSeen: (tourId: string) => Promise<boolean>;
         markSeen: (tourId: string, outcome: 'finished' | 'skipped') => Promise<void>;
     };
     onBeforeStep?: (step: object, index: number) => void | Promise<void>;
+    /** Button text, defaults Back, Next, Skip, Done. `done` is the last step's button only with `endDialog` false; while the closing dialog is on, the last step reads `next`, because the dialog follows. */
     labels?: {
         back?: string;
         next?: string;
@@ -36,7 +41,12 @@ declare const AppTour: import("react").ForwardRefExoticComponent<{
         endMessage?: string;
         endButton?: string;
     };
+    /**
+     * Show the closing dialog after the last step.
+     * @default true
+     */
     endDialog?: boolean;
+    /** Extra class names on the tour element. */
     className?: string;
 } & import("react").RefAttributes<any>>;
 export default AppTour;

package/dist/types/components/AppTreeView.d.ts

@@ -1,5 +1,6 @@
 import "@webority/ui-elements/elements/tree";
 declare const AppTreeView: import("react").ForwardRefExoticComponent<{
+    /** The hierarchy to show. Ids are strings, unique across the whole tree. `children: []` is a leaf; `hasChildren: true` with no `children` is a node whose children are fetched the first time it opens. */
     nodes: {
         id: string;
         label: string;
@@ -12,22 +13,44 @@ declare const AppTreeView: import("react").ForwardRefExoticComponent<{
         checked?: boolean;
         disabled?: boolean;
     }[];
+    /**
+     * How rows are chosen: none, single (one selected row) or multiple (a tri-state checkbox per node).
+     * @default "none"
+     */
     selection?: 'none' | 'single' | 'multiple';
+    /** Selected id (single mode, controlled). The tree shows this id whatever the user clicks until you change it; null selects nothing, and dropping the prop clears it. */
     selected?: string | null;
     onSelect?: (id: string, node: object) => void;
+    /** Checked ids (multiple mode, controlled). */
     checked?: string[];
     onCheck?: (ids: string[], detail: {
         id: string;
         checked: boolean;
     }) => void;
     loadChildren?: (node: object) => Promise<object[]>;
+    /** Children endpoint used when loadChildren is not set: a GET with parentId=<id> added, answering a JSON array of nodes. */
     loadUrl?: string;
     onLoadError?: (id: string, message: string) => void;
+    /** Form field name: multiple posts one value per checked id, single posts the selected id. */
     name?: string;
+    /**
+     * Announced while children load.
+     * @default "Loading"
+     */
     loadingText?: string;
+    /**
+     * Announced when they fail.
+     * @default "Could not load. Try again."
+     */
     errorText?: string;
+    /** Accessible name of the tree. */
     ariaLabel?: string;
+    /** The id of the tree element. */
     id?: string;
+    /**
+     * Extra class names on the tree.
+     * @default ""
+     */
     className?: string;
 } & import("react").RefAttributes<HTMLElement>>;
 export default AppTreeView;

package/dist/types/components/AppTruncate.d.ts

@@ -7,15 +7,24 @@ import "@webority/ui-elements/elements/truncate";
  *
  * @param {object} props
  * @param {import('react').ReactNode} props.children The text.
- * @param {number} [props.lines=1] How many lines show before the cut; 1 is a single line cut by width.
- * @param {string} [props.width] A CSS length the text never exceeds ("12rem", "240px"); without it the text takes the width it is given.
+ * @param {number} [props.lines]
+ * @param {string} [props.width]
  * @param {import('react').CSSProperties} [props.style]
  * @param {string} [props.className]
  */
 export default function AppTruncate(props: {
     children: import('react').ReactNode;
+    /**
+     * How many lines show before the cut. 1 is a single line cut by width.
+     * @default 1
+     */
     lines?: number;
+    /** A CSS length the text never exceeds, such as 12rem or 240px. Without it the text takes the width it is given. */
     width?: string;
     style?: import('react').CSSProperties;
+    /**
+     * Extra classes on the element.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

package/dist/types/components/AppUpdateBar.d.ts

@@ -8,13 +8,21 @@
  *
  * @param {object} props
  * @param {() => void} [props.onReload] What "Reload" does. Default: reload the page.
- * @param {boolean} [props.dismissible=false] Show a close button. The bar then stays closed until it remounts.
+ * @param {boolean} [props.dismissible]
  * @param {() => void} [props.onDismiss] Called after the bar is closed.
- * @param {string} [props.className] Extra classes, such as `sticky-top`.
+ * @param {string} [props.className]
  */
 export default function AppUpdateBar(props: {
     onReload?: () => void;
+    /**
+     * Shows a close button. The bar then stays closed until it remounts.
+     * @default false
+     */
     dismissible?: boolean;
     onDismiss?: () => void;
+    /**
+     * Extra classes on the bar, such as sticky-top to keep it in view.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

package/dist/types/components/AppWhatsNew.d.ts

@@ -14,17 +14,19 @@ import "@webority/ui-elements/elements/whats-new";
  *
  * @param {object} props
  * @param {{ id?: string, date: string, title: string, body?: string, imageSrc?: string,
- *   imageAlt?: string, href?: string, linkLabel?: string }[]} [props.entries] The release notes.
- *   `date` is the day it shipped, "YYYY-MM-DD", shown as DD-MMM-YYYY. `imageAlt` describes the
- *   picture; leave it empty when the picture adds nothing. `linkLabel` defaults to "Learn more".
- * @param {string} [props.storageKey] Names where read state is kept; include the user's id.
- * @param {string} [props.label="What's new"] The trigger's name and the panel's heading.
- * @param {string} [props.unreadLabel="unread"] Added to the trigger's name while there are unread entries.
- * @param {string} [props.emptyText="Nothing new yet"] Shown when there are no entries.
+ *   imageAlt?: string, href?: string, linkLabel?: string }[]} [props.entries]
+ * @param {string} [props.storageKey]
+ * @param {string} [props.label]
+ * @param {string} [props.unreadLabel]
+ * @param {string} [props.emptyText]
  * @param {(through: string) => void} [props.onRead] Called with the newest entry's date when opening marks entries read.
  * @param {string} [props.className]
  */
 export default function AppWhatsNew(props: {
+    /**
+     * The release notes, shown in the order passed.
+     * @default []
+     */
     entries?: {
         id?: string;
         date: string;
@@ -35,10 +37,27 @@ export default function AppWhatsNew(props: {
         href?: string;
         linkLabel?: string;
     }[];
+    /** Names where read state is kept. Include the user's id. */
     storageKey?: string;
+    /**
+     * The trigger's name and the panel's heading.
+     * @default "What's new"
+     */
     label?: string;
+    /**
+     * Added to the trigger's name while there are unread entries.
+     * @default "unread"
+     */
     unreadLabel?: string;
+    /**
+     * Shown when there are no entries.
+     * @default "Nothing new yet"
+     */
     emptyText?: string;
     onRead?: (through: string) => void;
+    /**
+     * Extra classes on the element.
+     * @default ""
+     */
     className?: string;
 }): import("react").JSX.Element;

package/dist/types/components/AppWizard.d.ts

@@ -1,5 +1,6 @@
 import "@webority/ui-elements/elements/wizard";
 declare const AppWizard: import("react").ForwardRefExoticComponent<{
+    /** One entry per step, in step order. A list that is not an array of objects with a text label is refused with a thrown error, and an unknown field warns in development. */
     steps: {
         key?: string;
         label: string;
@@ -9,7 +10,12 @@ declare const AppWizard: import("react").ForwardRefExoticComponent<{
         status?: 'done' | 'active' | 'pending' | 'error';
     }[];
     children: import('react').ReactNode;
+    /** The current step's index when the wizard is controlled, used together with onStepChange. */
     active?: number;
+    /**
+     * The step the wizard starts on when it is not controlled.
+     * @default 0
+     */
     defaultActive?: number;
     onStepChange?: (index: number, detail: {
         previous: number;
@@ -21,30 +27,103 @@ declare const AppWizard: import("react").ForwardRefExoticComponent<{
     onSkip?: (index: number) => void;
     beforeNext?: (index: number) => boolean | Promise<boolean>;
     onInvalid?: (index: number) => void;
+    /**
+     * The stepper header style: compact circles, the wide journey bar, large connected icon badges with a STEP n eyebrow, or a row of tiles with an icon square, a label and a Done, Current or To do line.
+     * @default "steps"
+     */
     variant?: 'steps' | 'journey' | 'icons' | 'tiles';
+    /** Recolours the whole stepper accent (active fill, done rail, ring, done tint) to a semantic ramp. Unset keeps the variant's default: primary for steps and journey, success for icons. */
     tone?: 'primary' | 'success' | 'warning' | 'danger' | 'info';
+    /** Recolours completed steps only (their badge, STEP n eyebrow and the filled line after them). The current step keeps the tone accent; unset, completed steps follow tone. */
     doneTone?: 'primary' | 'success' | 'warning' | 'danger' | 'info';
+    /**
+     * Lays the stepper out as a row or as a column.
+     * @default "horizontal"
+     */
     orientation?: 'horizontal' | 'vertical';
+    /**
+     * Where each step's badge, label and description sit in its column on a horizontal stepper: centred, or at the start with the line running from badge to badge. It applies to the steps and icons variants.
+     * @default "center"
+     */
     align?: 'center' | 'start';
+    /** The iconsax style of every header glyph: the done tick, the error alert, the skipped dash and each step's own icon. Unset draws the linear style. */
     iconVariant?: 'linear' | 'outline' | 'bold' | 'bulk' | 'broken' | 'twotone';
+    /**
+     * Scales the stepper header: the badge, its number, the labels and the glyphs.
+     * @default "md"
+     */
     size?: 'sm' | 'md' | 'lg';
+    /** Every header glyph's width and height in px. Unset, it follows size (14, 16 or 20). */
     iconSize?: number;
+    /**
+     * Shows a Skip button on every step but the last, without needing optional on each step.
+     * @default false
+     */
     skippable?: boolean;
+    /**
+     * Allows jumping to any step, not only completed ones.
+     * @default false
+     */
     nonLinear?: boolean;
+    /**
+     * Hides the progress header.
+     * @default false
+     */
     hideStepper?: boolean;
+    /**
+     * Drops the line joining the steps, on every variant and orientation. Lines show by default.
+     * @default false
+     */
     hideConnectors?: boolean;
+    /**
+     * Disables all navigation.
+     * @default false
+     */
     disabled?: boolean;
+    /**
+     * The accessible name of the stepper.
+     * @default "Progress"
+     */
     label?: string;
+    /**
+     * The text of the Back button.
+     * @default "Back"
+     */
     backLabel?: string;
+    /**
+     * The text of the Next button.
+     * @default "Next"
+     */
     nextLabel?: string;
+    /**
+     * The text of the Skip button.
+     * @default "Skip"
+     */
     skipLabel?: string;
+    /**
+     * The text of the Finish button on the last step.
+     * @default "Finish"
+     */
     finishLabel?: string;
+    /**
+     * Shows a 56px bar above the stepper with barTitle, Step N of M and a close button.
+     * @default false
+     */
     topBar?: boolean;
+    /** The title at the start of the top bar. */
     barTitle?: string;
+    /**
+     * The accessible name of the top bar's close button.
+     * @default "Close"
+     */
     closeLabel?: string;
     onClose?: (detail: {
         index: number;
     }) => void;
+    /**
+     * Extra classes on the wizard.
+     * @default ""
+     */
     className?: string;
 } & import("react").RefAttributes<any>>;
 export default AppWizard;

package/dist/types/components/AppWorkspaceSwitcher.d.ts

@@ -15,49 +15,68 @@
  *
  * @param {object} props
  * @param {{ id: string, name: string, logoUrl?: string, badge?: string }[]} [props.tenants]
- *   The switchable workspaces. Razor composes the same list from `<app-workspace-option>` children.
- * @param {string} [props.currentId] Id of the active workspace — drives the trigger and the tick.
+ * @param {string} [props.currentId]
  * @param {(tenant: object) => void} [props.onSelect] Fired with the chosen tenant. No navigation.
- * @param {string} [props.menuLabel] Optional header label above the list ("Workspaces").
+ * @param {string} [props.menuLabel]
  * @param {import('react').ReactNode | { label: string, icon?: string, href?: string }} [props.footerAction]
- *   A pinned row under the list — a node rendered as-is, or a descriptor the library renders
- *   as a menu row (through `linkComponent` when it carries an `href`).
  * @param {import('react').ElementType} [props.linkComponent] Component for `href` rows (e.g. Link).
- * @param {boolean} [props.searchable=false] Client-side filter over the list. Only earns its
- *   place past roughly eight workspaces.
+ * @param {boolean} [props.searchable]
  * @param {() => void} [props.onCreate] Fired by the create row.
- * @param {boolean} [props.canCreate=false] Renders the create row. Hidden by default because
- *   most members cannot create a workspace.
- * @param {string} [props.createLabel="Create workspace"] Copy for the create row.
- * @param {boolean} [props.compact=false] Renders the 36px monogram button instead of the full
- *   card — the shape a collapsed rail slot wants. Same menu either way.
- * @param {"sm"|"md"|"lg"} [props.size="md"] Size tier — scales the trigger (the card / compact
- *   square, its mark and name) AND the dropdown menu (width, row padding, avatars, the create
- *   "+" chip and the footer), so trigger and panel read at one size.
- * @param {string} [props.ariaLabel] Accessible name for the trigger. Defaults to
- *   "Workspace <name>".
+ * @param {boolean} [props.canCreate]
+ * @param {string} [props.createLabel]
+ * @param {boolean} [props.compact]
+ * @param {"sm"|"md"|"lg"} [props.size]
+ * @param {string} [props.ariaLabel]
  */
 export default function AppWorkspaceSwitcher(props: {
+    /**
+     * The switchable workspaces.
+     * @default []
+     */
     tenants?: {
         id: string;
         name: string;
         logoUrl?: string;
         badge?: string;
     }[];
+    /** The id of the active workspace. It drives the trigger and the tick, and falls back to the first workspace when it matches none. */
     currentId?: string;
     onSelect?: (tenant: object) => void;
+    /** An optional heading above the list, such as Workspaces. */
     menuLabel?: string;
+    /** A pinned row under the list. Pass any node, or a descriptor with a label, an optional icon and an optional href that the library renders as a menu row. */
     footerAction?: import('react').ReactNode | {
         label: string;
         icon?: string;
         href?: string;
     };
     linkComponent?: import('react').ElementType;
+    /**
+     * Adds a filter box above the list. It only earns its place past roughly eight workspaces.
+     * @default false
+     */
     searchable?: boolean;
     onCreate?: () => void;
+    /**
+     * Shows the create row. It is off by default because most members cannot create a workspace.
+     * @default false
+     */
     canCreate?: boolean;
+    /**
+     * The text of the create row.
+     * @default "Create workspace"
+     */
     createLabel?: string;
+    /**
+     * Draws a 36px monogram button instead of the full card, the shape a collapsed rail slot wants. The menu is the same either way.
+     * @default false
+     */
     compact?: boolean;
+    /**
+     * Scales the trigger (the card or compact square, its mark and name) and the menu (width, row padding, avatars, the create plus chip and the footer), so trigger and panel read at one size.
+     * @default "md"
+     */
     size?: "sm" | "md" | "lg";
+    /** The accessible name of the trigger. Without it the name is Workspace followed by the current workspace's name. */
     ariaLabel?: string;
 }): import("react").JSX.Element;

package/dist/types/lib/wuiMarker.d.ts

@@ -2,6 +2,8 @@
 export declare const WUI_MARKER_ATTRIBUTE = "data-wui";
 /** The attribute props mode adds: the plain props the component was given, as JSON. Written only when props mode is on. */
 export declare const WUI_MARKER_PROPS_ATTRIBUTE = "data-wui-props";
+/** The attribute that links an element to its Canvas board node where a part is ambiguous; the marker element carries the key the component was given, in every build. */
+export declare const WUI_CANVAS_KEY_ATTRIBUTE = "data-canvas";
 /** The global the importer sets through an init script before the page loads. */
 export declare const WUI_MARKERS_GLOBAL = "__WUI_MARKERS__";
 /** The value of WUI_MARKERS_GLOBAL that turns props mode on. */
@@ -15,6 +17,8 @@ export declare function wuiMarkerPropsOn(): boolean;
  * The attributes an App* root spreads onto its host element, placed before the component's rest
  * spread so a wrapper passing its own marker wins.
  *
+ * A data-canvas key the component was given rides on the marker element in every build.
+ *
  * In props mode the plain values the component was given ride along as JSON. The kit manifest stays
  * the one list of which props are plain: the importer keeps only those, so nothing here repeats it.
  * The props attribute is written even when empty, so a wrapper's marker never carries the inner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webority/ui-react",
-  "version": "0.88.1",
+  "version": "0.89.0",
   "description": "Webority shared React component library — App* primitives on react-bootstrap + the @webority/theme design system.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -23,15 +23,17 @@
       "types": "./dist/types/index.d.ts",
       "default": "./dist/ui-react.js"
     },
+    "./guidance.json": "./dist/guidance.json",
+    "./canvas-kit/*": "./dist/canvas-kit/*",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
   "dependencies": {
-    "@webority/theme": "0.88.1",
-    "@webority/ui-elements": "0.88.1"
+    "@webority/ui-elements": "0.89.0",
+    "@webority/theme": "0.89.0"
   },
   "peerDependencies": {
-    "@webority/analytics": "^0.25.0",
+    "@webority/analytics": "^0.26.0",
     "bootstrap": "5.3.3",
     "react": "^19.0.0",
     "react-bootstrap": "^2.10.0",
@@ -45,7 +47,7 @@
     "@types/react": "^19.2.17",
     "@vitejs/plugin-react": "^6.0.1",
     "@vitest/coverage-v8": "5.0.1",
-    "@webority/analytics": "0.25.1",
+    "@webority/analytics": "0.26.0",
     "bootstrap": "5.3.3",
     "jsdom": "30.1.1",
     "react": "^19.2.6",
@@ -54,10 +56,11 @@
     "typescript": "^7.0.2",
     "vite": "^8.0.12",
     "vitest": "5.0.1",
-    "@webority/canvas-kit": "0.88.1"
+    "@webority/canvas-kit": "0.89.0",
+    "@webority/tokens": "0.89.0"
   },
   "scripts": {
-    "build": "vite build && tsc -p tsconfig.json && node ../../scripts/sync-rcl-assets.mjs analytics",
+    "build": "vite build && tsc -p tsconfig.json && node ../../scripts/inject-meta-docs.mjs && node ../canvas-kit/dist/cli.js build --config canvas-kit.json --out dist/canvas-kit && node ../canvas-kit/dist/cli.js guidance --config canvas-kit.json --out dist/guidance.json && node ../../scripts/sync-rcl-assets.mjs analytics",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"