@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/drawer/drawer.svelte

@@ -17,14 +17,13 @@
 
 <script lang="ts">
   import type { DrawerProps } from './drawer.types.ts';
-  import { onDestroy, tick } from 'svelte';
+  import { onDestroy } from 'svelte';
 
-  import { captureFocus, lockBodyScroll, pushEscapeHandler } from '../../_internal/overlay.ts';
-  import { waitForTransitionCompletion } from '../../_internal/transition-completion.ts';
   import { overflowFade } from '../../utilities/attachments.ts';
   import { classNames } from '../../utilities/class-names.ts';
-  import { restoreFocusTo } from '../../utilities/focus.ts';
+  import { createFocusTrap } from '../focus-trap/index.ts';
   import { useReducedMotion } from '../../utilities/use-reduced-motion.svelte.ts';
+  import { createSlidingDialogState } from '../_internal/create-sliding-dialog-state.svelte.ts';
 
   let {
     open = $bindable(false),
@@ -43,13 +42,7 @@
   const titleId = $props.id();
 
   let dialogElement: HTMLDialogElement | undefined = $state();
-  let bodyElement: HTMLDivElement | undefined = $state();
   let panelElement: HTMLDivElement | undefined = $state();
-  let hydrated = $state(false);
-  let renderPanel = $state(open);
-  let isClosing = $state(false);
-  let closeGeneration = $state(0);
-  let pendingOpenFocus = $state(false);
   /**
    * The side that was active when the current open/close cycle began.
    * Snapshotted at open time so that a side-prop change while the drawer
@@ -58,196 +51,89 @@
    */
   let activeSide = $state(side);
 
-  let capturedFocus: HTMLElement | null = null;
-  let releaseScrollLock: (() => void) | null = null;
-  let releaseEscape: (() => void) | null = null;
-  let cancelPendingClose: (() => void) | null = null;
-
   const reducedMotion = useReducedMotion();
   const bodyOverflowFade = overflowFade();
-
-  function acquireScrollLock(): void {
-    if (releaseScrollLock) return;
-    releaseScrollLock = lockBodyScroll();
-  }
-
-  function acquireEscapeMarker(): void {
-    if (releaseEscape) return;
-    // No-op handler: presence marker so stacked non-dialog overlays
-    // route ESC to themselves. Native <dialog> owns the actual ESC close.
-    releaseEscape = pushEscapeHandler(() => {});
-  }
+  const dialogState = createSlidingDialogState({
+    getOpen: () => open,
+    setOpen: (nextOpen) => {
+      open = nextOpen;
+    },
+    getDialogElement: () => dialogElement,
+    getPanelElement: () => panelElement,
+    getReducedMotion: () => reducedMotion.current,
+    getTriggerRef: () => triggerRef,
+  });
 
   $effect(() => {
-    hydrated = true;
+    dialogState.markHydrated();
   });
 
   $effect(() => {
-    if (!dialogElement) return;
     if (open) {
-      if (isClosing) {
+      if (dialogState.isClosing) {
         // Quick-reopen while a close transition is still running.
         // Snapshot the current side so the reversal / re-entry animation
         // uses the side the user expects for this new open intent.
         activeSide = side;
-        closeGeneration += 1;
-        cancelPendingClose?.();
-        cancelPendingClose = null;
-        isClosing = false;
       }
 
-      if (!renderPanel) {
+      if (!dialogState.renderPanel) {
         // Fresh mount — snapshot the side for this open cycle so any later
         // side-prop change while open or closing does not flip the direction.
         activeSide = side;
-        renderPanel = true;
-      }
-
-      if (!dialogElement.open) {
-        capturedFocus = captureFocus();
-        pendingOpenFocus = true;
-        dialogElement.showModal();
-        acquireScrollLock();
-        acquireEscapeMarker();
       }
-      return;
-    }
-
-    if (dialogElement.open) {
-      beginClosing();
-    } else {
-      renderPanel = false;
-      pendingOpenFocus = false;
     }
+    dialogState.syncOpenState();
   });
 
-  $effect(() => {
-    if (!pendingOpenFocus || !dialogElement?.open) return;
-    pendingOpenFocus = false;
-    void tick().then(() => {
-      if (!open || !dialogElement?.open) return;
-      const hasExplicitAutofocus =
-        dialogElement.querySelector('[autofocus]') !== null ||
-        Array.from(dialogElement.querySelectorAll<HTMLElement>('*')).some(
-          (element) => element.autofocus === true,
-        );
-      if (!hasExplicitAutofocus && bodyElement) {
-        bodyElement.focus();
-      }
-    });
-  });
-
-  function beginClosing(): void {
-    if (!dialogElement?.open || isClosing) return;
-    if (!panelElement) {
-      finishClosing(closeGeneration);
-      return;
-    }
-
-    isClosing = true;
-    const generation = ++closeGeneration;
-    cancelPendingClose?.();
-    cancelPendingClose = waitForTransitionCompletion({
-      element: panelElement,
-      reducedMotion: reducedMotion.current,
-      onComplete: () => finishClosing(generation),
-    });
-  }
-
-  function finishClosing(generation: number): void {
-    if (generation !== closeGeneration) return;
-    cancelPendingClose?.();
-    cancelPendingClose = null;
-    isClosing = false;
-    renderPanel = false;
-    pendingOpenFocus = false;
-    if (dialogElement?.open) {
-      dialogElement.close();
-    }
-  }
-
-  function handleClose() {
-    if (releaseScrollLock) {
-      releaseScrollLock();
-      releaseScrollLock = null;
-    }
-    if (releaseEscape) {
-      releaseEscape();
-      releaseEscape = null;
-    }
-    open = false;
-    returnFocus();
-  }
-
-  function requestClose(): void {
-    if (!open && (isClosing || !dialogElement?.open)) return;
-    open = false;
-    beginClosing();
-  }
-
-  // Iterate candidates so a disconnected `triggerRef` falls through to the
-  // captured pre-open focus. Matches modal/sheet/popover/command-palette.
-  function returnFocus(): void {
-    const candidates: Array<HTMLElement | null> = [triggerRef, capturedFocus];
-    for (const candidate of candidates) {
-      if (restoreFocusTo(candidate)) break;
-    }
-    capturedFocus = null;
-  }
-
-  function handleNativeCancel(event: Event) {
-    // The browser's native ESC handler on <dialog> fires `cancel` then closes
-    // the dialog. preventDefault keeps the close out of the native path so it
-    // goes through `dialogElement.close()` here — which fires the `close`
-    // event and lets handleClose() run as the single canonical close path.
-    // This matches modal.svelte's pattern; without it, ESC would close the
-    // dialog out from under Svelte's `open` state for one tick.
-    event.preventDefault();
-    requestClose();
-  }
-
-  function handleBackdropClick(event: MouseEvent) {
-    if (event.target === dialogElement) {
-      requestClose();
-    }
+  /**
+   * Resolve the drawer's initial focus target for the shared focus trap.
+   *
+   * When the consumer marked a child with `autofocus`, the native <dialog>
+   * already focused it — honour that by handing the element back so the trap
+   * does not steal focus to the first tabbable. Otherwise return `null`, which
+   * lets `createFocusTrap` fall through to the first tabbable element inside the
+   * drawer — typically the close button. (The Drawer passes no `fallbackFocus`,
+   * so when there is nothing tabbable the trap focuses the trap root itself;
+   * unlike Modal/Sheet, the Drawer does not opt into host-managed body focus.)
+   * This replaces the prior ad-hoc selector, which accepted any `[tabindex]`
+   * other than `-1` (e.g. `-2`) and CSS-hidden elements that are not
+   * Tab-reachable.
+   */
+  function resolveInitialFocus(): HTMLElement | null {
+    if (!dialogElement) return null;
+    const explicitlyAutofocused =
+      dialogElement.querySelector<HTMLElement>('[autofocus]') ??
+      Array.from(dialogElement.querySelectorAll<HTMLElement>('*')).find(
+        (element) => element.autofocus === true,
+      ) ??
+      null;
+    return explicitlyAutofocused;
   }
 
   onDestroy(() => {
-    cancelPendingClose?.();
-    cancelPendingClose = null;
-    const wasOpen = releaseScrollLock !== null || releaseEscape !== null;
-    if (releaseScrollLock) {
-      releaseScrollLock();
-      releaseScrollLock = null;
-    }
-    if (releaseEscape) {
-      releaseEscape();
-      releaseEscape = null;
-    }
-    if (wasOpen) {
-      returnFocus();
-    }
+    dialogState.destroy();
   });
 </script>
 
-{#if hydrated}
+{#if dialogState.hydrated}
   <dialog
     {...rest}
     bind:this={dialogElement}
     class={classNames('cinder-drawer', className)}
     aria-modal="true"
     aria-labelledby={ariaLabelledBy ?? titleId}
-    data-cinder-closing={isClosing ? '' : undefined}
-    onclose={handleClose}
-    oncancel={handleNativeCancel}
-    onclick={handleBackdropClick}
+    data-cinder-closing={dialogState.isClosing ? '' : undefined}
+    onclose={() => dialogState.handleClose()}
+    oncancel={(event) => dialogState.handleNativeCancel(event)}
+    onclick={(event) => dialogState.handleBackdropClick(event)}
   >
     {#snippet closeButton()}
       <button
         type="button"
         class="cinder-drawer__close"
         aria-label="Close drawer"
-        onclick={requestClose}
+        onclick={() => dialogState.requestClose()}
       >
         <svg
           class="cinder-drawer__close-icon"
@@ -263,14 +149,26 @@
       </button>
     {/snippet}
 
-    {#if renderPanel}
+    {#if dialogState.renderPanel}
+      <!--
+        The native <dialog> (showModal) traps focus in supporting browsers; the
+        shared focus-trap is the defence-in-depth fallback and owns initial focus.
+        It carefully filters hidden/inert/disabled/`tabindex="-1"` elements, so it
+        replaces the prior ad-hoc selector. Drawer owns focus restoration
+        (returnFocus), so the trap runs with `restoreFocus: false`.
+      -->
       <div
         bind:this={panelElement}
         class="cinder-drawer__panel"
         data-cinder-side={activeSide}
         data-cinder-size={size}
-        data-cinder-closing={isClosing ? '' : undefined}
-        inert={isClosing}
+        data-cinder-closing={dialogState.isClosing ? '' : undefined}
+        inert={dialogState.isClosing}
+        {@attach createFocusTrap({
+          active: () => open && !dialogState.isClosing,
+          restoreFocus: false,
+          initialFocus: resolveInitialFocus,
+        })}
       >
         <header class="cinder-drawer__header">
           {#if header}
@@ -284,12 +182,7 @@
           {@render closeButton()}
         </header>
 
-        <div
-          bind:this={bodyElement}
-          class="cinder-drawer__body"
-          tabindex="-1"
-          {@attach bodyOverflowFade}
-        >
+        <div class="cinder-drawer__body" tabindex="-1" {@attach bodyOverflowFade}>
           {@render children()}
         </div>
 

package/src/components/dropdown/README.md

@@ -35,10 +35,10 @@ The leaves remain importable individually for à-la-carte builds — see
 
 | Prop        | Type                               | Required | Default | Description                                                                                                                |
 | ----------- | ---------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`     | `string`                           | no       | —       |                                                                                                                            |
-| `id`        | `string`                           | no       | —       |                                                                                                                            |
-| `open`      | `boolean`                          | no       | —       |                                                                                                                            |
-| `placement` | `"bottom-start"` \| `"bottom-end"` | no       | —       |                                                                                                                            |
+| `class`     | `string`                           | no       | —       | Additional class names merged with the component's root class.                                                             |
+| `id`        | `string`                           | no       | —       | HTML id applied to the dropdown root element. Auto-generated when omitted.                                                 |
+| `open`      | `boolean`                          | no       | —       | Controls the open state of the dropdown menu; bindable for controlled usage.                                               |
+| `placement` | `"bottom-start"` \| `"bottom-end"` | no       | —       | Preferred side of the trigger on which the menu opens. Default `bottom-start`.                                             |
 | `children`  | `(opaque)`                         | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `trigger`   | `(opaque)`                         | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 

package/src/components/dropdown/dropdown.css

@@ -93,7 +93,7 @@
     border-radius: var(--cinder-radius-md);
     background: var(--cinder-surface-raised);
     color: var(--cinder-text);
-    box-shadow: var(--cinder-shadow-lg);
+    box-shadow: var(--cinder-shadow-overlay);
   }
 
   .cinder-dropdown__menu {
@@ -265,10 +265,16 @@
       position: fixed;
       inset: auto;
       top: calc(anchor(bottom) + var(--cinder-space-1));
+      left: auto;
       right: anchor(right);
       position-try-fallbacks: flip-block, flip-inline;
     }
 
+    .cinder-dropdown-menu[popover][dir='rtl'] {
+      right: auto;
+      left: anchor(left);
+    }
+
     .cinder-dropdown__menu[popover] {
       position: fixed;
       margin: 0;

package/src/components/dropdown/dropdown.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic dropdown",
       "description": "A button trigger with a list of menu items.",
-      "code": "<script lang=\"ts\">\n  import { Dropdown } from '@lostgradient/cinder/dropdown';\n</script>\n\n<Dropdown id=\"dropdown-basic\">\n  <Dropdown.Trigger>Options</Dropdown.Trigger>\n  <Dropdown.Menu>\n    <Dropdown.Item>Edit</Dropdown.Item>\n    <Dropdown.Item>Duplicate</Dropdown.Item>\n    <Dropdown.Item variant=\"danger\">Delete</Dropdown.Item>\n  </Dropdown.Menu>\n</Dropdown>\n"
+      "code": "<script lang=\"ts\">\n  import { Dropdown } from '@lostgradient/cinder/dropdown';\n\n</script>\n\n<Dropdown id=\"dropdown\">\n  <Dropdown.Trigger>Options</Dropdown.Trigger>\n  <Dropdown.Menu>\n    <Dropdown.Item>Edit</Dropdown.Item>\n    <Dropdown.Item>Duplicate</Dropdown.Item>\n    <Dropdown.Item variant=\"danger\">Delete</Dropdown.Item>\n  </Dropdown.Menu>\n</Dropdown>\n"
     },
     {
       "id": "placement",

package/src/components/dropdown/dropdown.types.ts

@@ -8,6 +8,9 @@ export type DropdownContext = {
   get isOpen(): boolean;
   get supportsPopover(): boolean;
   readonly anchorElement?: HTMLElement | null | undefined;
+  readonly fallbackAnchorElement?: HTMLElement | null | undefined;
+  readonly fallbackPositionStyle?: string | undefined;
+  readonly fallbackPositionReady?: boolean | undefined;
   readonly fallbackPlacement?: Placement | undefined;
   readonly widthMode?: AnchoredOverlayWidthMode | undefined;
   readonly initialFocus?: 'first' | 'last' | 'none' | undefined;
@@ -15,11 +18,15 @@ export type DropdownContext = {
   focusTrigger: () => void;
 };
 type DropdownBaseProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** HTML id applied to the dropdown root element. Auto-generated when omitted. */
   id?: string;
+  /** Additional class names merged with the component's root class. */
   class?: string;
 };
 type LegacyDropdownProps = DropdownBaseProps & {
+  /** Controls the open state of the dropdown menu; bindable for controlled usage. */
   open?: boolean;
+  /** Preferred side of the trigger on which the menu opens. Default `bottom-start`. */
   placement?: DropdownPlacement;
   trigger: Snippet;
   children: Snippet;

package/src/components/dropdown-group/README.md

@@ -26,12 +26,12 @@ Accessible group boundary that clusters related dropdown-item rows inside a drop
 
 <!-- generated:props:start -->
 
-| Prop         | Type       | Required | Default | Description                                                                                                                |
-| ------------ | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `ariaLabel`  | `string`   | no       | —       |                                                                                                                            |
-| `class`      | `string`   | no       | —       | Additional class names merged onto the group root.                                                                         |
-| `labelledBy` | `string`   | no       | —       |                                                                                                                            |
-| `children`   | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop         | Type       | Required | Default | Description                                                                                                                        |
+| ------------ | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `class`      | `string`   | no       | —       | Additional class names merged onto the group root.                                                                                 |
+| `label`      | `string`   | no       | —       | Accessible label for the group, applied as aria-label. Provide exactly one of `label` or `labelledBy`.                             |
+| `labelledBy` | `string`   | no       | —       | ID of an existing element whose text labels the group, applied as aria-labelledby. Provide exactly one of `label` or `labelledBy`. |
+| `children`   | `(opaque)` | no       | —       | DropdownLabel plus grouped DropdownItem rows. Not expressible in JSON Schema; see the component types for the signature.           |
 
 <!-- generated:props:end -->
 

package/src/components/dropdown-group/dropdown-group.svelte

@@ -23,14 +23,14 @@
   let {
     class: customClassName,
     children,
-    ariaLabel,
+    label,
     labelledBy,
     ...rest
   }: DropdownGroupProps = $props();
 
   function normalizeAccessibleName(
     value: string | undefined,
-    propertyName: 'ariaLabel' | 'labelledBy',
+    propertyName: 'label' | 'labelledBy',
   ): string | undefined {
     if (value === undefined) return undefined;
     const trimmedValue = value.trim();
@@ -41,23 +41,23 @@
   }
 
   // Resolve and validate the accessible name at render time so all three
-  // invariants — non-empty ariaLabel, non-empty labelledBy, and exactly one of
+  // invariants — non-empty label, non-empty labelledBy, and exactly one of
   // the two — are enforced in a single place on both server and client, rather
   // than splitting the exclusivity check into a post-paint, SSR-skipped $effect.
   const resolvedAccessibleName = $derived.by(() => {
-    const trimmedAriaLabel = normalizeAccessibleName(ariaLabel, 'ariaLabel');
+    const trimmedLabel = normalizeAccessibleName(label, 'label');
     const trimmedLabelledBy = normalizeAccessibleName(labelledBy, 'labelledBy');
 
-    const namedByLabel = trimmedAriaLabel !== undefined;
+    const namedByLabel = trimmedLabel !== undefined;
     const namedByReference = trimmedLabelledBy !== undefined;
 
     if (namedByLabel === namedByReference) {
       throw new Error(
-        'DropdownGroup requires exactly one accessible naming strategy: ariaLabel or labelledBy.',
+        'DropdownGroup requires exactly one accessible naming strategy: label or labelledBy.',
       );
     }
 
-    return { ariaLabel: trimmedAriaLabel, labelledBy: trimmedLabelledBy };
+    return { label: trimmedLabel, labelledBy: trimmedLabelledBy };
   });
 </script>
 
@@ -65,7 +65,7 @@
   {...rest}
   class={classNames('cinder-dropdown-group', customClassName)}
   role="group"
-  aria-label={resolvedAccessibleName.ariaLabel}
+  aria-label={resolvedAccessibleName.label}
   aria-labelledby={resolvedAccessibleName.labelledBy}
 >
   {#if children}

package/src/components/dropdown-group/dropdown-group.types.ts

@@ -12,4 +12,15 @@ type DropdownGroupBaseProps = Omit<
 };
 
 export type DropdownGroupProps = DropdownGroupBaseProps &
-  ({ ariaLabel: string; labelledBy?: never } | { ariaLabel?: never; labelledBy: string });
+  (
+    | {
+        /** Accessible label for the group, applied as aria-label. Provide exactly one of `label` or `labelledBy`. */
+        label: string;
+        labelledBy?: never;
+      }
+    | {
+        label?: never;
+        /** ID of an existing element whose text labels the group, applied as aria-labelledby. Provide exactly one of `label` or `labelledBy`. */
+        labelledBy: string;
+      }
+  );

package/src/components/dropdown-item/README.md

@@ -16,13 +16,15 @@ snippet. The flat `@lostgradient/cinder/dropdown-item` subpath remains exported
 
 | Prop            | Type                                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | --------------- | ------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`         | `string`                              | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `closeOnSelect` | `boolean`                             | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `checked`       | `boolean`                             | no       | —       | Checked state for `itemRole="menuitemradio"`. Omitted for normal menu items.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `class`         | `string`                              | no       | —       | Additional class names merged with the component's root class.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `closeOnSelect` | `boolean`                             | no       | —       | When true, the parent dropdown closes after this item is activated. Default `true`.                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `disabled`      | `boolean`                             | no       | —       | When true the item is inert: click is blocked and aria-disabled is set.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `href`          | `string`                              | no       | —       | Destination URL. Any defined value — including an empty string — selects the anchor branch and renders an `<a>`. Omit `href` entirely to render a `<button>`.                                                                                                                                                                                                                                                                                                                                             |
-| `inset`         | `boolean`                             | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `inset`         | `boolean`                             | no       | —       | When true, adds leading padding to align the item with items that have a leading icon or indicator. Default `false`.                                                                                                                                                                                                                                                                                                                                                                                      |
+| `itemRole`      | `"menuitem"` \| `"menuitemradio"`     | no       | —       | ARIA role for the row. Use `menuitemradio` for mutually exclusive menu selections.                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `type`          | `"button"` \| `"submit"` \| `"reset"` | no       | —       | Button type forwarded to the `<button>` element. Defaults to `"button"`. NOTE: `type="submit"` only submits a surrounding `<form>` when the menu stays inside that form's DOM subtree. DropdownMenu portals its panel to `document.body` on the non-popover fallback path, so a submit item is then NOT a form descendant and native submission is skipped. To submit a form from a portaled menu, set `form="<form-id>"` to associate the button with the form by id, or handle submission in `onclick`. |
-| `variant`       | `"default"` \| `"danger"`             | no       | —       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `variant`       | `"default"` \| `"danger"`             | no       | —       | Visual style of the item. Use `danger` to signal a destructive action. Default `default`.                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `children`      | `(opaque)`                            | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                                                                                                |
 
 <!-- generated:props:end -->

package/src/components/dropdown-item/dropdown-item.svelte

@@ -30,6 +30,8 @@
 
   let {
     variant = 'default',
+    itemRole = 'menuitem',
+    checked = false,
     inset = false,
     disabled,
     closeOnSelect = true,
@@ -108,27 +110,27 @@
     event.currentTarget.click();
   }
 
-  const anchorAttributes = rest as Omit<
-    HTMLAnchorAttributes,
-    'class' | 'href' | 'onclick' | 'onkeydown'
-  >;
-  const buttonAttributes = rest as Omit<
-    HTMLButtonAttributes,
-    'class' | 'type' | 'disabled' | 'onclick'
-  >;
+  const anchorAttributes = $derived(
+    rest as Omit<HTMLAnchorAttributes, 'class' | 'href' | 'onclick' | 'onkeydown'>,
+  );
+  const buttonAttributes = $derived(
+    rest as Omit<HTMLButtonAttributes, 'class' | 'type' | 'disabled' | 'onclick'>,
+  );
   const buttonType = $derived((rest as { type?: HTMLButtonAttributes['type'] }).type ?? 'button');
+  const ariaChecked = $derived(itemRole === 'menuitemradio' ? checked : undefined);
 </script>
 
 <!--
   {...rest} is spread BEFORE the component-controlled attributes so a consumer
-  cannot override role="menuitem", tabindex (the roving-focus model), aria-disabled,
+  cannot override the menu role, tabindex (the roving-focus model), aria-disabled,
   or the click handler — overriding any of those would break menu semantics.
 -->
 {#if isLink}
   <a
     {...anchorAttributes}
     {href}
-    role="menuitem"
+    role={itemRole}
+    aria-checked={ariaChecked}
     class={sharedClass}
     data-cinder-variant={variant}
     tabindex={-1}
@@ -145,7 +147,8 @@
   <button
     {...buttonAttributes}
     type={buttonType}
-    role="menuitem"
+    role={itemRole}
+    aria-checked={ariaChecked}
     class={sharedClass}
     data-cinder-variant={variant}
     tabindex={-1}

package/src/components/dropdown-item/dropdown-item.types.ts

@@ -2,6 +2,7 @@ import type { Snippet } from 'svelte';
 import type { HTMLAnchorAttributes, HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
 
 export type DropdownItemVariant = 'default' | 'danger';
+export type DropdownItemRole = 'menuitem' | 'menuitemradio';
 
 // The shared base carries the common HTML attribute surface — crucially the
 // event handlers (onclick/onkeydown/onfocus/…) — typed against the generic
@@ -10,9 +11,17 @@ export type DropdownItemVariant = 'default' | 'danger';
 // "prove" which branch it is on. Element-specific NON-event attributes live in
 // the two branches so the `href` ⇄ `type` discriminant stays real.
 type DropdownItemBase = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Visual style of the item. Use `danger` to signal a destructive action. Default `default`. */
   variant?: DropdownItemVariant;
+  /** ARIA role for the row. Use `menuitemradio` for mutually exclusive menu selections. */
+  itemRole?: DropdownItemRole;
+  /** Checked state for `itemRole="menuitemradio"`. Omitted for normal menu items. */
+  checked?: boolean;
+  /** When true, adds leading padding to align the item with items that have a leading icon or indicator. Default `false`. */
   inset?: boolean;
+  /** When true, the parent dropdown closes after this item is activated. Default `true`. */
   closeOnSelect?: boolean;
+  /** Additional class names merged with the component's root class. */
   class?: string;
   children?: Snippet;
   /** When true the item is inert: click is blocked and aria-disabled is set. */

package/src/components/dropdown-label/README.md

@@ -16,7 +16,7 @@ snippet. The flat `@lostgradient/cinder/dropdown-label` subpath remains exported
 
 | Prop       | Type       | Required | Default | Description                                                                                                                |
 | ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`   | no       | —       |                                                                                                                            |
+| `class`    | `string`   | no       | —       | Additional class names merged with the component's root class.                                                             |
 | `children` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 
 <!-- generated:props:end -->

package/src/components/dropdown-label/dropdown-label.types.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 export type DropdownLabelProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Additional class names merged with the component's root class. */
   class?: string;
   children?: Snippet;
 };

package/src/components/dropdown-menu/README.md

@@ -16,7 +16,7 @@ snippet. The flat `@lostgradient/cinder/dropdown-menu` subpath remains exported
 
 | Prop       | Type       | Required | Default | Description                                                                                                                |
 | ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`   | no       | —       |                                                                                                                            |
+| `class`    | `string`   | no       | —       | Additional class names merged with the component's root class.                                                             |
 | `children` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 
 <!-- generated:props:end -->