@moldable-ai/ui 0.2.29 → 0.2.31

package/src/components/ui/date-picker.md

@@ -44,9 +44,12 @@ focus returns to the trigger.
 
 ## Platform behavior
 
-This component is portable and uses no host API. A future native date or time
-control must be introduced through a shared host capability with this
-renderer-owned control as its fallback.
+This component is renderer-owned and does not call the host. A call site that
+deliberately prefers the host picker can use `useHostDateTimePicker()` or
+`pickDateTimeWithHost('date', ...)`, then keep `DatePicker` as its portable
+fallback. A `status: 'fallback'` result does not open renderer UI for the
+caller. See
+[`host-date-time-picker.md`](../../lib/host-date-time-picker.md).
 
 ## Don't
 

package/src/components/ui/dialog.md

@@ -41,19 +41,21 @@ temporary control overlays where seeing the underlying context is useful.
 Use `DialogAction` for footer commands that need the standard async and keyboard
 contracts. Its `loading` prop forwards to `Button`, preventing duplicate
 activation while retaining the label width and accessible name. Keep the dialog
-controlled, show inline field errors, and close only after success. Disable the
-whole form only when edits during submission would be unsafe. Use
-`ConfirmDialog` when confirmation is the entire workflow.
+controlled when an async result must own closure, show inline field errors, and
+close only after success. Disable the whole form only when edits during
+submission would be unsafe. Use `ConfirmDialog` when confirmation is the entire
+workflow.
 
 Set `primary` on at most one `DialogAction` to opt into the default-action
-shortcut. Command+Enter activates it on macOS; Control+Enter does so on other
-platforms. The shortcut works from anywhere in the dialog unless a focused
-control consumes the key event with `preventDefault()`, or the primary action is
-loading or disabled. Plain Enter keeps the focused control's native behavior.
-Use `Kbd` to show the shortcut when it improves discovery; render the
-platform-appropriate modifier in app code.
+shortcut. Command+Enter activates it on macOS and iOS-family runtimes;
+Control+Enter does so elsewhere. The shortcut works from anywhere in the dialog
+unless a focused control consumes the key event with `preventDefault()`, or the
+primary action is loading or disabled. Plain Enter keeps the focused control's
+native behavior. Use `Kbd` to show the shortcut when it improves discovery;
+render the platform-appropriate modifier in app code.
 
 Every dialog needs a `DialogTitle`. Add `DialogDescription` when the outcome or
-scope is not obvious. Escape, outside dismissal, initial focus, and focus return
-come from the Radix primitive; do not replace them with manual document event
-handlers.
+scope is not obvious. `DialogContent` focuses its own container on open by
+default; pass `onOpenAutoFocus` for a deliberate alternative. Escape, outside
+dismissal, and focus return come from the Radix primitive; do not replace them
+with manual document event handlers.

package/src/components/ui/drawer.md

@@ -0,0 +1,58 @@
+# Drawer
+
+## Purpose
+
+`Drawer` presents a modal surface that enters from a screen edge and can be
+dismissed by dragging, pressing Escape, or using a close action. It wraps Vaul
+and defaults to the bottom edge.
+
+## Usage
+
+```tsx
+import {
+  Button,
+  Drawer,
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerTrigger,
+} from '@moldable-ai/ui'
+
+;<Drawer>
+  <DrawerTrigger asChild>
+    <Button>Open upload queue</Button>
+  </DrawerTrigger>
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Upload queue</DrawerTitle>
+      <DrawerDescription>Two files are ready to sync.</DrawerDescription>
+    </DrawerHeader>
+    <DrawerFooter>
+      <Button>Upload all</Button>
+      <DrawerClose asChild>
+        <Button variant="outline">Cancel</Button>
+      </DrawerClose>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
+```
+
+`Drawer` accepts the Vaul root props, including controlled `open` and
+`onOpenChange`, `direction="top" | "bottom" | "left" | "right"`, snap points,
+and dismissal options. `DrawerContent` supplies the portal and overlay. Bottom
+drawers also show the built-in drag indicator.
+
+## Quality bar
+
+- Always include `DrawerTitle`; add `DrawerDescription` when the title does not
+  fully explain the task.
+- Keep the primary action and an explicit close action in `DrawerFooter`.
+- Use `asChild` when a shared button should be the trigger or close control.
+- Keep long drawer bodies independently scrollable and preserve focus
+  management from the primitive.
+- Use `Dialog` for a centered decision and `Sheet` for a persistent side panel.
+- Do not disable outside-click or Escape dismissal without another obvious way
+  to close the drawer.

package/src/components/ui/error-boundary-view.md

@@ -25,7 +25,7 @@ nested cards.
 ## Usage
 
 ```tsx
-import { ErrorBoundaryView } from '@moldable-ai/ui'
+import { Button, ErrorBoundaryView } from '@moldable-ai/ui'
 
 function PaneError() {
   return (

package/src/components/ui/field.md

@@ -58,7 +58,8 @@ Use `orientation="horizontal"` for compact checkbox/radio rows and `orientation=
 - Give every control a visible label or an accessible name.
 - Connect labels and descriptions with `htmlFor`, `id`, and `aria-describedby`.
 - Set both `data-invalid` on `Field` and `aria-invalid` on the control.
-- Use real `disabled` state and reflect it on the field group when styling needs it.
+- Use real `disabled` state and set `data-disabled="true"` on `Field` when its
+  label or title should also appear disabled.
 - Place validation directly after the affected control.
 - Group related checkbox or radio controls in `FieldSet` with `FieldLegend`.
 

package/src/components/ui/form.md

@@ -0,0 +1,71 @@
+# Form
+
+## Purpose
+
+The form adapter connects React Hook Form state to labels, controls,
+descriptions, and validation messages. `Form` is `FormProvider`; the native
+`form` element remains part of the composition.
+
+## Usage
+
+```tsx
+import { useForm } from 'react-hook-form'
+import {
+  Button,
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+  Input,
+} from '@moldable-ai/ui'
+
+type Values = { project: string }
+
+function ProjectForm() {
+  const form = useForm<Values>({ defaultValues: { project: '' } })
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(saveProject)}>
+        <FormField
+          control={form.control}
+          name="project"
+          rules={{ required: 'Enter a project name.' }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Project name</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormDescription>Shown in the app titlebar.</FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Save</Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+`FormField` forwards React Hook Form `Controller` props. Within its
+`FormItem`, `FormLabel` targets the slotted `FormControl`; the control receives
+`id`, `aria-invalid`, and description/message references. `FormMessage` shows
+the current field error message, falls back to its children, and renders
+nothing when both are absent. `useFormField` exposes the generated IDs and
+field state to custom parts.
+
+## Quality bar
+
+- Put `FormControl`, `FormLabel`, `FormDescription`, and `FormMessage` inside
+  the same `FormField` and `FormItem`.
+- Give `FormControl` one interactive child that can accept the injected
+  accessibility props.
+- Keep validation messages specific and place them beside the affected field.
+- Use a native `form` with `onSubmit`; `Form` alone does not submit anything.
+- Prefer the simpler `Field` primitives when React Hook Form state is not
+  needed.

package/src/components/ui/grid.md

@@ -61,9 +61,10 @@ Prefer changing this value at deliberate window breakpoints. A smaller window sh
 - Home and End move to the first and last available tile in the current row.
 - Control/Command + Home and End move to the first and last available tile in
   the entire grid.
-- Space changes selection.
-- Enter changes selection and invokes `onAction`.
-- A single pointer click changes selection. A double click invokes `onAction`.
+- Space changes selection when selection is enabled.
+- Enter changes selection when enabled and invokes `onAction`.
+- A single pointer click changes selection when selection is enabled. A double
+  click invokes `onAction`.
 - Disabled tiles are skipped.
 - Buttons and links inside a tile preserve their own pointer behavior.
 - When the grid first mounts, the first selected, enabled tile receives the

package/src/components/ui/icon-button.md

@@ -22,7 +22,10 @@ import { IconButton } from '@moldable-ai/ui'
 </IconButton>
 ```
 
-`size` is `xs`, `sm`, `default`, or `lg`. `shape` is `rounded` or `circle`. `loading` disables the control, exposes `aria-busy`, and replaces the icon with a progress indicator. `tooltip` may be `true` to reuse the label as a native hint or a specific string.
+`size` is `xs`, `sm`, `default`, `lg`, or `xl`. `shape` is `rounded` or
+`circle`. `loading` disables the control, exposes `aria-busy`, and replaces the
+icon with a progress indicator. `tooltip` may be `true` to reuse the label as
+a native hint or a specific string.
 
 ## Quality bar
 

package/src/components/ui/input-group.md

@@ -0,0 +1,49 @@
+# Input Group
+
+## Purpose
+
+`InputGroup` combines one text control with inline or stacked context and
+actions inside a single bordered surface.
+
+## Usage
+
+```tsx
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  InputGroupText,
+} from '@moldable-ai/ui'
+
+;<InputGroup>
+  <InputGroupAddon>
+    <InputGroupText>https://</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput aria-label="Workspace address" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton aria-label="Copy address">Copy</InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+Use `InputGroupInput` for a native input or `InputGroupTextarea` for multiline
+text. `InputGroupAddon` defaults to `inline-start` and also supports
+`inline-end`, `block-start`, and `block-end`. Clicking a non-button inline
+addon focuses the contained input. `InputGroupButton` defaults to
+`type="button"`, `variant="ghost"`, and `size="xs"`; its sizes are `xs`, `sm`,
+`icon-xs`, and `icon-sm`.
+
+## Quality bar
+
+- Label the actual input or textarea; the group and its adornments do not
+  provide its accessible name.
+- Mark decorative icons `aria-hidden` and give icon-only buttons an
+  `aria-label`.
+- Put interactive controls in `InputGroupButton`, not in a clickable addon.
+- Set `aria-invalid` on the input or textarea so the group shows its error
+  state.
+- When disabling the control, add `data-disabled="true"` to `InputGroup` if
+  its addons should also appear disabled.
+- Keep addons short. Use `block-start` or `block-end` for context that cannot
+  fit inline.

package/src/components/ui/input-otp.md

@@ -0,0 +1,56 @@
+# Input OTP
+
+## Purpose
+
+`InputOTP` presents a one-time code as visual slots while retaining one
+keyboard- and paste-friendly input through the `input-otp` primitive.
+
+## Usage
+
+```tsx
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSeparator,
+  InputOTPSlot,
+} from '@moldable-ai/ui'
+
+;<InputOTP
+  aria-label="Verification code"
+  maxLength={6}
+  value={code}
+  onChange={setCode}
+>
+  <InputOTPGroup>
+    {[0, 1, 2].map((index) => (
+      <InputOTPSlot key={index} index={index} />
+    ))}
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    {[3, 4, 5].map((index) => (
+      <InputOTPSlot key={index} index={index} />
+    ))}
+  </InputOTPGroup>
+</InputOTP>
+```
+
+`maxLength` defines the code length and the rendered slot indexes must match
+it. Native input props and `input-otp` options such as `pattern`,
+`pasteTransformer`, `onComplete`, and `pushPasswordManagerStrategy` pass
+through. `containerClassName` styles the visible slot container; `className`
+targets the underlying input. `InputOTPSeparator` renders a separator role
+with the shared minus icon.
+
+## Quality bar
+
+- Give the root a visible label or an accessible name.
+- Match every `InputOTPSlot` index to a valid position below `maxLength`.
+- Use `pattern` when the code format is restricted; do not reject valid pasted
+  codes silently.
+- Let users paste and use password managers or system code autofill; add an
+  appropriate `autoComplete` value for the workflow.
+- Report expiration, resend status, and server errors outside the slots in
+  text, not by color alone.
+- Do not submit solely because the last character was entered unless the
+  result is safe, reversible, and clearly communicated.

package/src/components/ui/input.md

@@ -0,0 +1,40 @@
+# Input
+
+## Purpose
+
+`Input` is the shared styled native input. It preserves native input types,
+editing behavior, constraints, and form participation while applying semantic
+control tokens.
+
+## Usage
+
+```tsx
+import { Input, Label } from '@moldable-ai/ui'
+
+;<div className="grid gap-2">
+  <Label htmlFor="workspace-name">Workspace name</Label>
+  <Input
+    id="workspace-name"
+    name="workspaceName"
+    autoComplete="organization"
+    required
+  />
+</div>
+```
+
+All native input props pass through. `controlSize` accepts `mini`, `small`,
+`medium`, `large`, or `xl`; when omitted, the input inherits the active theme
+size. File inputs receive matching typography and file-button treatment.
+
+## Quality bar
+
+- Associate every input with a visible label or an accessible name.
+- Choose the correct native `type`, `name`, `autoComplete`, `inputMode`, and
+  constraints for the data.
+- Set `aria-invalid` when invalid and connect supporting or error text with
+  `aria-describedby`.
+- Use `disabled` only for unavailable controls; use `readOnly` for values that
+  should remain selectable.
+- Keep placeholder text as a short hint, never as the only label.
+- Use `Textarea`, `SearchField`, `DateField`, or `InputGroup` when their
+  behavior matches the task more closely.

package/src/components/ui/inspector.md

@@ -1,11 +1,51 @@
 # Inspector
 
-Secondary property controls for the current selection.
+## Purpose
 
-Compose `Inspector`, `InspectorHeader`, `InspectorContent`,
-`InspectorSection`, and aligned `InspectorRow` pairs. Controls should usually
-use compact sizes.
+The inspector primitives compose a secondary property pane for the current
+selection. The root is an `aside`; its header stays fixed while
+`InspectorContent` scrolls and includes bottom chat clearance.
 
-The inspector must remain subordinate to the primary pane. Collapse it when
-width is constrained, group related properties, and avoid placing primary
-workflow actions inside it.
+## Usage
+
+```tsx
+import {
+  Input,
+  Inspector,
+  InspectorContent,
+  InspectorHeader,
+  InspectorLabel,
+  InspectorRow,
+  InspectorSection,
+  InspectorValue,
+} from '@moldable-ai/ui'
+
+;<Inspector>
+  <InspectorHeader>Inspector</InspectorHeader>
+  <InspectorContent>
+    <InspectorSection title="Appearance">
+      <InspectorRow>
+        <InspectorLabel htmlFor="document-title">Title</InspectorLabel>
+        <InspectorValue>
+          <Input id="document-title" controlSize="small" />
+        </InspectorValue>
+      </InspectorRow>
+    </InspectorSection>
+  </InspectorContent>
+</Inspector>
+```
+
+`InspectorSection` accepts optional `title` and `actions`; it omits its header
+when neither is present. `InspectorRow` aligns a label and value in two
+columns. `InspectorLabel` renders a compact native label, and
+`InspectorValue` contains the control or read-only value.
+
+## Quality bar
+
+- Keep the inspector subordinate to the primary pane and collapse it when
+  width is constrained.
+- Group related properties into short sections and use section actions only
+  for local operations.
+- Connect each `InspectorLabel` to its control with `htmlFor` and `id`.
+- Use compact control sizes and keep unpredictable values truncatable.
+- Keep primary workflow actions out of the inspector.

package/src/components/ui/item.md

@@ -23,7 +23,7 @@ import {
 } from '@moldable-ai/ui'
 
 ;<ItemGroup>
-  <Item size="sm">
+  <Item role="listitem" size="sm">
     <ItemMedia variant="icon">
       <FileText />
     </ItemMedia>
@@ -53,8 +53,10 @@ Use `asChild` when the whole item is a link or another interactive primitive. Av
 
 ## API summary
 
-- `ItemGroup`: `role="list"` container.
-- `Item`: `variant="default"`, `"outline"`, or `"muted"`; `size="default"` or `"sm"`; optional `asChild`.
+- `ItemGroup`: `role="list"` container. Give each direct `Item`
+  `role="listitem"`.
+- `Item`: `variant="default"`, `"outline"`, or `"muted"`;
+  `size="default"` or `"sm"`; optional `asChild`.
 - `ItemMedia`: `variant="default"`, `"icon"`, or `"image"`.
 - `ItemContent`: flexible title/description column.
 - `ItemTitle`, `ItemDescription`: primary and secondary text.

package/src/components/ui/kbd.md

@@ -0,0 +1,30 @@
+# Kbd
+
+## Purpose
+
+`Kbd` displays a keyboard key or shortcut hint. `KbdGroup` lays out several
+keys as one shortcut. These components are visual labels only; they do not
+register keyboard handlers.
+
+## Usage
+
+```tsx
+import { Kbd, KbdGroup } from '@moldable-ai/ui'
+
+;<KbdGroup aria-label="Command K">
+  <Kbd>⌘</Kbd>
+  <Kbd>K</Kbd>
+</KbdGroup>
+```
+
+Both components accept native `<kbd>` props and `className`. `Kbd` applies the
+keycap treatment and sizes unclassified SVG children; `KbdGroup` supplies only
+an inline flex layout.
+
+## Guidance
+
+- Show shortcuts only when the command really supports them.
+- Keep key names brief and use the same notation throughout the app.
+- Add an accessible label when modifier glyphs may not be announced clearly.
+- Keep `Kbd` non-interactive; place click behavior on a real button or link.
+- Do not use shortcut hints as the only way to discover an action.

package/src/components/ui/label.md

@@ -0,0 +1,29 @@
+# Label
+
+## Purpose
+
+`Label` gives a form control a visible, clickable name. It wraps the Radix
+label primitive and accepts its props.
+
+## Usage
+
+```tsx
+import { Input, Label } from '@moldable-ai/ui'
+
+;<div className="space-y-2">
+  <Label htmlFor="project-name">Project name</Label>
+  <Input id="project-name" name="projectName" />
+</div>
+```
+
+## Guidance
+
+- Pair `htmlFor` with a unique control `id`, or nest the control when that is
+  the clearer native relationship.
+- Use a short noun phrase and keep instructions or validation outside the
+  label.
+- Keep a visible label for text fields; a placeholder is not a replacement.
+- Mark optional or required state consistently and expose it to assistive
+  technology on the control.
+- The built-in styles respond to disabled peer or group state; set the actual
+  control's `disabled` attribute as well.

package/src/components/ui/list.md

@@ -81,8 +81,8 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 
 - Arrow Up/Down moves through a vertical list; Arrow Left/Right moves through a horizontal list.
 - Home and End move to the first and last available item.
-- Space changes selection.
-- Enter changes selection and invokes `onAction`.
+- Space changes selection when selection is enabled.
+- Enter changes selection when enabled and invokes `onAction`.
 - A single pointer click changes selection. A double click invokes `onAction`.
 - Disabled items are skipped during keyboard navigation and cannot be selected or activated.
 - Interactive descendants such as buttons and links keep their own pointer behavior. They do not select or activate the containing item.

package/src/components/ui/material.md

@@ -1,13 +1,14 @@
 # Material
 
-Adaptive material for navigation and control chrome.
+`Material` provides an adaptive sampled layer for navigation and control
+chrome. `MaterialGroup` gives a related control cluster one shared layer.
 
 ```tsx
-<Material asChild variant="regular" elevation="none">
+<Material asChild variant="medium" elevation="none">
   <Toolbar>{/* context and actions */}</Toolbar>
 </Material>
 
-<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+<MaterialGroup variant="thin" shape="capsule" spacing="compact">
   <IconButton label="Previous" variant="ghost">
     <ChevronLeft />
   </IconButton>
@@ -19,15 +20,25 @@ Adaptive material for navigation and control chrome.
 
 ## Variants
 
-- `regular` provides a frosted, legible control or navigation layer.
-- `clear` is less frosted and is only for compact controls floating over
-  photos, maps, video, or another richly colored canvas.
+- Standard thicknesses are `ultra-thick`, `thick`, `medium`, `thin`, and
+  `ultra-thin`, ordered from most filled to most transparent. They all use the
+  standard material blur; thickness controls translucency.
+- `regular` is a compatibility alias for `medium` and remains the default.
+- `clear` is a compatibility alias for `ultra-thin`.
 
-Both variants start with an opaque fallback. Backdrop sampling is enabled only
-when the renderer supports it. Reduced transparency and forced colors keep the
-fallback opaque.
+Every variant starts with an opaque fallback. Backdrop sampling is enabled only
+when the renderer supports it.
 
-## Grouping
+## Shape, elevation, and grouping
+
+- `shape` is `rounded`, `capsule`, or `circle`; it defaults to `rounded`.
+- `elevation` is `none`, `panel`, or `overlay`; it defaults to `none` and
+  controls shadow independently of thickness.
+- `interactive` adds hover and press feedback when the material surface itself
+  is the control.
+- `asChild` applies `Material` to its single child through a Radix slot.
+- `MaterialGroup` supports `spacing="compact" | "default" | "comfortable"`
+  and defaults to `default`.
 
 `MaterialGroup` creates one sampled layer for a related cluster. Put ordinary
 ghost or transparent controls inside it. Do not wrap each child in another
@@ -42,8 +53,10 @@ do not read as one group.
   temporary control layers.
 - Keep documents, calendars, tables, forms, cards, sheets, and primary content
   canvases opaque.
-- Prefer `regular`. A `clear` surface needs stable contrast across every part
-  of the media behind it.
+- Prefer a named standard thickness when the hierarchy is known. Use the
+  compatibility aliases only where their existing semantics are intentional.
+- Thin and ultra-thin surfaces need stable contrast across every part of the
+  content behind them.
 - Use `interactive` only when the material surface itself is the control.
 - Do not animate blur or saturation. Shared motion tokens provide restrained
   press feedback and remove it when reduced motion is requested.

package/src/components/ui/menu-items.md

@@ -0,0 +1,60 @@
+# Menu Items
+
+## Purpose
+
+`menu-items.tsx` is the internal adapter shared by `DropdownMenu` and
+`ContextMenu` when their declarative `items` API is used. It coordinates the
+host-native request and portable fallback, formats shortcut labels, renders
+portable row contents, and removes conflicting authored content.
+
+App code should use `DropdownMenu` or `ContextMenu`, not import these helpers
+directly.
+
+## Declarative usage
+
+```tsx
+import { Button, DropdownMenu, DropdownMenuTrigger } from '@moldable-ai/ui'
+
+;<DropdownMenu
+  items={[
+    {
+      id: 'rename',
+      label: 'Rename',
+      shortcut: { key: 'r', modifiers: ['cmd'] },
+    },
+    { id: 'divider', kind: 'separator' },
+    { id: 'delete', label: 'Move to trash', destructive: true },
+  ]}
+  onSelectItem={(id) => runCommand(id)}
+>
+  <DropdownMenuTrigger asChild>
+    <Button
+      type="button"
+      variant="outline"
+      size="sm"
+      className="cursor-pointer"
+    >
+      Actions
+    </Button>
+  </DropdownMenuTrigger>
+</DropdownMenu>
+```
+
+## Internal contract
+
+- `useDeclarativeMenuState` supports controlled or uncontrolled portable-open
+  state. While a native request is active, `nativeOpen` is true and
+  `portableOpen` is forced false.
+- A completed native request passes `selectedId` to `onSelectItem`.
+  Cancellation does nothing. A fallback result or request failure opens the
+  portable menu unless the caller supplies its own `onFallback`.
+- `formatMenuShortcut` renders modifiers in array order as `⌘`, `⇧`, `⌥`, and
+  `⌃`, then uppercases a one-character key. It is display metadata only.
+- `MenuItemContents` renders an optional Lucide icon, the label, and a `Kbd`
+  shortcut. Separators are handled by the owning menu.
+- Content detection and removal recurse through fragments. When declarative
+  items and authored content are both provided, the owning menu reports the
+  conflict in development and declarative items win.
+
+Keep item IDs stable and labels concise. Do not execute a command from shortcut
+metadata, and do not mix declarative items with authored menu content.