@webjsdev/ui 0.3.1 → 0.3.3

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

@@ -0,0 +1,175 @@
+/**
+ * HoverCard: popover-like panel triggered by hover with configurable
+ * open / close delays. Tier-2. The content uses the native Popover API
+ * in `popover="manual"` mode for top-layer rendering; the custom
+ * element owns the hover-with-linger state machine and JS positioning.
+ *
+ * shadcn parity:
+ *   HoverCard          → <ui-hover-card open-delay close-delay>
+ *   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.
+ *   `close-delay`: ms, default 300. Linger delay before closing once
+ *                  cursor leaves trigger + content.
+ *
+ * Attributes on <ui-hover-card-content>:
+ *   `side`:         "top" | "right" | "bottom" (default) | "left".
+ *   `align`:        "center" (default) | "start" | "end".
+ *   `side-offset`:  number, default 4. Pixels between trigger and content.
+ *   `align-offset`: number, default 0. Pixels of cross-axis shift.
+ *
+ * Events: none dispatched at present; observe the reflected `open`
+ * attribute from CSS or JS.
+ *
+ * Programmatic API on <ui-hover-card>: `.show()` · `.hide()`.
+ *
+ * Design tokens used: --popover, --popover-foreground, --border.
+ */
+import { WebComponent, html } from '@webjsdev/core';
+import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
+
+// `fixed m-0` opts out of the UA `[popover]` auto-centering margin so
+// JS-computed top/left from positionFloating lands correctly. shadcn's
+// visual layer sits on top. UA `[popover]:not(:popover-open) {
+// display: none }` handles closed-state hiding.
+export const hoverCardContentClass = (): string =>
+  'fixed z-50 w-64 m-0 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-hidden';
+
+// --------------------------------------------------------------------------
+// <ui-hover-card>
+// --------------------------------------------------------------------------
+
+export class UiHoverCard extends WebComponent {
+  static properties = {
+    open: { type: Boolean, reflect: true },
+  };
+  declare open: boolean;
+
+  _showTimer: number | undefined;
+  _hideTimer: number | undefined;
+
+  constructor() {
+    super();
+    this.open = false;
+  }
+
+  // Back-compat getter.
+  get isOpen(): boolean { return this.open; }
+
+  show(): void {
+    clearTimeout(this._hideTimer);
+    const delay = Number(this.getAttribute('open-delay') ?? 700);
+    this._showTimer = window.setTimeout(() => { this.open = true; }, delay);
+  }
+
+  hide(): void {
+    clearTimeout(this._showTimer);
+    const delay = Number(this.getAttribute('close-delay') ?? 300);
+    this._hideTimer = window.setTimeout(() => { this.open = false; }, delay);
+  }
+
+  render() {
+    return html`<div
+      data-slot="hover-card"
+      data-state=${this.open ? 'open' : 'closed'}
+    ><slot></slot></div>`;
+  }
+
+  updated(changedProperties: Map<string, unknown>): void {
+    if (!changedProperties.has('open')) return;
+    if (changedProperties.get('open') === undefined) return;
+    // Wait one microtask for <ui-hover-card-content>'s inner [popover]
+    // element to commit; we drive its showPopover() / hidePopover().
+    queueMicrotask(() => this._syncContent());
+  }
+
+  _syncContent(): void {
+    // Same nested-popover pattern as tooltip: <ui-hover-card-content>
+    // renders an inner <div popover="manual">; the Popover API lives on
+    // that inner div, not the host.
+    const popover = this.querySelector<HTMLElement>('ui-hover-card-content [popover]');
+    const host = this.querySelector<HTMLElement>('ui-hover-card-content');
+    if (!popover || !popover.isConnected) return;
+    const p = popover as HTMLElement & {
+      showPopover?: () => void;
+      hidePopover?: () => void;
+      matches: (s: string) => boolean;
+    };
+    if (typeof p.showPopover !== 'function') return;
+    if (this.open) {
+      if (!p.matches(':popover-open')) p.showPopover();
+      if (host) this._reposition(host, popover);
+    } else if (p.matches(':popover-open')) {
+      p.hidePopover();
+    }
+  }
+
+  _reposition(contentHost: HTMLElement, popover: HTMLElement): void {
+    const trigger = this.querySelector<HTMLElement>('ui-hover-card-trigger');
+    if (!trigger) return;
+    positionFloating(trigger, popover, {
+      side: (contentHost.getAttribute('side') ?? 'bottom') as PopoverSide,
+      align: (contentHost.getAttribute('align') ?? 'center') as PopoverAlign,
+      sideOffset: Number(contentHost.getAttribute('side-offset') ?? 4),
+      alignOffset: Number(contentHost.getAttribute('align-offset') ?? 0),
+    });
+  }
+}
+UiHoverCard.register('ui-hover-card');
+
+// --------------------------------------------------------------------------
+// <ui-hover-card-trigger>
+// --------------------------------------------------------------------------
+
+export class UiHoverCardTrigger extends WebComponent {
+  render() {
+    return html`<div
+      data-slot="hover-card-trigger"
+      @mouseenter=${this._onEnter}
+      @mouseleave=${this._onLeave}
+      @focusin=${this._onEnter}
+      @focusout=${this._onLeave}
+    ><slot></slot></div>`;
+  }
+
+  _onEnter = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
+  _onLeave = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+}
+UiHoverCardTrigger.register('ui-hover-card-trigger');
+
+// --------------------------------------------------------------------------
+// <ui-hover-card-content>
+// The mouseenter/mouseleave handlers keep the card open while the cursor
+// is over the content itself (so it does not close during a brief
+// mouseleave on the trigger if the user is moving toward the card).
+// --------------------------------------------------------------------------
+
+export class UiHoverCardContent extends WebComponent {
+  render() {
+    return html`<div
+      data-slot="hover-card-content"
+      role="dialog"
+      popover="manual"
+      class=${hoverCardContentClass()}
+      @mouseenter=${this._onEnter}
+      @mouseleave=${this._onLeave}
+    ><slot></slot></div>`;
+  }
+
+  _onEnter = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.show();
+  _onLeave = (): void => (this.closest('ui-hover-card') as UiHoverCard | null)?.hide();
+}
+UiHoverCardContent.register('ui-hover-card-content');

package/packages/registry/components/input.ts

@@ -0,0 +1,36 @@
+/**
+ * Input: styled native `<input>`. Tier-1 class helper. Works with every
+ * input type (text, email, password, number, search, tel, url, date,
+ * time, file, color, …). Form submission, autocomplete, browser
+ * validation, and password managers all work because it IS the native
+ * input.
+ *
+ * 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.
+ */
+import { cn } from '../lib/utils.ts';
+
+const INPUT_BASE =
+  'h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:bg-input/30';
+
+const INPUT_FOCUS =
+  'focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50';
+
+const INPUT_INVALID =
+  'aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40';
+
+/** Compose Tailwind classes for a native `<input>`. */
+export function inputClass(): string {
+  return cn(INPUT_BASE, INPUT_FOCUS, INPUT_INVALID);
+}

package/packages/registry/components/kbd.ts

@@ -0,0 +1,25 @@
+/**
+ * Kbd: keyboard chord display. Tier-1 class helpers; compose with the
+ * native `<kbd>` element for correct semantics.
+ *
+ * shadcn parity:
+ *   Kbd       → kbdClass()
+ *   KbdGroup  → kbdGroupClass()
+ *
+ * Usage:
+ *   <kbd class=${kbdClass()}>⌘</kbd>
+ *   <kbd class=${kbdClass()}>K</kbd>
+ *
+ *   <div class=${kbdGroupClass()}>
+ *     <kbd class=${kbdClass()}>⌘</kbd>
+ *     <kbd class=${kbdClass()}>Shift</kbd>
+ *     <kbd class=${kbdClass()}>P</kbd>
+ *   </div>
+ *
+ * Design tokens used: --muted, --muted-foreground, --background.
+ */
+
+export const kbdClass = (): string =>
+  "pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-sm bg-muted px-1 font-sans text-xs font-medium text-muted-foreground select-none [&_svg:not([class*='size-'])]:size-3 [[data-slot=tooltip-content]_&]:bg-background/20 [[data-slot=tooltip-content]_&]:text-background dark:[[data-slot=tooltip-content]_&]:bg-background/10";
+
+export const kbdGroupClass = (): string => 'inline-flex items-center gap-1';

package/packages/registry/components/label.ts

@@ -0,0 +1,23 @@
+/**
+ * Label: styled native `<label>`. Tier-1 class helper. Compose with a
+ * real `<label for="...">` so click-to-focus, `htmlFor` / `for` linking,
+ * and screen-reader association all work natively (no Radix Label needed).
+ *
+ * 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).
+ */
+
+/** Compose Tailwind classes for a native `<label>`. */
+export function labelClass(): string {
+  return 'flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50';
+}

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

@@ -0,0 +1,110 @@
+/**
+ * NativeSelect: styled native `<select>`. Tier-1 class helpers. Uses
+ * `appearance: none` to hide the platform chevron and overlays an SVG
+ * chevron on top. Best mobile UX (native picker), full keyboard support,
+ * form submission works natively. No JS.
+ *
+ * shadcn parity:
+ *   NativeSelect             → nativeSelectClass()
+ *   NativeSelect wrapper     → nativeSelectWrapperClass()
+ *   NativeSelect chevron     → nativeSelectIconClass()
+ *   NativeSelect option      → bare <option> (or nativeSelectOptionClass()
+ *                              for explicit overrides; the installed
+ *                              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
+ * overrides use `nativeSelectOptionClass()` / `nativeSelectOptGroupClass()`.
+ *
+ * Design tokens used: --input, --background, --primary, --primary-foreground,
+ * --muted-foreground, --ring, --destructive.
+ */
+import { cn } from '../lib/utils.ts';
+
+export type NativeSelectSize = 'default' | 'sm';
+
+// Auto-apply Canvas/CanvasText to every <option> on the page. Without
+// this, an <option> with no explicit bg paints transparent on top of
+// the browser-popup background; in dark mode (when color-scheme: dark
+// is set on <html>) Chrome's popup is dark, the option's transparent
+// bg lets the popup colour through, and the inherited text colour
+// from the <select> matches that dark popup: the option disappears,
+// only the focused/selected one stays visible because the browser
+// overlays its own highlight on it.
+//
+// Original selector required the option to be inside a
+// `.group/native-select` wrapper, on the assumption every user would
+// follow the documented Usage block above. But it's easy to write a
+// bare <select class=${nativeSelectClass()}> without the wrapper
+// (legitimate when you don't need the chevron icon: the popover and
+// hover-card docs examples both do this), in which case the rule
+// never matched and the dropdown reverted to invisible-options.
+// Broadening to `select option, select optgroup` makes the fix work
+// everywhere the user has imported native-select, with no required
+// wrapper. The Canvas/CanvasText pair is a safe default: they ARE
+// the system colours the browser would have painted anyway when no
+// rule applied; we just stop relying on inheritance to pull through.
+// Selector specificity is 0,0,2 (two elements), so any user who
+// genuinely needs custom <option> colours can override with a single
+// class anywhere in their cascade (e.g. `.my-select option { ... }`
+// at 0,1,2 wins).
+//
+// `nativeSelectOptionClass()` and `nativeSelectOptGroupClass()` stay
+// exported for users who want to opt into the same colours via the
+// class helper instead of the global rule. They emit the same
+// `bg-[Canvas] text-[CanvasText]` Tailwind utilities: redundant if
+// this stylesheet is installed, but harmless and matches the broader
+// shadcn convention of "every part has a class helper".
+const STYLES = `
+select option,
+select optgroup {
+  background-color: Canvas;
+  color: CanvasText;
+}
+`;
+
+let installed = false;
+export function installNativeSelectStyles(): void {
+  if (installed || typeof document === 'undefined') return;
+  if (document.getElementById('ui-native-select-styles')) {
+    installed = true;
+    return;
+  }
+  const style = document.createElement('style');
+  style.id = 'ui-native-select-styles';
+  style.textContent = STYLES;
+  document.head.appendChild(style);
+  installed = true;
+}
+
+if (typeof document !== 'undefined') installNativeSelectStyles();
+
+export const nativeSelectWrapperClass = (): string =>
+  'group/native-select relative w-fit has-[select:disabled]:opacity-50';
+
+export function nativeSelectClass(): string {
+  return cn(
+    'h-9 w-full min-w-0 appearance-none rounded-md border border-input bg-transparent px-3 py-2 pr-9 text-sm shadow-xs transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed data-[size=sm]:h-8 data-[size=sm]:py-1 dark:bg-input/30 dark:hover:bg-input/50',
+    'focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50',
+    'aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40',
+  );
+}
+
+export const nativeSelectIconClass = (): string =>
+  'pointer-events-none absolute top-1/2 right-3.5 size-4 -translate-y-1/2 text-muted-foreground opacity-50 select-none';
+
+/** Option / optgroup styling: forces themed background even in dark mode. */
+export const nativeSelectOptionClass = (): string => 'bg-[Canvas] text-[CanvasText]';
+export const nativeSelectOptGroupClass = (): string => 'bg-[Canvas] text-[CanvasText]';

package/packages/registry/components/pagination.ts

@@ -0,0 +1,45 @@
+/**
+ * Pagination: page navigation. Tier-1 class helpers; compose with native
+ * `<nav>` + `<ul>` + `<li>` + `<a>`. Links route through `buttonClass()`
+ * so the visual matches the rest of the button vocabulary exactly.
+ *
+ * shadcn parity:
+ *   Pagination           → <nav aria-label="pagination" class=${paginationClass()}>
+ *   PaginationContent    → paginationContentClass()
+ *   PaginationItem       → <li> (no helper needed)
+ *   PaginationLink       → paginationLinkClass({ isActive, size })
+ *   PaginationPrevious   → paginationPreviousClass()
+ *   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>
+ *
+ * Design tokens used: inherited from buttonClass.
+ */
+import { cn } from '../lib/utils.ts';
+import { buttonClass, type ButtonSize } from './button.ts';
+
+export const paginationClass = (): string => 'mx-auto flex w-full justify-center';
+
+export const paginationContentClass = (): string => 'flex flex-row items-center gap-1';
+
+export function paginationLinkClass(opts: { isActive?: boolean; size?: ButtonSize } = {}): string {
+  return cn(buttonClass({ variant: opts.isActive ? 'outline' : 'ghost', size: opts.size ?? 'icon' }));
+}
+
+export const paginationPreviousClass = (): string =>
+  cn(buttonClass({ variant: 'ghost', size: 'default' }), 'gap-1 px-2.5 sm:pl-2.5');
+
+export const paginationNextClass = (): string =>
+  cn(buttonClass({ variant: 'ghost', size: 'default' }), 'gap-1 px-2.5 sm:pr-2.5');
+
+export const paginationEllipsisClass = (): string => 'flex size-9 items-center justify-center';