@webjsdev/ui 0.3.7 → 0.3.9

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,9 +27,28 @@
  * 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, onBeforeCache } from '../lib/utils.ts';
+import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // `fixed m-0` opts out of the UA `[popover]` auto-centering margin so

package/packages/registry/components/input.ts

@@ -8,16 +8,18 @@
  * shadcn parity:
  *   Input  → inputClass()
  *
- * Usage:
- *   <input class=${inputClass()} type="email" name="email" id="email" required
- *          aria-describedby="email-hint">
- *
  * Pair with `<label class=${labelClass()} for="...">` and a hint paragraph
  * (`<p class=${hintClass()} id="...-hint">`). Wrap all three in
  * `<div class=${fieldClass()}>` for the canonical field rhythm.
  *
  * Design tokens used: --input, --background, --primary, --primary-foreground,
  * --muted-foreground, --foreground, --ring, --destructive.
+ *
+ * @example
+ * ```html
+ * <input class=${inputClass()} type="email" name="email" id="email" required
+ *        aria-describedby="email-hint">
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/kbd.ts

@@ -6,17 +6,19 @@
  *   Kbd       → kbdClass()
  *   KbdGroup  → kbdGroupClass()
  *
- * Usage:
- *   <kbd class=${kbdClass()}>⌘</kbd>
- *   <kbd class=${kbdClass()}>K</kbd>
+ * Design tokens used: --muted, --muted-foreground, --background.
  *
- *   <div class=${kbdGroupClass()}>
- *     <kbd class=${kbdClass()}>⌘</kbd>
- *     <kbd class=${kbdClass()}>Shift</kbd>
- *     <kbd class=${kbdClass()}>P</kbd>
- *   </div>
+ * @example
+ * ```html
+ * <kbd class=${kbdClass()}>⌘</kbd>
+ * <kbd class=${kbdClass()}>K</kbd>
  *
- * Design tokens used: --muted, --muted-foreground, --background.
+ * <div class=${kbdGroupClass()}>
+ *   <kbd class=${kbdClass()}>⌘</kbd>
+ *   <kbd class=${kbdClass()}>Shift</kbd>
+ *   <kbd class=${kbdClass()}>P</kbd>
+ * </div>
+ * ```
  */
 
 export const kbdClass = (): string =>

package/packages/registry/components/label.ts

@@ -6,15 +6,17 @@
  * shadcn parity:
  *   Label  → labelClass()
  *
- * Usage:
- *   <label class=${labelClass()} for="email">Email</label>
- *   <input class=${inputClass()} id="email" name="email" type="email">
- *
  * Disabled-state inheritance: when the label is inside a container with
  * `data-disabled="true"` (the "field" pattern), or next to a peer-disabled
  * control, it dims automatically.
  *
  * Design tokens used: none (typography only).
+ *
+ * @example
+ * ```html
+ * <label class=${labelClass()} for="email">Email</label>
+ * <input class=${inputClass()} id="email" name="email" type="email">
+ * ```
  */
 
 /** Compose Tailwind classes for a native `<label>`. */

package/packages/registry/components/native-select.ts

@@ -13,16 +13,6 @@
  *                              stylesheet sets Canvas / CanvasText on
  *                              every <option> automatically)
  *
- * Usage:
- *   <div class=${nativeSelectWrapperClass()}>
- *     <select class=${nativeSelectClass()} name="plan">
- *       <option>Basic</option>
- *       <option>Pro</option>
- *     </select>
- *     <!-- chevron icon, decorative -->
- *     <svg class="${nativeSelectIconClass()}" aria-hidden="true">…</svg>
- *   </div>
- *
  * Importing this module installs a stylesheet that forces Canvas /
  * CanvasText on every <option> inside the wrapper so the dropdown reads
  * in both light and dark themes regardless of OS preference; advanced
@@ -30,6 +20,18 @@
  *
  * Design tokens used: --input, --background, --primary, --primary-foreground,
  * --muted-foreground, --ring, --destructive.
+ *
+ * @example
+ * ```html
+ * <div class=${nativeSelectWrapperClass()}>
+ *   <select class=${nativeSelectClass()} name="plan">
+ *     <option>Basic</option>
+ *     <option>Pro</option>
+ *   </select>
+ *   <!-- chevron icon, decorative -->
+ *   <svg class="${nativeSelectIconClass()}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
+ * </div>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/pagination.ts

@@ -12,23 +12,27 @@
  *   PaginationNext       → paginationNextClass()
  *   PaginationEllipsis   → paginationEllipsisClass()
  *
- * Usage:
- *   <nav role="navigation" aria-label="pagination" class=${paginationClass()}>
- *     <ul class=${paginationContentClass()}>
- *       <li><a class=${paginationPreviousClass()} href="?page=1">‹ Previous</a></li>
- *       <li><a class=${paginationLinkClass({ isActive: false })} href="?page=2">2</a></li>
- *       <li><a class=${paginationLinkClass({ isActive: true })} aria-current="page">3</a></li>
- *       <li class=${paginationEllipsisClass()} aria-hidden="true">…</li>
- *       <li><a class=${paginationNextClass()} href="?page=4">Next ›</a></li>
- *     </ul>
- *   </nav>
- *
  * A11y (required for accessible output): wrap the list in <nav
  * aria-label="pagination">, set aria-current="page" on the active page
  * link, give an icon-only Previous / Next control an aria-label, and mark
  * the ellipsis aria-hidden="true". The class helpers emit none of these.
  *
  * Design tokens used: inherited from buttonClass.
+ *
+ * @example
+ * ```html
+ * <nav role="navigation" aria-label="pagination" class=${paginationClass()}>
+ *   <ul class=${paginationContentClass()}>
+ *     <li><a class=${paginationPreviousClass()} href="?page=1">‹ Previous</a></li>
+ *     <li><a class=${paginationLinkClass({ isActive: false })} href="?page=2">2</a></li>
+ *     <li><a class=${paginationLinkClass({ isActive: true })} aria-current="page">3</a></li>
+ *     <li class=${paginationEllipsisClass()} aria-hidden="true">
+ *       <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="1" /><circle cx="19" cy="12" r="1" /><circle cx="5" cy="12" r="1" /></svg>
+ *     </li>
+ *     <li><a class=${paginationNextClass()} href="?page=4">Next ›</a></li>
+ *   </ul>
+ * </nav>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 import { buttonClass, type ButtonSize } from './button.ts';

package/packages/registry/components/popover.ts

@@ -18,28 +18,36 @@
  *   PopoverTitle          → popoverTitleClass()
  *   PopoverDescription    → popoverDescriptionClass()
  *
- * Usage (single invoker, implicit anchor, zero inline style):
- *   <button popovertarget="filter" class=${buttonClass({ variant: 'outline' })}>Filter</button>
- *   <div id="filter" popover
- *        class=${popoverContentClass({ side: 'bottom', align: 'start', sideOffset: 4 })}>
- *     <div class=${popoverHeaderClass()}>
- *       <h3 class=${popoverTitleClass()}>Filter posts</h3>
- *       <p class=${popoverDescriptionClass()}>By tag and status.</p>
- *     </div>
- *   </div>
- *
- *   <!-- Explicit anchor (multiple invokers / anchoring to a different element): -->
- *   <span style="anchor-name: --picker">@vivek</span>
- *   <button popovertarget="profile">Show</button>
- *   <div id="profile" popover style="position-anchor: --picker"
- *        class=${popoverContentClass({ side: 'bottom' })}>…</div>
- *
  * The `positionFloating` helper is also exported (used by the Tier-2
  * tooltip / hover-card / dropdown-menu components for imperative
  * positioning where CSS Anchor Positioning isn't enough). Migrated from
  * the prior <ui-popover> custom element set.
  *
  * Design tokens used: --popover, --popover-foreground, --border.
+ *
+ * @example
+ * ```html
+ * <!-- Single invoker, implicit anchor, zero inline style. -->
+ * <button popovertarget="filter" class=${buttonClass({ variant: 'outline' })}>Filter</button>
+ * <div id="filter" popover
+ *      class=${popoverContentClass({ side: 'bottom', align: 'start', sideOffset: 4 })}>
+ *   <div class=${popoverHeaderClass()}>
+ *     <h3 class=${popoverTitleClass()}>Filter posts</h3>
+ *     <p class=${popoverDescriptionClass()}>By tag and status.</p>
+ *   </div>
+ * </div>
+ *
+ * <!-- Explicit anchor, for multiple invokers or anchoring to a different element. -->
+ * <span style="anchor-name: --picker">@vivek</span>
+ * <button popovertarget="profile">Show</button>
+ * <div id="profile" popover style="position-anchor: --picker"
+ *      class=${popoverContentClass({ side: 'bottom' })}>
+ *   <div class=${popoverHeaderClass()}>
+ *     <h3 class=${popoverTitleClass()}>Vivek Khandelwal</h3>
+ *     <p class=${popoverDescriptionClass()}>@vivek</p>
+ *   </div>
+ * </div>
+ * ```
  */
 
 // --------------------------------------------------------------------------

package/packages/registry/components/progress.ts

@@ -10,18 +10,20 @@
  *                                 `::-webkit-progress-value`, and
  *                                 `::-moz-progress-bar`)
  *
- * Usage:
- *   <progress value="42" max="100" class=${progressClass()}></progress>
- *
- *   <!-- Indeterminate (no `value` attribute): -->
- *   <progress class=${progressClass()}></progress>
- *
  * A11y (required for accessible output): give the <progress> an accessible
  * name with aria-label (or a <label for>), e.g. aria-label="Upload
  * progress". The native element supplies the role and value; only the name
  * is the author's responsibility.
  *
  * Design tokens used: --primary.
+ *
+ * @example
+ * ```html
+ * <progress value="42" max="100" class=${progressClass()}></progress>
+ *
+ * <!-- Indeterminate state, with no value attribute. -->
+ * <progress class=${progressClass()}></progress>
+ * ```
  */
 
 /**

package/packages/registry/components/radio-group.ts

@@ -9,19 +9,21 @@
  *                          → radioGroupClass({ orientation }) on a <div role="radiogroup">
  *   RadioGroupItem         → radioClass() on a native <input type="radio">
  *
- * Usage:
- *   <div role="radiogroup" class=${radioGroupClass()}>
- *     <div class="flex items-center gap-2">
- *       <input type="radio" name="plan" value="basic" id="plan-basic" class=${radioClass()}>
- *       <label class=${labelClass()} for="plan-basic">Basic</label>
- *     </div>
- *     <div class="flex items-center gap-2">
- *       <input type="radio" name="plan" value="pro" id="plan-pro" class=${radioClass()}>
- *       <label class=${labelClass()} for="plan-pro">Pro</label>
- *     </div>
- *   </div>
- *
  * Design tokens used: --input, --primary, --ring, --destructive.
+ *
+ * @example
+ * ```html
+ * <div role="radiogroup" class=${radioGroupClass()}>
+ *   <div class="flex items-center gap-2">
+ *     <input type="radio" name="plan" value="basic" id="plan-basic" class=${radioClass()}>
+ *     <label class=${labelClass()} for="plan-basic">Basic</label>
+ *   </div>
+ *   <div class="flex items-center gap-2">
+ *     <input type="radio" name="plan" value="pro" id="plan-pro" class=${radioClass()}>
+ *     <label class=${labelClass()} for="plan-pro">Pro</label>
+ *   </div>
+ * </div>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/separator.ts

@@ -7,18 +7,20 @@
  *   Separator (orientation: horizontal | vertical, decorative: bool)
  *                          → separatorClass({ orientation }) + role + data-orientation
  *
- * Usage:
- *   <div role="none" class=${separatorClass()} data-orientation="horizontal"></div>
- *   <div role="separator" aria-orientation="vertical"
- *        class=${separatorClass({ orientation: 'vertical' })}
- *        data-orientation="vertical"></div>
- *
  * A11y (required for accessible output): a meaningful divider needs
  * role="separator" plus aria-orientation. A purely decorative one needs
  * role="none" (or aria-hidden="true") so assistive tech does not announce
  * an empty separator.
  *
  * Design tokens used: --border.
+ *
+ * @example
+ * ```html
+ * <div role="none" class=${separatorClass()} data-orientation="horizontal"></div>
+ * <div role="separator" aria-orientation="vertical"
+ *      class=${separatorClass({ orientation: 'vertical' })}
+ *      data-orientation="vertical"></div>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/skeleton.ts

@@ -6,16 +6,18 @@
  * shadcn parity:
  *   Skeleton  → skeletonClass()  (visual: animated rounded muted block)
  *
- * Usage:
- *   <div class=${cn(skeletonClass(), 'h-4 w-32')}></div>
- *   <div class=${cn(skeletonClass(), 'h-12 w-12 rounded-full')}></div>
- *
  * A11y (required for accessible output): a skeleton is a decorative
  * placeholder, so hide it from assistive tech with aria-hidden="true" (or
  * mark the loading region aria-busy="true"). Announce the real content
  * once it replaces the skeleton.
  *
  * Design tokens used: --accent.
+ *
+ * @example
+ * ```html
+ * <div class=${cn(skeletonClass(), 'h-4 w-32')}></div>
+ * <div class=${cn(skeletonClass(), 'h-12 w-12 rounded-full')}></div>
+ * ```
  */
 
 export const skeletonClass = (): string => 'animate-pulse rounded-md bg-accent';

package/packages/registry/components/sonner.ts

@@ -12,18 +12,6 @@
  *                   → toast()  (plus toast.success / .error / .info / .warning /
  *                     .loading / .promise / .dismiss)
  *
- * Usage:
- *   <!-- Mount once at the root of your app (typically in layout.ts): -->
- *   <ui-sonner position="bottom-right"></ui-sonner>
- *
- *   // Then from anywhere (server or client component):
- *   import { toast } from '@/components/ui/sonner.ts';
- *   toast('Saved!');
- *   toast.success('Account created');
- *   toast.error('Failed to save', { description: 'Try again' });
- *   toast.promise(savePost(), { loading: 'Saving…', success: 'Saved', error: 'Failed' });
- *   toast.dismiss(id);
- *
  * Attributes on <ui-sonner>:
  *   `position`: "top-left" | "top-center" | "top-right" |
  *               "bottom-left" | "bottom-center" | "bottom-right" (default).
@@ -42,9 +30,25 @@
  * uses); typically only needed when mounting multiple viewports.
  *
  * Design tokens used: --popover, --popover-foreground, --border, --radius.
+ *
+ * @example
+ * ```html
+ * <!-- Mount once at the root of your app, typically in layout.ts. -->
+ * <ui-sonner position="bottom-right"></ui-sonner>
+ *
+ * <!-- Then from anywhere, in a server or client component, call the API. -->
+ * <script type="module">
+ *   import { toast } from '@/components/ui/sonner.ts';
+ *   toast('Saved!');
+ *   toast.success('Account created');
+ *   toast.error('Failed to save', { description: 'Try again' });
+ *   toast.promise(savePost(), { loading: 'Saving', success: 'Saved', error: 'Failed' });
+ *   toast.dismiss(id);
+ * </script>
+ * ```
  */
 import { WebComponent, html, repeat, unsafeHTML, signal, prop } from '@webjsdev/core';
-import { onBeforeCache } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 
 type ToastType = 'default' | 'success' | 'error' | 'info' | 'warning' | 'loading';
 

package/packages/registry/components/switch.ts

@@ -8,19 +8,21 @@
  *   Switch (size: default | sm)  → switchInputClass() on a hidden <input> +
  *                                   switchTrackClass({ size }) on a sibling <span>
  *
- * Usage:
- *   <label class="inline-flex items-center gap-2">
- *     <input type="checkbox" role="switch" name="notify" class=${switchInputClass()}>
- *     <span class=${switchTrackClass()}></span>
- *     <span class=${labelClass()}>Notifications</span>
- *   </label>
- *
- *   <!-- Small size: -->
- *   <input type="checkbox" role="switch" name="x" class=${cn(switchInputClass(), 'peer/sm')}>
- *   <span class=${switchTrackClass({ size: 'sm' })}></span>
- *
  * Design tokens used: --primary, --input, --background, --foreground, --ring,
  * --primary-foreground.
+ *
+ * @example
+ * ```html
+ * <label class="inline-flex items-center gap-2">
+ *   <input type="checkbox" role="switch" name="notify" class=${switchInputClass()}>
+ *   <span class=${switchTrackClass()}></span>
+ *   <span class=${labelClass()}>Notifications</span>
+ * </label>
+ *
+ * <!-- Small size. -->
+ * <input type="checkbox" role="switch" name="x" class=${cn(switchInputClass(), 'peer/sm')}>
+ * <span class=${switchTrackClass({ size: 'sm' })}></span>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/table.ts

@@ -13,31 +13,33 @@
  *   TableHead / TableCell / TableCaption
  *                                     → tableHeadClass() / tableCellClass() / tableCaptionClass()
  *
- * Usage:
- *   <div class=${tableContainerClass()}>
- *     <table class=${tableClass()}>
- *       <thead class=${tableHeaderClass()}>
- *         <tr class=${tableRowClass()}>
- *           <th scope="col" class=${tableHeadClass()}>Name</th>
- *           <th scope="col" class=${tableHeadClass()}>Status</th>
- *         </tr>
- *       </thead>
- *       <tbody class=${tableBodyClass()}>
- *         <tr class=${tableRowClass()}>
- *           <td class=${tableCellClass()}>Vivek</td>
- *           <td class=${tableCellClass()}>Active</td>
- *         </tr>
- *       </tbody>
- *       <caption class=${tableCaptionClass()}>Users</caption>
- *     </table>
- *   </div>
- *
  * A11y (required for accessible output): every header cell needs a scope
  * (scope="col" on a column header, scope="row" on a row header) so screen
  * readers map cells to their headers. Add a <caption> naming the table's
  * purpose (it can be visually hidden if a heading already names it).
  *
  * Design tokens used: --muted, --muted-foreground, --foreground.
+ *
+ * @example
+ * ```html
+ * <div class=${tableContainerClass()}>
+ *   <table class=${tableClass()}>
+ *     <thead class=${tableHeaderClass()}>
+ *       <tr class=${tableRowClass()}>
+ *         <th scope="col" class=${tableHeadClass()}>Name</th>
+ *         <th scope="col" class=${tableHeadClass()}>Status</th>
+ *       </tr>
+ *     </thead>
+ *     <tbody class=${tableBodyClass()}>
+ *       <tr class=${tableRowClass()}>
+ *         <td class=${tableCellClass()}>Vivek</td>
+ *         <td class=${tableCellClass()}>Active</td>
+ *       </tr>
+ *     </tbody>
+ *     <caption class=${tableCaptionClass()}>Users</caption>
+ *   </table>
+ * </div>
+ * ```
  */
 
 export const tableContainerClass = (): string => 'relative w-full overflow-x-auto';

package/packages/registry/components/tabs.ts

@@ -11,16 +11,6 @@
  *   TabsTrigger    → <ui-tabs-trigger value>
  *   TabsContent    → <ui-tabs-content value>
  *
- * Usage:
- *   <ui-tabs value="account">
- *     <ui-tabs-list>
- *       <ui-tabs-trigger value="account">Account</ui-tabs-trigger>
- *       <ui-tabs-trigger value="password">Password</ui-tabs-trigger>
- *     </ui-tabs-list>
- *     <ui-tabs-content value="account">…</ui-tabs-content>
- *     <ui-tabs-content value="password">…</ui-tabs-content>
- *   </ui-tabs>
- *
  * Attributes on <ui-tabs>:
  *   `value`:       string (reflected, controlled). Active tab value.
  *   `orientation`: "horizontal" (default) | "vertical".
@@ -42,6 +32,22 @@
  *
  * Design tokens used: --muted, --muted-foreground, --foreground, --background,
  * --input, --ring.
+ *
+ * @example
+ * ```html
+ * <ui-tabs value="account">
+ *   <ui-tabs-list>
+ *     <ui-tabs-trigger value="account">Account</ui-tabs-trigger>
+ *     <ui-tabs-trigger value="password">Password</ui-tabs-trigger>
+ *   </ui-tabs-list>
+ *   <ui-tabs-content value="account">
+ *     <p class="text-sm">Update your name and email here.</p>
+ *   </ui-tabs-content>
+ *   <ui-tabs-content value="password">
+ *     <p class="text-sm">Change your password here.</p>
+ *   </ui-tabs-content>
+ * </ui-tabs>
+ * ```
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { cn, ensureId } from '../lib/utils.ts';

package/packages/registry/components/textarea.ts

@@ -6,15 +6,17 @@
  * shadcn parity:
  *   Textarea  → textareaClass()
  *
- * Usage:
- *   <textarea class=${textareaClass()} name="message" rows="4" placeholder="Your message…">
- *   </textarea>
- *
  * Pair with `<label class=${labelClass()} for="...">` and wrap in
  * `<div class=${fieldClass()}>` for the canonical field rhythm.
  *
  * Design tokens used: --input, --background, --muted-foreground, --ring,
  * --destructive.
+ *
+ * @example
+ * ```html
+ * <textarea class=${textareaClass()} name="message" rows="4" placeholder="Your message">
+ * </textarea>
+ * ```
  */
 import { cn } from '../lib/utils.ts';
 

package/packages/registry/components/toggle-group.ts

@@ -12,19 +12,6 @@
  *                                 → <ui-toggle-group type variant size value>
  *   ToggleGroupItem               → <ui-toggle-group-item value>
  *
- * Usage:
- *   <ui-toggle-group type="single" value="bold">
- *     <ui-toggle-group-item value="bold" aria-label="Bold"><b>B</b></ui-toggle-group-item>
- *     <ui-toggle-group-item value="italic" aria-label="Italic"><i>I</i></ui-toggle-group-item>
- *     <ui-toggle-group-item value="underline" aria-label="Underline"><u>U</u></ui-toggle-group-item>
- *   </ui-toggle-group>
- *
- *   <!-- Multiple selection (comma-separated value): -->
- *   <ui-toggle-group type="multiple" value="bold,italic">
- *     <ui-toggle-group-item value="bold">B</ui-toggle-group-item>
- *     <ui-toggle-group-item value="italic">I</ui-toggle-group-item>
- *   </ui-toggle-group>
- *
  * Attributes on <ui-toggle-group>:
  *   `type`:        "single" (default) | "multiple".
  *   `value`:       string. Selected value(s). Single: a single value;
@@ -47,6 +34,21 @@
  *
  * Design tokens used: inherited from toggleClass (--muted, --accent, --ring,
  * --input, --destructive).
+ *
+ * @example
+ * ```html
+ * <ui-toggle-group type="single" value="bold">
+ *   <ui-toggle-group-item value="bold" aria-label="Bold"><b>B</b></ui-toggle-group-item>
+ *   <ui-toggle-group-item value="italic" aria-label="Italic"><i>I</i></ui-toggle-group-item>
+ *   <ui-toggle-group-item value="underline" aria-label="Underline"><u>U</u></ui-toggle-group-item>
+ * </ui-toggle-group>
+ *
+ * <!-- Multiple selection, with a comma-separated value. -->
+ * <ui-toggle-group type="multiple" value="bold,italic">
+ *   <ui-toggle-group-item value="bold">B</ui-toggle-group-item>
+ *   <ui-toggle-group-item value="italic">I</ui-toggle-group-item>
+ * </ui-toggle-group>
+ * ```
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { cn } from '../lib/utils.ts';

package/packages/registry/components/toggle.ts

@@ -10,20 +10,6 @@
  *                                 → toggleClass({ variant, size })  (class helper)
  *                                 → <ui-toggle pressed variant size>  (custom element)
  *
- * Usage (Tier-1 class helper, caller owns state):
- *   <button class=${toggleClass()} data-state="off" aria-pressed="false"
- *           onclick="this.dataset.state = this.dataset.state==='on'?'off':'on'">
- *     <svg>…</svg>
- *   </button>
- *
- * Usage (Tier-2 custom element, state managed):
- *   <ui-toggle aria-label="Toggle bold">
- *     <svg>…</svg>
- *   </ui-toggle>
- *
- *   <!-- Controlled / initial: -->
- *   <ui-toggle variant="outline" size="sm" pressed>B</ui-toggle>
- *
  * Attributes on <ui-toggle>:
  *   `pressed`:  boolean (reflected). Active state.
  *   `variant`:  "default" (default) | "outline".
@@ -37,6 +23,23 @@
  *
  * Design tokens used: --muted, --muted-foreground, --accent, --accent-foreground,
  * --input, --background, --ring, --destructive.
+ *
+ * @example
+ * ```html
+ * <!-- Tier-1 class helper, caller owns state. -->
+ * <button class=${toggleClass()} data-state="off" aria-pressed="false"
+ *         onclick="this.dataset.state = this.dataset.state==='on'?'off':'on'">
+ *   <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M14 12a4 4 0 0 0 0-8H6v8" /><path d="M15 20a4 4 0 0 0 0-8H6v8Z" /></svg>
+ * </button>
+ *
+ * <!-- Tier-2 custom element, state managed. -->
+ * <ui-toggle aria-label="Toggle bold">
+ *   <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M14 12a4 4 0 0 0 0-8H6v8" /><path d="M15 20a4 4 0 0 0 0-8H6v8Z" /></svg>
+ * </ui-toggle>
+ *
+ * <!-- Controlled or initial state. -->
+ * <ui-toggle variant="outline" size="sm" pressed>B</ui-toggle>
+ * ```
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { cn } from '../lib/utils.ts';