@webjsdev/ui 0.3.8 → 0.3.10

package/README.md

@@ -94,17 +94,26 @@ and picks sensible defaults.
 
 Copies the component's `.ts` source into `components/ui/<name>.ts` (or your
 configured alias). Resolves transitive deps via `registryDependencies` and
-auto-installs npm deps like `@floating-ui/dom` for popover-style components.
+auto-installs npm deps like `@floating-ui/dom` for popover-style components. For
+a Tier-1 class-helper component it copies the helpers plus a lean header and a
+one-line pointer, and leaves the worked structural example OUT of the file (get
+it on demand with `webjsui view <name>`). It also self-heals the theme tokens if
+they are missing.
+
+Resolution is LOCAL-FIRST: `init` / `add` / `list` / `view` read the registry
+that ships inside the installed `@webjsdev/ui` package, so they work with no
+network. Point at a custom registry with `--registry <url>`; `webjsui diff`
+always compares against the live upstream.
 
 ## Commands
 
 | Command | Effect |
 |---|---|
-| `webjsui init` | Initialize a project (writes `components.json`, theme CSS, `lib/utils.ts`) |
-| `webjsui add <names...>` | Add components to your project |
+| `webjsui init` | Initialize a project (writes `components.json`, `lib/utils.ts`, the theme tokens). Exits non-zero if the tokens cannot be written. |
+| `webjsui add <names...>` | Add components (copies helpers + a pointer for Tier-1, self-heals theme tokens) |
 | `webjsui list` | List all available components |
-| `webjsui view <name>` | Print a component's source to stdout |
-| `webjsui diff [name]` | Show diff between your local copy and the registry |
+| `webjsui view <name>` | Print a component's projected view (helpers + paste-ready example) and full source |
+| `webjsui diff [name]` | Show diff between your local copy and the live registry |
 | `webjsui info` | Print project diagnostics |
 | `webjsui build` | (For registry authors) Compile a custom registry |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "type": "module",
   "description": "An AI-first component library - class-helper functions for visuals, custom elements only where state matters. Source-copied into your repo, you own it. Works with any Tailwind v4 project.",
   "bin": {
@@ -10,6 +10,7 @@
   "exports": {
     ".": "./src/index.js",
     "./registry/schema": "./src/registry/schema.js",
+    "./registry/extract": "./src/registry/extract.js",
     "./utils": "./src/utils/index.js"
   },
   "files": [

package/packages/registry/components/accordion.ts

@@ -15,21 +15,6 @@
  *   <AccordionTrigger>                    → <summary class=${accordionTriggerClass()}>
  *   <AccordionContent>                    → <div class=${accordionContentClass()}>
  *
- * Usage (single-open, exclusive):
- *   <div class=${accordionClass()}>
- *     <details name="faq" class=${accordionItemClass()}>
- *       <summary class=${accordionTriggerClass()}>
- *         <span>Is it accessible?</span>
- *         <svg class="size-4 transition-transform group-open:rotate-180">…</svg>
- *       </summary>
- *       <div class=${accordionContentClass()}>Yes, native disclosure widget.</div>
- *     </details>
- *     <details name="faq" class=${accordionItemClass()} open>
- *       <summary class=${accordionTriggerClass()}>Is it styled?</summary>
- *       <div class=${accordionContentClass()}>Yes, shadcn design tokens.</div>
- *     </details>
- *   </div>
- *
  * Initial state: add `open` on the <details> that should render expanded
  * on first paint. Programmatic toggling: `el.open = true | false`.
  *
@@ -38,6 +23,26 @@
  * <ui-accordion> custom element set.
  *
  * Design tokens used: --border, --ring, --foreground.
+ *
+ * @example
+ * ```html
+ * <div class=${accordionClass()}>
+ *   <details name="faq" class=${accordionItemClass()} open>
+ *     <summary class=${accordionTriggerClass()}>
+ *       <span>Is it accessible?</span>
+ *       <svg class="size-4 shrink-0 transition-transform group-open:rotate-180" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
+ *     </summary>
+ *     <div class=${accordionContentClass()}>Yes, it uses a native disclosure widget.</div>
+ *   </details>
+ *   <details name="faq" class=${accordionItemClass()}>
+ *     <summary class=${accordionTriggerClass()}>
+ *       <span>Is it styled?</span>
+ *       <svg class="size-4 shrink-0 transition-transform group-open:rotate-180" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
+ *     </summary>
+ *     <div class=${accordionContentClass()}>Yes, with the shadcn design tokens.</div>
+ *   </details>
+ * </div>
+ * ```
  */
 
 /** Root wrapper. Holds the column-of-items rhythm; no display: rules. */

package/packages/registry/components/alert-dialog.ts

@@ -25,23 +25,6 @@
  *   AlertDialogAction        → <ui-alert-dialog-action variant size>
  *   AlertDialogCancel        → <ui-alert-dialog-cancel variant size>
  *
- * Usage:
- *   <ui-alert-dialog>
- *     <ui-alert-dialog-trigger>
- *       <button class=${buttonClass({ variant: 'destructive' })}>Delete</button>
- *     </ui-alert-dialog-trigger>
- *     <ui-alert-dialog-content>
- *       <div class=${alertDialogHeaderClass()}>
- *         <h2 data-slot="alert-dialog-title" class=${alertDialogTitleClass()}>Delete account?</h2>
- *         <p data-slot="alert-dialog-description" class=${alertDialogDescriptionClass()}>This cannot be undone.</p>
- *       </div>
- *       <div class=${alertDialogFooterClass()}>
- *         <ui-alert-dialog-cancel>Cancel</ui-alert-dialog-cancel>
- *         <ui-alert-dialog-action variant="destructive">Delete</ui-alert-dialog-action>
- *       </div>
- *     </ui-alert-dialog-content>
- *   </ui-alert-dialog>
- *
  * Attributes on <ui-alert-dialog>:
  *   `open`:  boolean (reflected). Presence shows the dialog.
  *
@@ -62,6 +45,25 @@
  * Tab cycles trapped within the dialog (native focus trap).
  *
  * Design tokens used: --background, --border, --muted-foreground.
+ *
+ * @example
+ * ```html
+ * <ui-alert-dialog>
+ *   <ui-alert-dialog-trigger>
+ *     <button class=${buttonClass({ variant: 'destructive' })}>Delete</button>
+ *   </ui-alert-dialog-trigger>
+ *   <ui-alert-dialog-content>
+ *     <div class=${alertDialogHeaderClass()}>
+ *       <h2 data-slot="alert-dialog-title" class=${alertDialogTitleClass()}>Delete account?</h2>
+ *       <p data-slot="alert-dialog-description" class=${alertDialogDescriptionClass()}>This cannot be undone.</p>
+ *     </div>
+ *     <div class=${alertDialogFooterClass()}>
+ *       <ui-alert-dialog-cancel>Cancel</ui-alert-dialog-cancel>
+ *       <ui-alert-dialog-action variant="destructive">Delete</ui-alert-dialog-action>
+ *     </div>
+ *   </ui-alert-dialog-content>
+ * </ui-alert-dialog>
+ * ```
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';

package/packages/registry/components/alert.ts

@@ -7,30 +7,32 @@
  *   AlertTitle                              → alertTitleClass()
  *   AlertDescription                        → alertDescriptionClass()
  *
- * Usage:
- *   <div role="alert" class=${alertClass()}>
- *     <svg>…</svg>
- *     <div data-slot="alert-title" class=${alertTitleClass()}>Heads up</div>
- *     <div data-slot="alert-description" class=${alertDescriptionClass()}>
- *       Something happened. Probably fine.
- *     </div>
- *   </div>
- *
- *   <!-- Destructive variant: accent stripe + colored title/description. -->
- *   <div role="alert" class=${alertClass({ variant: 'destructive' })}>
- *     <svg>…</svg>
- *     <div data-slot="alert-title" class=${alertTitleClass()}>Failed</div>
- *     <div data-slot="alert-description" class=${alertDescriptionClass()}>
- *       Couldn't save your changes.
- *     </div>
- *   </div>
- *
  * A11y (required for accessible output): put role="alert" on the container
  * for an urgent, interrupting message, or role="status" for a polite,
  * non-urgent update. The class helper sets no role, so without one the
  * banner is silent to assistive tech.
  *
  * Design tokens used: --card, --card-foreground, --destructive, --muted-foreground.
+ *
+ * @example
+ * ```html
+ * <div role="alert" class=${alertClass()}>
+ *   <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><circle cx="12" cy="12" r="10" /><path d="M12 16v-4M12 8h.01" /></svg>
+ *   <div data-slot="alert-title" class=${alertTitleClass()}>Heads up</div>
+ *   <div data-slot="alert-description" class=${alertDescriptionClass()}>
+ *     Something happened. Probably fine.
+ *   </div>
+ * </div>
+ *
+ * <!-- Destructive variant: accent stripe plus colored title and description. -->
+ * <div role="alert" class=${alertClass({ variant: 'destructive' })}>
+ *   <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" /><path d="M12 9v4M12 17h.01" /></svg>
+ *   <div data-slot="alert-title" class=${alertTitleClass()}>Failed</div>
+ *   <div data-slot="alert-description" class=${alertDescriptionClass()}>
+ *     Couldn't save your changes.
+ *   </div>
+ * </div>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/aspect-ratio.ts

@@ -6,17 +6,19 @@
  * shadcn parity:
  *   AspectRatio (Radix primitive)  → aspectRatioClass() + inline `aspect-ratio` style
  *
- * Usage:
- *   <div style="aspect-ratio: 16/9;" class="${aspectRatioClass()}">
- *     <img src="…" class="h-full w-full object-cover rounded-md">
- *   </div>
+ * Design tokens used: none (layout only).
  *
- *   <!-- Or with Tailwind's arbitrary aspect-ratio (no helper needed): -->
- *   <div class="aspect-[16/9]">
- *     <img …>
- *   </div>
+ * @example
+ * ```html
+ * <div style="aspect-ratio: 16/9;" class="${aspectRatioClass()}">
+ *   <img src="/hero.jpg" alt="Team offsite" class="h-full w-full object-cover rounded-md">
+ * </div>
  *
- * Design tokens used: none (layout only).
+ * <!-- Or with Tailwind's arbitrary aspect-ratio (no helper needed): -->
+ * <div class="aspect-[16/9]">
+ *   <img src="/hero.jpg" alt="Team offsite" class="h-full w-full object-cover rounded-md">
+ * </div>
+ * ```
  */
 
 export const aspectRatioClass = (): string => 'relative w-full';

package/packages/registry/components/avatar.ts

@@ -11,24 +11,32 @@
  *   AvatarGroup                       → avatarGroupClass()
  *   AvatarGroupCount                  → avatarGroupCountClass()
  *
- * Usage:
- *   <span class=${avatarClass()} data-size="default" data-slot="avatar">
- *     <img class=${avatarImageClass()} src="…" alt="…">
- *     <span class=${avatarFallbackClass()}>VK</span>
- *   </span>
- *
- *   <div class=${avatarGroupClass()}>
- *     <span class=${avatarClass()} data-size="default" data-slot="avatar">…</span>
- *     <span class=${avatarClass()} data-size="default" data-slot="avatar">…</span>
- *     <div class=${avatarGroupCountClass()}>+3</div>
- *   </div>
- *
  * A11y (required for accessible output): the <img> MUST have an alt that
  * names the person (alt="Vivek Khandelwal"), or alt="" when a visible text
  * fallback already names them. Always provide the fallback <span> so the
  * avatar is still named if the image fails to load.
  *
  * Design tokens used: --muted, --muted-foreground, --primary, --background.
+ *
+ * @example
+ * ```html
+ * <span class=${avatarClass()} data-size="default" data-slot="avatar">
+ *   <img class=${avatarImageClass()} src="/avatars/vivek.jpg" alt="Vivek Khandelwal">
+ *   <span class=${avatarFallbackClass()}>VK</span>
+ * </span>
+ *
+ * <div class=${avatarGroupClass()}>
+ *   <span class=${avatarClass()} data-size="default" data-slot="avatar">
+ *     <img class=${avatarImageClass()} src="/avatars/vivek.jpg" alt="Vivek Khandelwal">
+ *     <span class=${avatarFallbackClass()}>VK</span>
+ *   </span>
+ *   <span class=${avatarClass()} data-size="default" data-slot="avatar">
+ *     <img class=${avatarImageClass()} src="/avatars/amir.jpg" alt="Amir Rao">
+ *     <span class=${avatarFallbackClass()}>AR</span>
+ *   </span>
+ *   <div class=${avatarGroupCountClass()}>+3</div>
+ * </div>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/badge.ts

@@ -6,11 +6,6 @@
  *   Badge (variant: default | secondary | destructive | outline | ghost | link)
  *                                  → badgeClass({ variant })
  *
- * Usage:
- *   <span class=${badgeClass()}>New</span>
- *   <span class=${badgeClass({ variant: 'destructive' })}>Error</span>
- *   <a    class=${badgeClass({ variant: 'link' })} href="/profile">@vivek</a>
- *
  * The `[a&]:hover:...` hover styles only apply when the element is an `<a>`,
  * so a static `<span>` doesn't pick up an unwanted hover.
  *
@@ -20,6 +15,13 @@
  *
  * Design tokens used: --primary, --secondary, --destructive, --foreground,
  * --accent, --border, --ring.
+ *
+ * @example
+ * ```html
+ * <span class=${badgeClass()}>New</span>
+ * <span class=${badgeClass({ variant: 'destructive' })}>Error</span>
+ * <a class=${badgeClass({ variant: 'link' })} href="/profile">@vivek</a>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/breadcrumb.ts

@@ -11,27 +11,29 @@
  *   BreadcrumbSeparator  → breadcrumbSeparatorClass() (aria-hidden + role="presentation")
  *   BreadcrumbEllipsis   → breadcrumbEllipsisClass()
  *
- * Usage:
- *   <nav aria-label="breadcrumb" data-slot="breadcrumb">
- *     <ol class=${breadcrumbListClass()}>
- *       <li class=${breadcrumbItemClass()}>
- *         <a class=${breadcrumbLinkClass()} href="/">Home</a>
- *       </li>
- *       <li class=${breadcrumbSeparatorClass()} role="presentation" aria-hidden="true">
- *         <svg>›</svg>
- *       </li>
- *       <li class=${breadcrumbItemClass()}>
- *         <span class=${breadcrumbPageClass()} aria-current="page">Posts</span>
- *       </li>
- *     </ol>
- *   </nav>
- *
  * A11y (required for accessible output): wrap the list in <nav
  * aria-label="breadcrumb">, set aria-current="page" on the current-page
  * element, and mark each separator role="presentation" aria-hidden="true".
  * The class helpers emit none of these.
  *
  * Design tokens used: --muted-foreground, --foreground.
+ *
+ * @example
+ * ```html
+ * <nav aria-label="breadcrumb" data-slot="breadcrumb">
+ *   <ol class=${breadcrumbListClass()}>
+ *     <li class=${breadcrumbItemClass()}>
+ *       <a class=${breadcrumbLinkClass()} href="/">Home</a>
+ *     </li>
+ *     <li class=${breadcrumbSeparatorClass()} role="presentation" aria-hidden="true">
+ *       <svg class="size-3.5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg>
+ *     </li>
+ *     <li class=${breadcrumbItemClass()}>
+ *       <span class=${breadcrumbPageClass()} aria-current="page">Posts</span>
+ *     </li>
+ *   </ol>
+ * </nav>
+ * ```
  */
 
 export const breadcrumbListClass = (): string =>

package/packages/registry/components/button.ts

@@ -8,12 +8,6 @@
  *         (size:    default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg)
  *                                            → buttonClass({ variant, size })
  *
- * Usage:
- *   <button class=${buttonClass()} type="submit">Save</button>
- *   <button class=${buttonClass({ variant: 'outline', size: 'sm' })}>Cancel</button>
- *   <button class=${buttonClass({ size: 'icon' })} aria-label="Settings">⚙</button>
- *   <a       class=${buttonClass({ variant: 'link' })} href="/about">About</a>
- *
  * shadcn React's `asChild` (Slot) prop has no equivalent here: just call
  * `buttonClass(...)` and spread the classes onto whatever element you want.
  *
@@ -26,6 +20,14 @@
  * Design tokens used: --primary, --primary-foreground, --destructive,
  * --secondary, --secondary-foreground, --accent, --accent-foreground,
  * --background, --input, --ring.
+ *
+ * @example
+ * ```html
+ * <button class=${buttonClass()} type="submit">Save</button>
+ * <button class=${buttonClass({ variant: 'outline', size: 'sm' })}>Cancel</button>
+ * <button class=${buttonClass({ size: 'icon' })} aria-label="Settings">⚙</button>
+ * <a class=${buttonClass({ variant: 'link' })} href="/about">About</a>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/card.ts

@@ -11,22 +11,26 @@
  *   CardContent                → cardContentClass()
  *   CardFooter                 → cardFooterClass()
  *
- * Usage:
- *   <div class=${cardClass()}>
- *     <div class=${cardHeaderClass()}>
- *       <div class=${cardTitleClass()}>Notifications</div>
- *       <div class=${cardDescriptionClass()}>You have 3 unread messages.</div>
- *       <div class=${cardActionClass()}>
- *         <button class=${buttonClass({ variant: 'ghost', size: 'sm' })}>Mark all read</button>
- *       </div>
- *     </div>
- *     <div class=${cardContentClass()}>…</div>
- *     <div class=${cardFooterClass()}>
- *       <button class=${buttonClass()}>Save</button>
+ * Design tokens used: --card, --card-foreground, --muted-foreground, --border.
+ *
+ * @example
+ * ```html
+ * <div class=${cardClass()}>
+ *   <div class=${cardHeaderClass()}>
+ *     <div class=${cardTitleClass()}>Notifications</div>
+ *     <div class=${cardDescriptionClass()}>You have 3 unread messages.</div>
+ *     <div class=${cardActionClass()}>
+ *       <button class=${buttonClass({ variant: 'ghost', size: 'sm' })}>Mark all read</button>
  *     </div>
  *   </div>
- *
- * Design tokens used: --card, --card-foreground, --muted-foreground, --border.
+ *   <div class=${cardContentClass()}>
+ *     <p class="text-sm">Your weekly digest is ready to review.</p>
+ *   </div>
+ *   <div class=${cardFooterClass()}>
+ *     <button class=${buttonClass()}>Save</button>
+ *   </div>
+ * </div>
+ * ```
  */
 
 export type CardSize = 'default' | 'sm';

package/packages/registry/components/checkbox.ts

@@ -9,12 +9,14 @@
  *                                 when checked, inset shadow, focus ring;
  *                                 bypasses Radix)
  *
- * Usage:
- *   <input type="checkbox" name="terms" id="terms" class=${checkboxClass()}>
- *   <label class=${labelClass()} for="terms">I accept the terms</label>
- *
  * Design tokens used: --input, --primary, --primary-foreground, --background,
  * --ring, --destructive.
+ *
+ * @example
+ * ```html
+ * <input type="checkbox" name="terms" id="terms" class=${checkboxClass()}>
+ * <label class=${labelClass()} for="terms">I accept the terms</label>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/collapsible.ts

@@ -10,24 +10,26 @@
  *   CollapsibleTrigger  → <summary class=${collapsibleTriggerClass()}>
  *   CollapsibleContent  → <div class=${collapsibleContentClass()}>
  *
- * Usage:
- *   <details class=${collapsibleClass()}>
- *     <summary class=${collapsibleTriggerClass()}>
- *       Show details
- *       <svg class="size-4 transition-transform group-open:rotate-180">…</svg>
- *     </summary>
- *     <div class=${collapsibleContentClass()}>
- *       Hidden until <summary> is clicked, Enter / Space pressed, or the
- *       <details> element's `open` property is set via JS.
- *     </div>
- *   </details>
- *
  * Initial state: add `open` on <details> to render expanded on first
  * paint. Programmatic toggling: `el.open = true | false`. Migrated from
  * the prior <ui-collapsible> custom element; the trigger class hides
  * the native disclosure marker so callers can render their own chevron.
  *
  * Design tokens used: --border, --ring, --foreground.
+ *
+ * @example
+ * ```html
+ * <details class=${collapsibleClass()}>
+ *   <summary class=${collapsibleTriggerClass()}>
+ *     Show details
+ *     <svg class="size-4 transition-transform group-open:rotate-180" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
+ *   </summary>
+ *   <div class=${collapsibleContentClass()}>
+ *     Hidden until <summary> is clicked, Enter / Space pressed, or the
+ *     <details> element's `open` property is set via JS.
+ *   </div>
+ * </details>
+ * ```
  */
 
 /**

package/packages/registry/components/dialog.ts

@@ -22,30 +22,6 @@
  *   DialogDescription  → <p class=${dialogDescriptionClass()}>
  *   DialogFooter       → <div class=${dialogFooterClass()}>
  *
- * Usage:
- *   <ui-dialog>
- *     <ui-dialog-trigger>
- *       <button class=${buttonClass({ variant: 'outline' })}>Edit profile</button>
- *     </ui-dialog-trigger>
- *     <ui-dialog-content>
- *       <div class=${dialogHeaderClass()}>
- *         <h2 data-slot="dialog-title" class=${dialogTitleClass()}>Edit profile</h2>
- *         <p data-slot="dialog-description" class=${dialogDescriptionClass()}>Make changes and click save.</p>
- *       </div>
- *       <div class="grid gap-3">
- *         <label class=${labelClass()} for="dlg-name">Name</label>
- *         <input class=${inputClass()} id="dlg-name" placeholder="Your name">
- *       </div>
- *       <div class=${dialogFooterClass()}>
- *         <ui-dialog-close><button class=${buttonClass({ variant: 'outline' })}>Cancel</button></ui-dialog-close>
- *         <button class=${buttonClass()}>Save</button>
- *       </div>
- *     </ui-dialog-content>
- *   </ui-dialog>
- *
- *   <!-- Suppress the auto-injected top-right X close: -->
- *   <ui-dialog-content show-close-button="false">…</ui-dialog-content>
- *
  * Attributes on <ui-dialog>:
  *   `open`:  boolean (reflected). Presence shows the dialog.
  *
@@ -62,6 +38,36 @@
  * within the dialog (native focus trap).
  *
  * Design tokens used: --background, --border, --muted-foreground.
+ *
+ * @example
+ * ```html
+ * <ui-dialog>
+ *   <ui-dialog-trigger>
+ *     <button class=${buttonClass({ variant: 'outline' })}>Edit profile</button>
+ *   </ui-dialog-trigger>
+ *   <ui-dialog-content>
+ *     <div class=${dialogHeaderClass()}>
+ *       <h2 data-slot="dialog-title" class=${dialogTitleClass()}>Edit profile</h2>
+ *       <p data-slot="dialog-description" class=${dialogDescriptionClass()}>Make changes and click save.</p>
+ *     </div>
+ *     <div class="grid gap-3">
+ *       <label class=${labelClass()} for="dlg-name">Name</label>
+ *       <input class=${inputClass()} id="dlg-name" placeholder="Your name">
+ *     </div>
+ *     <div class=${dialogFooterClass()}>
+ *       <ui-dialog-close><button class=${buttonClass({ variant: 'outline' })}>Cancel</button></ui-dialog-close>
+ *       <button class=${buttonClass()}>Save</button>
+ *     </div>
+ *   </ui-dialog-content>
+ * </ui-dialog>
+ *
+ * <!-- Suppress the auto-injected top-right X close button. -->
+ * <ui-dialog-content show-close-button="false">
+ *   <div class=${dialogHeaderClass()}>
+ *     <h2 data-slot="dialog-title" class=${dialogTitleClass()}>Quiet dialog</h2>
+ *   </div>
+ * </ui-dialog-content>
+ * ```
  */
 import { WebComponent, html, unsafeHTML, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';

package/packages/registry/components/dropdown-menu.ts

@@ -20,26 +20,6 @@
  *   DropdownMenuSubTrigger    → <ui-dropdown-menu-sub-trigger inset>
  *   DropdownMenuSubContent    → <ui-dropdown-menu-sub-content>
  *
- * Usage:
- *   <ui-dropdown-menu>
- *     <ui-dropdown-menu-trigger>
- *       <button class=${buttonClass({ variant: 'outline' })}>Options</button>
- *     </ui-dropdown-menu-trigger>
- *     <ui-dropdown-menu-content align="end">
- *       <ui-dropdown-menu-label>My Account</ui-dropdown-menu-label>
- *       <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
- *       <ui-dropdown-menu-item>Profile</ui-dropdown-menu-item>
- *       <ui-dropdown-menu-sub>
- *         <ui-dropdown-menu-sub-trigger>Invite users</ui-dropdown-menu-sub-trigger>
- *         <ui-dropdown-menu-sub-content>
- *           <ui-dropdown-menu-item>Email</ui-dropdown-menu-item>
- *         </ui-dropdown-menu-sub-content>
- *       </ui-dropdown-menu-sub>
- *       <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
- *       <ui-dropdown-menu-item variant="destructive">Sign out</ui-dropdown-menu-item>
- *     </ui-dropdown-menu-content>
- *   </ui-dropdown-menu>
- *
  * Attributes on <ui-dropdown-menu>:
  *   `open`:  boolean (reflected). Open state.
  *
@@ -76,6 +56,28 @@
  *
  * Design tokens used: --popover, --popover-foreground, --accent,
  * --accent-foreground, --destructive, --muted-foreground, --border.
+ *
+ * @example
+ * ```html
+ * <ui-dropdown-menu>
+ *   <ui-dropdown-menu-trigger>
+ *     <button class=${buttonClass({ variant: 'outline' })}>Options</button>
+ *   </ui-dropdown-menu-trigger>
+ *   <ui-dropdown-menu-content align="end">
+ *     <ui-dropdown-menu-label>My Account</ui-dropdown-menu-label>
+ *     <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
+ *     <ui-dropdown-menu-item>Profile</ui-dropdown-menu-item>
+ *     <ui-dropdown-menu-sub>
+ *       <ui-dropdown-menu-sub-trigger>Invite users</ui-dropdown-menu-sub-trigger>
+ *       <ui-dropdown-menu-sub-content>
+ *         <ui-dropdown-menu-item>Email</ui-dropdown-menu-item>
+ *       </ui-dropdown-menu-sub-content>
+ *     </ui-dropdown-menu-sub>
+ *     <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
+ *     <ui-dropdown-menu-item variant="destructive">Sign out</ui-dropdown-menu-item>
+ *   </ui-dropdown-menu-content>
+ * </ui-dropdown-menu>
+ * ```
  */
 import { WebComponent, html, unsafeHTML, signal, prop } from '@webjsdev/core';
 import { ensureId } from '../lib/utils.ts';

package/packages/registry/components/hover-card.ts

@@ -9,16 +9,6 @@
  *   HoverCardTrigger   → <ui-hover-card-trigger>
  *   HoverCardContent   → <ui-hover-card-content side align side-offset align-offset>
  *
- * Usage:
- *   <ui-hover-card open-delay="700" close-delay="300">
- *     <ui-hover-card-trigger>
- *       <a href="/user/vivek">@vivek</a>
- *     </ui-hover-card-trigger>
- *     <ui-hover-card-content>
- *       <div class="flex gap-3">…</div>
- *     </ui-hover-card-content>
- *   </ui-hover-card>
- *
  * Attributes on <ui-hover-card>:
  *   `open`:        boolean (reflected). Open state.
  *   `open-delay`:  ms, default 700. Hover delay before opening.
@@ -37,6 +27,24 @@
  * Programmatic API on <ui-hover-card>: `.show()` · `.hide()`.
  *
  * Design tokens used: --popover, --popover-foreground, --border.
+ *
+ * @example
+ * ```html
+ * <ui-hover-card open-delay="700" close-delay="300">
+ *   <ui-hover-card-trigger>
+ *     <a href="/user/vivek">@vivek</a>
+ *   </ui-hover-card-trigger>
+ *   <ui-hover-card-content>
+ *     <div class="flex gap-3">
+ *       <img class="size-10 rounded-full" src="/avatars/vivek.jpg" alt="Vivek Khandelwal">
+ *       <div>
+ *         <div class="text-sm font-semibold">Vivek Khandelwal</div>
+ *         <p class="text-sm text-muted-foreground">Builds the platform, not against it.</p>
+ *       </div>
+ *     </div>
+ *   </ui-hover-card-content>
+ * </ui-hover-card>
+ * ```
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { ensureId } from '../lib/utils.ts';