@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/dropdown/dropdown.svelte

@@ -0,0 +1,209 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { createClickOutside } from '../../utilities/attachments.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import { setDropdownContext, setDropdownRegister, setDropdownRegisterTrigger, setDropdownSetOpen, } from './dropdown.context.ts';
+const generatedId = $props.id();
+let { id = generatedId, open = $bindable(false), placement = 'bottom-start', class: customClassName, trigger, children, ...rest } = $props();
+let compoundMenuElement = $state(null);
+let compoundTriggerElement = $state(null);
+let compoundOpen = $state(false);
+// Popover + CSS Anchor Positioning detection is deferred to after mount so
+// the server and client produce identical initial markup (both start with the
+// fallback {#if open} branch). Popover alone is not enough: without anchor()
+// support, top-layer menus cannot stay positioned relative to the trigger.
+let supportsPopover = $state(false);
+// $props.id() returns a framework-managed SSR-stable identifier — always a
+// valid CSS ident, so it can be safely interpolated into the inline
+// `anchor-name`/`position-anchor` styles below without sanitization.
+const menuId = `${generatedId}-menu`;
+let menuElement = $state();
+let triggerWrapper = $state();
+const compoundMenuId = $derived(`${id}-menu`);
+const usesLegacySnippetApi = $derived(Boolean(trigger));
+function closeCompoundMenu() {
+    // Optional-chain the method too: when CSS Anchor Positioning is missing,
+    // the menu renders without `popover="auto"` (see dropdown-menu.svelte),
+    // and calling hidePopover() on a non-popover element throws
+    // InvalidStateError — which would prevent compoundOpen from flipping
+    // to false and leave the menu stuck open.
+    compoundMenuElement?.hidePopover?.();
+    compoundOpen = false;
+}
+function registerCompoundMenu(element) {
+    compoundMenuElement = element;
+}
+function registerCompoundTrigger(element) {
+    compoundTriggerElement = element;
+}
+function focusCompoundTrigger() {
+    compoundTriggerElement?.focus();
+}
+function setCompoundOpen(nextOpen) {
+    compoundOpen = nextOpen;
+}
+setDropdownContext({
+    get menuId() {
+        return compoundMenuId;
+    },
+    get isOpen() {
+        return compoundOpen;
+    },
+    get supportsPopover() {
+        return supportsPopover;
+    },
+    get anchorElement() {
+        return compoundTriggerElement;
+    },
+    get fallbackPlacement() {
+        return placement;
+    },
+    get widthMode() {
+        return 'menu';
+    },
+    get initialFocus() {
+        return undefined;
+    },
+    close: closeCompoundMenu,
+    focusTrigger: focusCompoundTrigger,
+});
+setDropdownRegister(registerCompoundMenu);
+setDropdownRegisterTrigger(registerCompoundTrigger);
+setDropdownSetOpen(setCompoundOpen);
+// Keep aria-expanded on the trigger element in sync with open state.
+$effect(() => {
+    if (!usesLegacySnippetApi)
+        return;
+    const btn = triggerWrapper?.querySelector('button, a, [tabindex]:not([tabindex="-1"]), input, select');
+    if (!btn)
+        return;
+    btn.setAttribute('aria-haspopup', 'menu');
+    btn.setAttribute('aria-expanded', String(open));
+    btn.setAttribute('aria-controls', menuId);
+    return () => {
+        btn.removeAttribute('aria-haspopup');
+        btn.removeAttribute('aria-expanded');
+        btn.removeAttribute('aria-controls');
+    };
+});
+$effect(() => {
+    // Runs only on the client after mount — safe to check browser APIs.
+    supportsPopover =
+        typeof HTMLElement !== 'undefined' &&
+            'showPopover' in HTMLElement.prototype &&
+            typeof CSS !== 'undefined' &&
+            typeof CSS.supports === 'function' &&
+            CSS.supports('anchor-name: --x') &&
+            CSS.supports('position-anchor: --x') &&
+            CSS.supports('top: anchor(bottom)');
+});
+function handleKeydown(event) {
+    // The inner DropdownMenu's keydown handler closes the menu and calls
+    // preventDefault. When defaultPrevented is true, the menu already
+    // handled this keystroke — skip to avoid a second close+focus pass.
+    // Svelte 5 delegates onkeydown to the document, so the child handler
+    // runs first when the event path traverses the menu element.
+    if (event.defaultPrevented)
+        return;
+    if (event.key === 'Escape' && open) {
+        open = false;
+    }
+    else if (event.key === 'Escape' && compoundOpen) {
+        // Compound fallback path: focus was outside the menu (e.g. on the
+        // trigger), so the menu's onkeydown never fired. Close from here.
+        closeCompoundMenu();
+        focusCompoundTrigger();
+    }
+}
+const dismissOnOutsideClick = $derived(createClickOutside({
+    handler: () => {
+        open = false;
+        compoundOpen = false;
+    },
+    // Match the original effect gate: only the non-popover fallback path, and only while open.
+    enabled: () => !supportsPopover && (open || compoundOpen),
+    ignoreRefs: [() => menuElement ?? null, () => compoundMenuElement ?? null],
+    capture: false,
+}));
+// Popover API path: imperatively show/hide after the feature is detected.
+$effect(() => {
+    if (!supportsPopover || !menuElement)
+        return;
+    const menu = menuElement;
+    if (open) {
+        menu.showPopover?.();
+    }
+    else {
+        menu.hidePopover?.();
+    }
+});
+function handlePopoverToggle(event) {
+    const toggleEvent = event;
+    open = toggleEvent.newState === 'open';
+}
+</script>
+
+<div
+  {id}
+  class={classNames('cinder-dropdown', customClassName)}
+  data-cinder-placement={placement}
+  onkeydown={handleKeydown}
+  {@attach dismissOnOutsideClick}
+  {...rest}
+>
+  {#if usesLegacySnippetApi}
+    <!--
+      The legacy trigger wrapper intercepts clicks to toggle open, and wires ARIA attributes
+      onto the first focusable element inside the snippet. The anchor-name on the trigger
+      and position-anchor on the menu hand off positioning to CSS Anchor Positioning,
+      so the menu lands beside the trigger even after the popover API promotes the menu
+      into the top layer (where percent-based offsets would otherwise resolve against the viewport).
+    -->
+    <!--
+      Presentational delegation wrapper: the consumer's focusable trigger child
+      is the real interactive element (it receives aria-haspopup / aria-expanded
+      / aria-controls via the effect above). Keyboard activation works through
+      that child — Enter/Space fire a native click that bubbles here — so this
+      wrapper only needs role="presentation" to stay out of the a11y tree.
+    -->
+    <div
+      class="cinder-dropdown__trigger"
+      role="presentation"
+      bind:this={triggerWrapper}
+      style={`anchor-name: --${menuId};`}
+      onclick={() => (open = !open)}
+    >
+      {#if trigger}
+        {@render trigger()}
+      {/if}
+    </div>
+
+    {#if supportsPopover}
+      <div
+        bind:this={menuElement}
+        id={menuId}
+        class="cinder-dropdown__menu"
+        popover="auto"
+        role="menu"
+        data-cinder-placement={placement}
+        style={`position-anchor: --${menuId};`}
+        ontoggle={handlePopoverToggle}
+      >
+        {#if children}
+          {@render children()}
+        {/if}
+      </div>
+    {:else if open}
+      <div id={menuId} class="cinder-dropdown__menu" role="menu" data-cinder-placement={placement}>
+        {#if children}
+          {@render children()}
+        {/if}
+      </div>
+    {/if}
+  {:else if children}
+    {@render children()}
+  {/if}
+</div>

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

@@ -0,0 +1,48 @@
+import type { Placement } from '@floating-ui/dom';
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { AnchoredOverlayWidthMode } from '../../_internal/anchored-overlay.svelte.ts';
+export type DropdownPlacement = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+export type DropdownContext = {
+  get menuId(): string;
+  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;
+  close: () => void;
+  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 menu placement relative to the trigger. Default `bottom-start`.
+   * The rendered menu may still flip to stay within the viewport.
+   */
+  placement?: DropdownPlacement;
+  trigger: Snippet;
+  children: Snippet;
+};
+type CompoundDropdownProps = DropdownBaseProps & {
+  id: string;
+  children?: Snippet;
+  trigger?: never;
+  open?: never;
+  /**
+   * Preferred menu placement relative to the trigger. Default `bottom-start`.
+   * The rendered menu may still flip to stay within the viewport.
+   */
+  placement?: DropdownPlacement;
+};
+export type DropdownProps = LegacyDropdownProps | CompoundDropdownProps;

package/src/components/dropdown/dropdown.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/dropdown/index.ts

@@ -0,0 +1,32 @@
+import DropdownGroup from '../dropdown-group/dropdown-group.svelte';
+import DropdownItem from '../dropdown-item/dropdown-item.svelte';
+import DropdownLabel from '../dropdown-label/dropdown-label.svelte';
+import DropdownMenu from '../dropdown-menu/dropdown-menu.svelte';
+import DropdownSeparator from '../dropdown-separator/dropdown-separator.svelte';
+import DropdownTrigger from '../dropdown-trigger/dropdown-trigger.svelte';
+import './dropdown.css';
+import DropdownRoot from './dropdown.svelte';
+
+/**
+ * `Dropdown` is the parent compound component and a namespace exposing the
+ * compose-only leaves: `Dropdown.Trigger`, `Dropdown.Menu`, `Dropdown.Item`,
+ * `Dropdown.Label`, `Dropdown.Separator`, and `Dropdown.Group`. The leaves
+ * remain importable individually via `@lostgradient/cinder/dropdown-trigger`,
+ * `@lostgradient/cinder/dropdown-menu`, etc.
+ */
+const Dropdown = Object.assign(DropdownRoot, {
+  Trigger: DropdownTrigger,
+  Menu: DropdownMenu,
+  Item: DropdownItem,
+  Label: DropdownLabel,
+  Separator: DropdownSeparator,
+  Group: DropdownGroup,
+});
+
+export default Dropdown;
+// Context getter functions are intentionally excluded from the public barrel:
+// setters would allow external code to hijack the dropdown wiring of any subtree,
+// and raw getters without the provider are not a supported use case for consumers.
+// Internal bridges (menu-bar, context-menu) import from dropdown.context.ts directly.
+export type { DropdownContext, DropdownPlacement, DropdownProps } from './dropdown.types.ts';
+export { Dropdown };

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

@@ -0,0 +1,34 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    class: {
+      type: 'string',
+      description: 'Additional class names merged onto the group root.',
+    },
+    label: {
+      type: 'string',
+      description:
+        'Accessible label for the group, applied as aria-label. Provide exactly one of `label` or `labelledBy`.',
+    },
+    labelledBy: {
+      type: 'string',
+      description:
+        'ID of an existing element whose text labels the group, applied as aria-labelledby. Provide exactly one of `label` or `labelledBy`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        description: 'DropdownLabel plus grouped DropdownItem rows.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

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

@@ -0,0 +1,43 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+let { class: customClassName, children, label, labelledBy, ...rest } = $props();
+function normalizeAccessibleName(value, propertyName) {
+    if (value === undefined)
+        return undefined;
+    const trimmedValue = value.trim();
+    if (trimmedValue.length === 0) {
+        throw new Error(`DropdownGroup requires a non-empty ${propertyName} value.`);
+    }
+    return trimmedValue;
+}
+// Resolve and validate the accessible name at render time so all three
+// 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 trimmedLabel = normalizeAccessibleName(label, 'label');
+    const trimmedLabelledBy = normalizeAccessibleName(labelledBy, 'labelledBy');
+    const namedByLabel = trimmedLabel !== undefined;
+    const namedByReference = trimmedLabelledBy !== undefined;
+    if (namedByLabel === namedByReference) {
+        throw new Error('DropdownGroup requires exactly one accessible naming strategy: label or labelledBy.');
+    }
+    return { label: trimmedLabel, labelledBy: trimmedLabelledBy };
+});
+</script>
+
+<div
+  {...rest}
+  class={classNames('cinder-dropdown-group', customClassName)}
+  role="group"
+  aria-label={resolvedAccessibleName.label}
+  aria-labelledby={resolvedAccessibleName.labelledBy}
+>
+  {#if children}
+    {@render children()}
+  {/if}
+</div>

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

@@ -0,0 +1,26 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+type DropdownGroupBaseProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'aria-label' | 'aria-labelledby' | 'class' | 'role'
+> & {
+  /** Additional class names merged onto the group root. */
+  class?: string;
+  /** DropdownLabel plus grouped DropdownItem rows. */
+  children?: Snippet;
+};
+
+export type DropdownGroupProps = DropdownGroupBaseProps &
+  (
+    | {
+        /** 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-group/dropdown-group.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

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

@@ -0,0 +1,5 @@
+import DropdownGroup from './dropdown-group.svelte';
+
+export default DropdownGroup;
+export type { DropdownGroupProps } from './dropdown-group.types.ts';
+export { DropdownGroup };

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

@@ -0,0 +1,62 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    variant: {
+      enum: ['default', 'danger'],
+      description:
+        'Visual style of the item. Use `danger` to signal a destructive action. Default `default`.',
+    },
+    itemRole: {
+      enum: ['menuitem', 'menuitemcheckbox', 'menuitemradio'],
+      description:
+        'ARIA role for the row. Use `menuitemcheckbox` or `menuitemradio` for selectable menu items.',
+    },
+    checked: {
+      type: 'boolean',
+      description:
+        'Checked state for checkbox and radio menu items. Omitted for normal menu items.',
+    },
+    inset: {
+      type: 'boolean',
+      description:
+        'When true, adds leading padding to align the item with items that have a leading icon or indicator. Default `false`.',
+    },
+    closeOnSelect: {
+      type: 'boolean',
+      description:
+        'When true, the parent dropdown closes after this item is activated. Default `true`.',
+    },
+    class: {
+      type: 'string',
+      description: "Additional class names merged with the component's root class.",
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'When true the item is inert: click is blocked and aria-disabled is set.',
+    },
+    href: {
+      type: 'string',
+      description:
+        'Destination URL. Any defined value — including an empty string — selects\nthe anchor branch and renders an `<a>`. Omit `href` entirely to render a\n`<button>`.',
+    },
+    type: {
+      enum: ['button', 'submit', 'reset'],
+      description:
+        'Button type forwarded to the `<button>` element. Defaults to `"button"`.\n\nNOTE: `type="submit"` only submits a surrounding `<form>` when the menu\nstays inside that form\'s DOM subtree. DropdownMenu portals its panel to\n`document.body` on the non-popover fallback path, so a submit item is then\nNOT a form descendant and native submission is skipped. To submit a form\nfrom a portaled menu, set `form="<form-id>"` to associate the button with\nthe form by id, or handle submission in `onclick`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

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

@@ -0,0 +1,95 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import { getDropdownContext } from '../dropdown/dropdown.context.ts';
+let { variant = 'default', itemRole = 'menuitem', checked = false, inset = false, disabled, closeOnSelect = true, class: customClassName, onclick, onkeydown, href, children, ...rest } = $props();
+const context = getDropdownContext();
+const isLink = $derived(href !== undefined);
+const sharedClass = $derived(classNames('cinder-_option-row', 'cinder-dropdown-item', inset && 'cinder-dropdown-item--inset', customClassName));
+function handleClick(event) {
+    if (disabled) {
+        event.preventDefault();
+        return;
+    }
+    if (typeof onclick === 'function') {
+        if (isLink) {
+            onclick(event);
+        }
+        else {
+            onclick(event);
+        }
+    }
+    if (closeOnSelect) {
+        context.close();
+    }
+}
+// A native `<a>` activates on Enter but NOT Space, whereas a `<button>` (and
+// the WAI-ARIA menuitem pattern) activates on both. Without this, Space on a
+// link row would scroll the page instead of following the row — inconsistent
+// with button rows. Translate Space into an activation click on the anchor,
+// while still forwarding any consumer-provided onkeydown handler (which runs
+// first and may preventDefault to opt out of Space-to-activate).
+function handleAnchorKeydown(event) {
+    if (typeof onkeydown === 'function') {
+        onkeydown(event);
+    }
+    if (event.defaultPrevented)
+        return;
+    if (event.key !== ' ' && event.key !== 'Spacebar')
+        return;
+    event.preventDefault(); // stop the page from scrolling
+    if (disabled)
+        return;
+    event.currentTarget.click();
+}
+const anchorAttributes = $derived(rest);
+const buttonAttributes = $derived(rest);
+const buttonType = $derived(rest.type ?? 'button');
+const ariaChecked = $derived(itemRole === 'menuitemcheckbox' || itemRole === 'menuitemradio' ? checked : undefined);
+</script>
+
+<!--
+  {...rest} is spread BEFORE the component-controlled attributes so a consumer
+  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={itemRole}
+    aria-checked={ariaChecked}
+    class={sharedClass}
+    data-cinder-variant={variant}
+    tabindex={-1}
+    data-disabled={disabled ? '' : undefined}
+    aria-disabled={disabled ? 'true' : undefined}
+    onclick={handleClick}
+    onkeydown={handleAnchorKeydown}
+  >
+    {#if children}
+      {@render children()}
+    {/if}
+  </a>
+{:else}
+  <button
+    {...buttonAttributes}
+    type={buttonType}
+    role={itemRole}
+    aria-checked={ariaChecked}
+    class={sharedClass}
+    data-cinder-variant={variant}
+    tabindex={-1}
+    data-disabled={disabled ? '' : undefined}
+    aria-disabled={disabled ? 'true' : undefined}
+    onclick={handleClick}
+    {onkeydown}
+  >
+    {#if children}
+      {@render children()}
+    {/if}
+  </button>
+{/if}

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

@@ -0,0 +1,75 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAnchorAttributes, HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
+
+export type DropdownItemVariant = 'default' | 'danger';
+export type DropdownItemRole = 'menuitem' | 'menuitemcheckbox' | 'menuitemradio';
+
+// The shared base carries the common HTML attribute surface — crucially the
+// event handlers (onclick/onkeydown/onfocus/…) — typed against the generic
+// `HTMLElement`. Both render paths (`<button>` and `<a>`) satisfy that, so a
+// consumer can attach an inline handler without TypeScript forcing it to
+// "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 `menuitemcheckbox` or `menuitemradio` for selectable menu items. */
+  itemRole?: DropdownItemRole;
+  /** Checked state for checkbox and radio menu items. 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. */
+  disabled?: boolean | undefined;
+};
+
+/**
+ * Button variant — renders a `<button>`. Forwards every button-specific
+ * attribute (`name`, `value`, `form`, `formaction`, `formmethod`,
+ * `formnovalidate`, `formtarget`, `formenctype`, …) by subtracting the shared
+ * `HTMLElement` surface — which the base already provides with `HTMLElement`-typed
+ * event handlers — so a form-submitting menu item (`type="submit"` with `name`/
+ * `value`) keeps full typing without reintroducing the inline-handler
+ * contravariance trap. `disabled` is owned by the base (a managed click guard +
+ * aria-disabled), not the native attribute.
+ */
+export type DropdownItemButtonProps = DropdownItemBase &
+  Omit<HTMLButtonAttributes, keyof HTMLAttributes<HTMLElement> | 'class' | 'disabled' | 'type'> & {
+    href?: undefined;
+    /**
+     * 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`.
+     */
+    type?: 'button' | 'submit' | 'reset';
+  };
+
+/**
+ * Anchor variant — renders an `<a href>`. `disabled` blocks navigation and sets
+ * aria-disabled. Forwards every anchor-specific attribute (`target`, `rel`,
+ * `download`, `ping`, `hreflang`, `referrerpolicy`, …) by subtracting the shared
+ * `HTMLElement` surface — which the base already provides with `HTMLElement`-typed
+ * event handlers — so the inline-handler contravariance trap never reappears.
+ */
+export type DropdownItemAnchorProps = DropdownItemBase &
+  Omit<HTMLAnchorAttributes, keyof HTMLAttributes<HTMLElement> | 'class' | 'href'> & {
+    /**
+     * Destination URL. Any defined value — including an empty string — selects
+     * the anchor branch and renders an `<a>`. Omit `href` entirely to render a
+     * `<button>`.
+     */
+    href: string;
+    type?: undefined;
+  };
+
+export type DropdownItemProps = DropdownItemButtonProps | DropdownItemAnchorProps;

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

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

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

@@ -0,0 +1,10 @@
+import DropdownItem from './dropdown-item.svelte';
+
+export default DropdownItem;
+export type {
+  DropdownItemAnchorProps,
+  DropdownItemButtonProps,
+  DropdownItemProps,
+  DropdownItemVariant,
+} from './dropdown-item.types.ts';
+export { DropdownItem };