Improve Components documentation discovery and correctness

.github/workflows/documentation.yml

@@ -12,6 +12,7 @@ on:
   push:
     branches: ["main"]
     paths:
+      - ".github/workflows/documentation.yml"
       - "Documentation/**"
 
 permissions:

.github/workflows/markdown-verification.yml

@@ -6,6 +6,8 @@ on:
         branches:
             - main
         paths:
+            - '.github/workflows/markdown-verification.yml'
+            - '.markdownlint.json'
             - 'Documentation/**'
             - 'README.md'
             - 'release.md'
@@ -20,6 +22,8 @@ on:
         branches:
             - '**'
         paths:
+            - '.github/workflows/markdown-verification.yml'
+            - '.markdownlint.json'
             - 'Documentation/**'
             - 'README.md'
             - 'release.md'
@@ -39,32 +43,7 @@ permissions:
     contents: read
 
 jobs:
-    markdown-lint:
-        runs-on: ubuntu-latest
-        timeout-minutes: 15
-        steps:
-            - name: Checkout code
-              uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
-              with:
-                  persist-credentials: false
-
-            - name: Lint Markdown files
-              uses: DavidAnson/markdownlint-cli2-action@eb5ca3ab411449c66620fe7f1b3c9e10547144b0 # v18
-              with:
-                  globs: |
-                      README.md
-                      release.md
-                      Documentation/**/*.md
-                      Documentation/**/*.mdx
-                      Source/*.md
-                      Migrator/*.md
-                      ESLint/*.md
-                      Conformance/*.md
-                      Adapters/**/*.md
-                      Storybook/*.md
-                      scripts/*.md
-
-    link-verification:
+    markdown-verification:
         runs-on: ubuntu-latest
         timeout-minutes: 15
         steps:
@@ -78,11 +57,10 @@ jobs:
               with:
                   node-version: 23.x
 
-            - name: Check repository-local Markdown and MDX links
-              run: |
-                  node Documentation/verify-local-links.mjs Documentation
-                  node Documentation/verify-local-links.mjs Adapters
-                  node Documentation/verify-local-links.mjs scripts
+            # Run the same entry point contributors use locally so linting,
+            # authoring validation, and local-link checks cannot drift apart.
+            - name: Check Markdown and MDX authoring
+              run: ./Documentation/verify-markdown.sh
 
             - name: Check external links in consumer documentation
               uses: JustinBeckwith/linkinator-action@7b6b0bc671f6264e1a8daa4488a5bd91ce61dcd4 # v2.4.2

.markdownlint.json

@@ -4,16 +4,28 @@
   "MD013": false,
   "MD033": {
     "allowed_elements": [
-      "antml:function_calls",
-      "antml:invoke",
-      "antml:parameter",
       "a",
-      "Steps",
       "Aside",
+      "Badge",
+      "Card",
       "CardGrid",
+      "Code",
+      "FileTree",
+      "Fragment",
+      "FullStackTabs",
+      "Icon",
+      "LinkButton",
+      "LinkCard",
+      "OsAwareTabs",
+      "Recap",
       "SimpleCard",
-      "Card",
-      "StorybookEmbed"
+      "StackDiagram",
+      "Steps",
+      "StorybookEmbed",
+      "TabItem",
+      "Tabs",
+      "TopicHero",
+      "YouWillLearn"
     ]
   },
   "MD041": false,

Documentation/Chat/index.md

@@ -1,4 +1,7 @@
-# Chat
+---
+title: Chat
+description: Build topic-based chat with host-owned data, mentions, emoji, and message actions.
+---
 
 The `Chat` components give an application a topic-based chat that opens in a sidebar next to the view — a topics list, the conversation for the picked topic, `@`-mentions of people and agents, emoji, and per-message actions — without the library holding any opinion about where the data lives or what a backend looks like.
 

Documentation/CommandDialog/index.md

@@ -1,4 +1,7 @@
-# CommandDialog
+---
+title: CommandDialog
+description: Execute Arc commands in a dialog with automatic form state, validation, and result handling.
+---
 
 The `CommandDialog` component provides a dialog interface for executing commands with built-in form handling and validation.
 

Documentation/CommandForm/checkbox-field.md

@@ -25,4 +25,3 @@ import { CheckboxField } from '@cratis/components/CommandForm';
 
 - Default value is `false`.
 - Validation state is reflected through `aria-invalid` and `data-invalid`.
-

Documentation/CommandForm/index.md

@@ -1,4 +1,7 @@
-# CommandForm
+---
+title: CommandForm
+description: Build type-safe Arc command forms with reusable fields, validation, and automatic value binding.
+---
 
 The `CommandForm` component provides form field components for building command input forms with automatic type handling and validation.
 

Documentation/CommandForm/input-text-field.md

@@ -28,4 +28,3 @@ import { InputTextField } from '@cratis/components/CommandForm';
 - Default value is an empty string.
 - The field spans full width within its container.
 - Validation state is reflected through `aria-invalid` and `data-invalid`.
-

Documentation/CommandForm/number-field.md

@@ -30,4 +30,3 @@ import { NumberField } from '@cratis/components/CommandForm';
 - The field spans full width within its container.
 - Validation state is reflected through `aria-invalid` and `data-invalid`.
 - When the value is cleared, it falls back to `0`.
-

Documentation/CommandForm/slider-field.md

@@ -28,4 +28,3 @@ import { SliderField } from '@cratis/components/CommandForm';
 - Default value is `0`.
 - The slider spans full width within its container.
 - The selected numeric value is rendered centered beneath the slider track.
-

Documentation/CommandStepper/index.md

@@ -1,18 +1,15 @@
-# CommandStepper
+---
+title: CommandStepper
+description: Split an Arc command form into validation-aware steps for wizard-style workflows.
+---
 
-The `CommandStepper` component is a command-scoped stepper foundation for wizard-style flows.
+The `CommandStepper` component executes one Arc command through an inline, multi-step form.
 
 ## Purpose
 
-`CommandStepper` establishes a `CommandForm` context and focuses on step rendering and validation-driven navigation.
+Use `CommandStepper` when the wizard belongs directly in a page region, panel, or route. It establishes a `CommandForm`, renders `StepperPanel` steps with built-in navigation, and executes the command from the final step.
 
-Use it when you want to:
-
-- Render `StepperPanel` steps with built-in previous and next navigation
-- Color step number circles based on validation state
-- Keep form validation and step transitions scoped to a single command
-
-`StepperCommandDialog` is built on top of `CommandStepper` and adds command execution, submission flow, and dialog behavior.
+`CommandStepper` and [`StepperCommandDialog`](../StepperCommandDialog/index.md) are sibling public components that share the private `CommandStepperContent` rendering primitive. Both execute the command. Choose `StepperCommandDialog` when the wizard should be modal; the dialog also owns cancel, busy state, and authorization routing.
 
 ## Basic Usage
 
@@ -52,12 +49,16 @@ export const ProjectWizard = () => {
 - `showSubmit`: Show the built-in submit action on the last step (default: `true`)
 - `okLabel`: Submit button label. Falls back to the provider's `messages.stepper.submit`, then `'Submit'`
 - `isBusy`: Disables the navigation controls while something is running
-- `onSubmit`: Submit callback invoked on the last step
-- Any `CommandForm` props, including `initialValues`, `currentValues`, `validateOnInit`, and validation callbacks
+- Other applicable `CommandForm` props, including `initialValues`, `currentValues`, `validateOnInit`, field-validation callbacks, and inherited command execution callbacks:
+  - `onSuccess`: Callback invoked with the typed response after successful command execution
+  - `onValidationFailure`: Callback invoked with validation results when command execution returns validation errors
+  - `onFailed`: Callback invoked with the full command result for an unsuccessful, non-validation result
 - `onBeforeExecute`: Transform command values before execution — it must **return** the values to run with, and it runs only on submit, so it can never satisfy required-field validation (seed those through `initialValues`)
 - `linear` (default `true`), `orientation` (`'horizontal'` default / `'vertical'`), `headerPosition` (`'top'` default / `'bottom'`), `start`, `end`, `onChangeStep`, and `pt`: the active `StepperCustomizationProps` surface. It maps onto stable `root`, `list`, `step`, `header`, `number`, `title`, `separator`, `panels`, and `panel` parts.
 - `ptOptions` and `unstyled`: retained temporarily for source compatibility; ignored because Cratis part attributes always merge and styling is CSS-owned.
 
+Because `CommandStepper` has no outer dialog, it has no `dialogPt` or `dialogUnstyled` props; `pt` targets the stepper directly.
+
 Conditional steps written as `{condition && <StepperPanel/>}` are counted correctly — only the panels that actually render are counted, so navigation and the per-step validation state stay in step with what is on screen. A `<>…</>` fragment wrapping several panels still counts as **one** step.
 
 ## Validation Indicators
@@ -72,4 +73,4 @@ The step number circles are then styled based on state:
 
 ## See Also
 
-- [StepperCommandDialog](../StepperCommandDialog/index.md)
+- [StepperCommandDialog](../StepperCommandDialog/index.md) — place the same kind of command wizard in a modal dialog

Documentation/Common/action-menubar.md

@@ -0,0 +1,59 @@
+---
+title: ActionMenubar
+description: Render a horizontal toolbar of page-level command actions.
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+`ActionMenubar` renders a flat set of command actions from `@cratis/components/Common`. Use it for page-level actions; use [`Toolbar`](../Toolbar/index.md) for a canvas-style tool palette with active tools, groups, folders, or fan-out panels.
+
+## Basic usage
+
+```tsx
+import { ActionMenubar } from '@cratis/components/Common';
+
+<ActionMenubar
+    aria-label='Project actions'
+    model={[
+        { label: 'Create project', command: createProject },
+        { label: 'Archive', command: archiveProject, severity: 'warn' },
+        { label: 'Delete', command: deleteProject, severity: 'danger', disabled: true },
+    ]}
+/>;
+```
+
+The root is a `div` with `role='toolbar'` and `data-cratis-part='root'`. Pass `aria-label` to set the toolbar's accessible name.
+
+## `ActionMenuItem`
+
+| Field       | Type                                        | Purpose                                      |
+| ----------- | ------------------------------------------- | -------------------------------------------- |
+| `label`     | `string`                                    | Visible button label.                        |
+| `icon`      | `ReactNode`                                 | Content rendered before the label.           |
+| `command`   | `() => void`                                | Invoked when the action is activated.        |
+| `disabled`  | `boolean`                                   | Disables the action button.                  |
+| `className` | `string`                                    | Extra class name for the action button.      |
+| `severity`  | `ButtonSeverity`                            | Maps the action severity to a button tone.   |
+| `template`  | `(item: ActionMenuItem) => ReactNode`       | Fully replaces rendering for this menu item. |
+
+When `template` is present, `ActionMenubar` renders its result directly instead of rendering a Components `Button`. The item's `severity`, `disabled`, and `className`, the shared `pt`, and the normal button label, icon, and command wiring therefore do not apply unless the template implements them.
+
+## `ActionMenubarProps`
+
+| Prop         | Type               | Required | Purpose                                                    |
+| ------------ | ------------------ | -------- | ---------------------------------------------------------- |
+| `model`      | `ActionMenuItem[]` | Yes      | Actions rendered from left to right.                       |
+| `className`  | `string`           | No       | Extra class name for the toolbar root.                     |
+| `aria-label` | `string`           | No       | Accessible name for the toolbar.                           |
+| `pt`         | `ButtonParts`      | No       | Part attributes applied to every non-template action button. |
+| `ptOptions`  | `object`           | No       | Deprecated, retained for source compatibility, and ignored. |
+| `unstyled`   | `boolean`          | No       | Deprecated, retained for source compatibility, and ignored. |
+
+`pt` is the [`ButtonParts`](basic-controls.md) surface, not a toolbar-root parts object. It is passed to each `Button` created from the model. Use `className` to identify the `ActionMenubar` root.
+
+## See also
+
+- [DataPage](../DataPage/index.md) — the list-page composition that uses `ActionMenubar` for its action row
+- [Toolbar](../Toolbar/index.md) — canvas-style tool palettes
+- [Stable component parts](../Styling/pass-through.md) — Components-owned parts and state attributes

Documentation/Common/index.md

@@ -1,4 +1,7 @@
-# Common Components
+---
+title: Common Components
+description: Reference the shared controls, provider, layout, icons, and form utilities used across Components.
+---
 
 The Common module provides reusable UI components and the styling setup primitive that serve as building blocks for applications.
 
@@ -8,6 +11,7 @@ The Common module provides reusable UI components and the styling setup primitiv
 - **TextInput / TextArea**: Native text controls with semantic string changes and real element refs.
 - **Checkbox / Radio / Switch**: Native form choices with semantic boolean changes and browser-owned submission and reset behavior.
 - **Button / IconButton**: Native actions with semantic variants, tones, loading, and disabled behavior.
+- **ActionMenubar**: Horizontal toolbar of page-level command actions.
 - **Surface**: A bounded `div`, `section`, or `article` container with no invented interaction state.
 - **Icon / IconDisplay**: Unified icon type that accepts a CSS class string or any React node.
 - **Page**: Layout primitive for consistent page structures.
@@ -17,6 +21,7 @@ The Common module provides reusable UI components and the styling setup primitiv
 ## See Also
 
 - [Basic controls](basic-controls.md) — native form, ref, change, part, and state contracts
+- [ActionMenubar](action-menubar.md) — page-level command actions
 - [CratisComponentsProvider](cratis-components-provider.md) — locale, labels, and toaster configuration
 - [Icon](icon.md) - Icon type and IconDisplay component
 - [Page](page.md) - Page layout component

Documentation/Common/toc.yml

@@ -4,6 +4,8 @@
   href: cratis-components-provider.md
 - name: Basic controls
   href: basic-controls.md
+- name: ActionMenubar
+  href: action-menubar.md
 - name: Icon
   href: icon.md
 - name: Page

Documentation/DataPage/index.md

@@ -1,4 +1,7 @@
-# DataPage
+---
+title: DataPage
+description: Combine query-backed tables, actions, selection, and optional details in a complete data page.
+---
 
 The `DataPage` component provides a complete page layout for displaying and managing data from queries, including table view, menu actions, and optional detail panels.
 

Documentation/DataPage/menu-items.md

@@ -96,7 +96,7 @@ import { FaFloppyDisk, FaDownload, FaUpload } from 'react-icons/fa6';
 <MenuItem label="Upload" icon={FaUpload} command={handleUpload} />
 ```
 
-:::caution
+:::caution[Pass an icon component]
 Don't pass `icon="pi pi-save"` (a PrimeIcons CSS class) or `icon={<FaFloppyDisk />}` (a JSX element).
 DataPage instantiates the icon itself, so the prop must be the component type: `icon={FaFloppyDisk}`.
 :::

Documentation/DataTables/index.md

@@ -1,4 +1,7 @@
-# DataTables
+---
+title: DataTables
+description: Render local, paged, and observable query data with sorting, filtering, and selection.
+---
 
 The DataTables module provides a semantic local-array table plus specialized Arc query and observable-query wrappers.
 

Documentation/Dialogs/index.md

@@ -1,4 +1,7 @@
-# Dialogs
+---
+title: Dialogs
+description: Present custom content, busy states, and confirmations with the shared dialog components.
+---
 
 The Dialogs module provides common dialog components for user interactions.
 

Documentation/Display/index.md

@@ -1,4 +1,7 @@
-# Display
+---
+title: Display
+description: Show statuses, counts, avatars, progress, and loading states with presentational primitives.
+---
 
 The `Display` components are small, presentational primitives for status and feedback — tags, badges, chips, avatars, progress, and loading skeletons. Import them from `@cratis/components/Display`.
 

Documentation/Filter/index.md

@@ -1,6 +1,9 @@
-# FilterPanel
+---
+title: FilterPanel
+description: Build reusable filter panels with option, range, and custom editors.
+---
 
-The `FilterPanel` component provides a standalone, reusable filter UI that can be placed next to any data view. It renders as a positioned dropdown anchored below a trigger button and supports single-select, multi-select, numeric range (with histogram), and fully custom filter editors declared as children.
+The `FilterPanel` component provides a standalone, reusable filter UI that can be placed next to any data view. It renders as a positioned dropdown anchored below a trigger button and supports single-select, multi-select, numeric range (with histogram), and fully custom filter editors declared as children. If you are choosing between faceted, column, and global filtering, start with [Choosing a component](../choosing-a-component.md#filtering).
 
 ## Key Features
 

Documentation/Migration/index.md

@@ -1,4 +1,7 @@
-# Migration
+---
+title: Migration
+description: Move @cratis/components applications between major versions with focused upgrade guides.
+---
 
 Guides for moving `@cratis/components` forward across major versions. Each guide is scoped to one version jump and lists the changes a consuming application can observe: dependencies, imports, styling, licensing, behavior, and verification.
 

Documentation/ObjectContentEditor/index.md

@@ -1,4 +1,7 @@
-# ObjectContentEditor
+---
+title: ObjectContentEditor
+description: Explore complex JSON objects with schema-aware rendering and breadcrumb navigation.
+---
 
 The `ObjectContentEditor` component displays and allows exploration of complex JSON objects with schema-aware rendering and navigation.
 

Documentation/ObjectNavigationalBar/index.md

@@ -1,4 +1,7 @@
-# ObjectNavigationalBar
+---
+title: ObjectNavigationalBar
+description: Navigate hierarchical objects with a controlled breadcrumb bar and back action.
+---
 
 The `ObjectNavigationalBar` component provides breadcrumb navigation for hierarchical data structures.
 

Documentation/PivotViewer/index.md

@@ -1,4 +1,7 @@
-# PivotViewer
+---
+title: PivotViewer
+description: Explore large datasets through interactive grouping, filtering, zooming, and spatial rendering.
+---
 
 The `PivotViewer` component provides an interactive, high-performance visualization for exploring large datasets with dynamic grouping, filtering, and zooming capabilities.