@webjsdev/ui 0.3.16 → 0.4.0

package/packages/registry/components/empty.ts

@@ -0,0 +1,88 @@
+/**
+ * Empty: the empty state for a list, table, search result, or any region with
+ * nothing to show yet. Tier-1 class helpers; compose with `<div>` (or a heading
+ * and paragraph) for each subpart.
+ *
+ * shadcn parity:
+ *   Empty                               → emptyClass()
+ *   EmptyHeader                         → emptyHeaderClass()
+ *   EmptyMedia (variant: default | icon) → emptyMediaClass({ variant })
+ *   EmptyTitle                          → emptyTitleClass()
+ *   EmptyDescription                    → emptyDescriptionClass()
+ *   EmptyContent                        → emptyContentClass()
+ *
+ * The root carries `border-dashed` but no border width, exactly as shadcn
+ * does, so it renders borderless by default. Add `border` beside it for the
+ * dashed outline: `class=${cn(emptyClass(), 'border')}`.
+ *
+ * Design tokens used: --muted, --foreground, --muted-foreground, --primary,
+ * --border.
+ *
+ * A11y (required for accessible output):
+ *   Use a REAL HEADING for `emptyTitleClass()`, at the level the surrounding
+ *   document wants (`<h2>` under the page `<h1>`, `<h3>` inside a section). The
+ *   empty state usually replaces the list a heading already introduces, so the
+ *   title is often a level below it.
+ *   The media is decorative: put `aria-hidden="true"` on the icon or
+ *   illustration, since the title already says what is missing.
+ *   The action in `emptyContentClass()` is a real `<a href>` (navigates, e.g.
+ *   to the create page) or a real `<button>` (acts in place). A create action
+ *   that is a form submit keeps working without JavaScript.
+ *   When the empty state appears in response to a user action (a search or a
+ *   filter that matched nothing), put `role="status"` on the root so the change
+ *   is announced; a page that simply loads empty needs no role.
+ *
+ * @example
+ * ```html
+ * <div class=${cn(emptyClass(), 'border')}>
+ *   <div class=${emptyHeaderClass()}>
+ *     <div class=${emptyMediaClass({ variant: 'icon' })}>
+ *       <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 12h-6l-2 3h-4l-2-3H2"/><path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z"/></svg>
+ *     </div>
+ *     <h3 class=${emptyTitleClass()}>No projects yet</h3>
+ *     <p class=${emptyDescriptionClass()}>Create your first project to get started.</p>
+ *   </div>
+ *   <div class=${emptyContentClass()}>
+ *     <a class=${buttonClass()} href="/projects/new">Create project</a>
+ *   </div>
+ * </div>
+ * ```
+ */
+
+const MEDIA_BASE =
+  'cn-empty-media flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0';
+
+const MEDIA_VARIANTS = {
+  default: 'cn-empty-media-default',
+  icon: 'cn-empty-media-icon',
+} as const;
+
+export type EmptyMediaVariant = keyof typeof MEDIA_VARIANTS;
+
+/** Empty root: centred column with generous padding. Add `border` for the dashed outline. */
+export const emptyClass = (): string =>
+  'cn-empty flex w-full min-w-0 flex-1 flex-col items-center justify-center text-center text-balance';
+
+/** Empty header: groups the media, title, and description. */
+export const emptyHeaderClass = (): string =>
+  'cn-empty-header flex max-w-sm flex-col items-center';
+
+/**
+ * Empty media: the icon or illustration above the title. `icon` puts the icon
+ * on a muted tile; `default` leaves it bare (for an avatar or an illustration).
+ * Set `data-variant="<variant>"` on the same element for shadcn parity.
+ */
+export function emptyMediaClass(opts: { variant?: EmptyMediaVariant } = {}): string {
+  return MEDIA_BASE + ' ' + MEDIA_VARIANTS[opts.variant ?? 'default'];
+}
+
+/** Empty title: what is missing, in a few words. */
+export const emptyTitleClass = (): string => 'cn-empty-title';
+
+/** Empty description: the muted line under the title, saying what to do next. */
+export const emptyDescriptionClass = (): string =>
+  'cn-empty-description text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary';
+
+/** Empty content: the row for the action button(s) or a small form. */
+export const emptyContentClass = (): string =>
+  'cn-empty-content flex w-full max-w-sm min-w-0 flex-col items-center text-balance';

package/packages/registry/components/field.ts

@@ -0,0 +1,165 @@
+/**
+ * Field: the layout system for a form, a label, a control, its helper text,
+ * and its error message, plus the fieldset, legend, and group that hold many
+ * fields. Tier-1 class helpers; compose with the native elements (`<fieldset>`,
+ * `<legend>`, `<label>`, `<p>`) and the kit's control helpers
+ * (`inputClass()`, `textareaClass()`, `checkboxClass()`, and the rest).
+ *
+ * shadcn parity:
+ *   FieldSet                             → fieldSetClass()
+ *   FieldLegend (variant: legend | label) → fieldLegendClass({ variant })
+ *   FieldGroup                           → fieldGroupClass()
+ *   Field (orientation: vertical | horizontal | responsive) → fieldClass({ orientation })
+ *   FieldContent                         → fieldContentClass()
+ *   FieldLabel                           → fieldLabelClass()
+ *   FieldTitle                           → fieldTitleClass()
+ *   FieldDescription                     → fieldDescriptionClass()
+ *   FieldError                           → fieldErrorClass()
+ *   FieldSeparator                       → fieldSeparatorClass() + fieldSeparatorContentClass()
+ *
+ * Set the shadcn data attributes on the same elements, because the sibling and
+ * group rules key on them: `data-slot="field"` + `data-orientation` on the
+ * field, `data-slot="field-label"` on the label, `data-slot="field-content"`
+ * on the content wrapper, `data-variant` on the legend, and
+ * `data-slot="field-group"` on the group (the `responsive` orientation reads
+ * the group's container width).
+ *
+ * Invalid state: put `data-invalid="true"` on the field, which turns the
+ * field's text destructive (`data-[invalid=true]:text-destructive`), and
+ * `aria-invalid="true"` on the control, which the control helpers style.
+ * Disabled state: `data-disabled="true"` on the field fades its label.
+ *
+ * Not the same as the `fieldClass()` / `fieldLabelClass()` in the `cn()`
+ * helper module (`lib/utils/cn.ts`), which are the older single-field rhythm
+ * helpers (`grid gap-2`). Both keep working. Import each from its own module,
+ * and alias one (`import { fieldClass as fieldStackClass } from ...`) if a file
+ * needs both.
+ *
+ * Design tokens used: --destructive, --muted-foreground, --primary,
+ * --background, --border.
+ *
+ * A11y (required for accessible output):
+ *   Every control has a real `<label for>` (`fieldLabelClass()`), never a
+ *   placeholder alone. A field carries `role="group"` (as shadcn's does) only
+ *   when it holds more than one control; a single-control field needs no role.
+ *   Wire the helper and error text to the control with `aria-describedby`,
+ *   listing the description id and, when invalid, the error id
+ *   (`aria-describedby="email-desc email-error"`). Point it only at ids that
+ *   EXIST on the page, so render the error element only when there is an error.
+ *   On a server validation error, re-render the form with the typed values
+ *   kept (`value=${values.email}`), `data-invalid="true"` on the field,
+ *   `aria-invalid="true"` on the control, and the message in
+ *   `fieldErrorClass()` with `role="alert"`, so the user fixes the one field
+ *   instead of retyping the form. Move focus to the first invalid control.
+ *   Group related controls (a radio set, a checkbox list) in a `<fieldset>`
+ *   with a `<legend>` (`fieldSetClass()` / `fieldLegendClass()`), which names
+ *   the group. A `fieldTitleClass()` element is NOT a label: use it for the
+ *   title inside a choice card whose `<label>` wraps the whole card.
+ *   A decorative separator gets `role="none"`; its text (`or`) stays readable.
+ *
+ * @example
+ * ```html
+ * <form method="post" class="w-full max-w-md">
+ *   <fieldset class=${fieldSetClass()}>
+ *     <legend class=${fieldLegendClass()} data-variant="legend">Profile</legend>
+ *     <p class=${fieldDescriptionClass()}>This is how others see you.</p>
+ *     <div class=${fieldGroupClass()} data-slot="field-group">
+ *       <div class=${fieldClass()} data-slot="field" data-orientation="vertical">
+ *         <label class=${fieldLabelClass()} data-slot="field-label" for="name">Name</label>
+ *         <input class=${inputClass()} id="name" name="name" value="Ada" aria-describedby="name-desc">
+ *         <p class=${fieldDescriptionClass()} id="name-desc">Shown on your public page.</p>
+ *       </div>
+ *       <div class=${fieldClass()} data-slot="field" data-orientation="vertical" data-invalid="true">
+ *         <label class=${fieldLabelClass()} data-slot="field-label" for="email">Email</label>
+ *         <input class=${inputClass()} id="email" name="email" type="email" value="ada@" aria-invalid="true" aria-describedby="email-error">
+ *         <div class=${fieldErrorClass()} id="email-error" role="alert">Enter a valid email address.</div>
+ *       </div>
+ *       <div class=${fieldSeparatorClass()} role="none"><span class=${fieldSeparatorContentClass()}>Notifications</span></div>
+ *       <div class=${fieldClass({ orientation: 'horizontal' })} data-slot="field" data-orientation="horizontal">
+ *         <input class=${checkboxClass()} data-slot="checkbox" type="checkbox" id="digest" name="digest">
+ *         <label class=${fieldLabelClass()} data-slot="field-label" for="digest">Send me a weekly digest</label>
+ *       </div>
+ *     </div>
+ *   </fieldset>
+ * </form>
+ * ```
+ */
+
+export type FieldLegendVariant = 'legend' | 'label';
+export type FieldOrientation = 'vertical' | 'horizontal' | 'responsive';
+
+const LEGEND_VARIANTS = {
+  legend: 'cn-field-legend-variant-legend',
+  label: 'cn-field-legend-variant-label',
+} as const;
+
+// shadcn's `*:w-full` widens a field's control because the control is the
+// field's child. A `<ui-select>` host is `display: contents` and its trigger
+// (or, before it upgrades, the native select) sits two levels down, so the
+// same width reaches through the host to it.
+const ORIENTATIONS = {
+  vertical: 'cn-field-orientation-vertical flex-col *:w-full [&>.sr-only]:w-auto [&>ui-select_:is(select,[data-slot=select-trigger])]:w-full',
+  horizontal: 'cn-field-orientation-horizontal flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px',
+  responsive: 'cn-field-orientation-responsive flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px [&>ui-select_:is(select,[data-slot=select-trigger])]:w-full @md/field-group:[&>ui-select_:is(select,[data-slot=select-trigger])]:w-auto',
+} as const;
+
+/** Field set: a native `<fieldset>` holding a legend and a group of fields. */
+export const fieldSetClass = (): string =>
+  'cn-field-set flex flex-col';
+
+/**
+ * Field legend: the `<legend>` naming a field set. `legend` is section-sized,
+ * `label` matches a field label (for a radio or checkbox set). Set
+ * `data-variant="<variant>"` on the same element so a following description
+ * tightens its spacing.
+ */
+export function fieldLegendClass(opts: { variant?: FieldLegendVariant } = {}): string {
+  return 'cn-field-legend ' + LEGEND_VARIANTS[opts.variant ?? 'legend'];
+}
+
+/** Field group: stacks fields, and is the container `responsive` fields measure. */
+export const fieldGroupClass = (): string =>
+  'cn-field-group group/field-group @container/field-group flex w-full flex-col';
+
+/**
+ * Field: one label + control + text unit. `vertical` stacks them, `horizontal`
+ * puts the control beside the label (checkbox, switch), and `responsive` stacks
+ * on a narrow group and goes side by side from the group's `md` width.
+ */
+export function fieldClass(opts: { orientation?: FieldOrientation } = {}): string {
+  return (
+    'cn-field group/field flex w-full ' +
+    ORIENTATIONS[opts.orientation ?? 'vertical']
+  );
+}
+
+/** Field content: wraps a label and description beside a horizontal control. */
+export const fieldContentClass = (): string =>
+  'cn-field-content group/field-content flex flex-1 flex-col leading-snug';
+
+/** Field label: the `<label for>` of the control. Fades when the field is data-disabled. */
+export const fieldLabelClass = (): string =>
+  'cn-label cn-field-label group/field-label peer/field-label flex w-fit items-center select-none group-data-[disabled=true]:pointer-events-none peer-disabled:cursor-not-allowed has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col';
+
+/** Field title: label-styled text that is not a `<label>` (a choice card's heading). */
+export const fieldTitleClass = (): string =>
+  'cn-field-title flex w-fit items-center';
+
+/** Field description: the muted helper text under (or beside) the control. */
+export const fieldDescriptionClass = (): string =>
+  'cn-field-description leading-normal font-normal group-has-data-horizontal/field:text-balance last:mt-0 nth-last-2:-mt-1 [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary';
+
+/** Field error: the inline validation message. Give it an id the control's aria-describedby lists. */
+export const fieldErrorClass = (): string => 'cn-field-error font-normal';
+
+/**
+ * Field separator: a horizontal rule between fields, drawn by the element's own
+ * `::before`, with optional centred text in a `fieldSeparatorContentClass()`
+ * span.
+ */
+export const fieldSeparatorClass = (): string =>
+  'cn-field-separator relative before:absolute before:inset-x-0 before:top-1/2 before:h-px before:bg-border';
+
+/** Field separator content: the text on the separator line (`or`, a section name). */
+export const fieldSeparatorContentClass = (): string =>
+  'cn-field-separator-content relative mx-auto block w-fit bg-background';

package/packages/registry/components/floating.ts

@@ -0,0 +1,124 @@
+/**
+ * Floating placement: positions a panel beside the element that opened it.
+ * Tier-2 support module. The kit's overlays that measure their own placement
+ * (tooltip, hover card, the dropdown, context and menubar menus, select,
+ * combobox) import `positionFloating` from here, and so does a hand-built
+ * popover that wants measured placement.
+ *
+ * It is its own module because it reads the window and the elements' boxes,
+ * which is browser code. Kept beside the popover's class helpers, it would make
+ * every page importing `popoverContentClass` ship to the browser whole, the
+ * same reason `cn()` and the DOM helpers are separate modules.
+ */
+import type { PopoverSide, PopoverAlign } from './popover.ts';
+
+/**
+ * Places `content` beside `trigger`, flipping to the opposite side when it
+ * does not fit, and keeps it 8px inside the viewport.
+ *
+ * `radix` names the component the way Radix does (`dropdown-menu`,
+ * `tooltip`), and makes this set the variables Radix's positioner sets on the
+ * panel, which shadcn's classes read: `--radix-<name>-trigger-width` /
+ * `-height`, `--radix-<name>-content-available-width` / `-height` and
+ * `--radix-<name>-content-transform-origin`. Without them a class such as
+ * `w-(--radix-dropdown-menu-trigger-width)` resolves to nothing, and a fixed
+ * panel with no width stretches across the viewport.
+ */
+export function positionFloating(
+  trigger: HTMLElement,
+  content: HTMLElement,
+  opts: {
+    side?: PopoverSide;
+    align?: PopoverAlign;
+    sideOffset?: number;
+    alignOffset?: number;
+    radix?: string;
+  } = {},
+): void {
+  const side = opts.side ?? 'bottom';
+  const align = opts.align ?? 'center';
+  const sideOffset = opts.sideOffset ?? 4;
+  const alignOffset = opts.alignOffset ?? 0;
+  const tr = trigger.getBoundingClientRect();
+  const vars = opts.radix ? `--radix-${opts.radix}` : '';
+  // The trigger's size first: a panel sized from it can only be measured
+  // once it is set.
+  if (vars) {
+    content.style.setProperty(`${vars}-trigger-width`, `${tr.width}px`);
+    content.style.setProperty(`${vars}-trigger-height`, `${tr.height}px`);
+  }
+  const cr = content.getBoundingClientRect();
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+
+  let top = 0;
+  let left = 0;
+  let actualSide = side;
+
+  const fitsBottom = tr.bottom + sideOffset + cr.height <= vh;
+  const fitsTop = tr.top - sideOffset - cr.height >= 0;
+  const fitsRight = tr.right + sideOffset + cr.width <= vw;
+  const fitsLeft = tr.left - sideOffset - cr.width >= 0;
+
+  if (side === 'bottom' && !fitsBottom && fitsTop) actualSide = 'top';
+  else if (side === 'top' && !fitsTop && fitsBottom) actualSide = 'bottom';
+  else if (side === 'right' && !fitsRight && fitsLeft) actualSide = 'left';
+  else if (side === 'left' && !fitsLeft && fitsRight) actualSide = 'right';
+
+  if (actualSide === 'bottom') top = tr.bottom + sideOffset;
+  else if (actualSide === 'top') top = tr.top - sideOffset - cr.height;
+  else if (actualSide === 'right' || actualSide === 'left') {
+    if (align === 'start') top = tr.top;
+    else if (align === 'end') top = tr.bottom - cr.height;
+    else top = tr.top + (tr.height - cr.height) / 2;
+  }
+
+  if (actualSide === 'right') left = tr.right + sideOffset;
+  else if (actualSide === 'left') left = tr.left - sideOffset - cr.width;
+  else {
+    if (align === 'start') left = tr.left;
+    else if (align === 'end') left = tr.right - cr.width;
+    else left = tr.left + (tr.width - cr.width) / 2;
+  }
+
+  // alignOffset shifts the popover along the align axis. For align='start',
+  // positive shifts AWAY from the start edge; align='end' reverses; center
+  // is a no-op. Axis is perpendicular to the chosen side.
+  if (align !== 'center' && alignOffset !== 0) {
+    const dir = align === 'start' ? 1 : -1;
+    if (actualSide === 'top' || actualSide === 'bottom') {
+      left += dir * alignOffset;
+    } else {
+      top += dir * alignOffset;
+    }
+  }
+
+  left = Math.max(8, Math.min(left, vw - cr.width - 8));
+  top = Math.max(8, Math.min(top, vh - cr.height - 8));
+
+  content.style.top = `${top}px`;
+  content.style.left = `${left}px`;
+  if (vars) {
+    // What Radix's size and transform-origin middleware report, with no
+    // collision padding and no arrow.
+    const availableHeight =
+      actualSide === 'bottom' ? vh - tr.bottom - sideOffset
+        : actualSide === 'top' ? tr.top - sideOffset
+          : vh;
+    const availableWidth =
+      actualSide === 'right' ? vw - tr.right - sideOffset
+        : actualSide === 'left' ? tr.left - sideOffset
+          : vw;
+    const along = align === 'start' ? '0%' : align === 'end' ? '100%' : '50%';
+    const origin =
+      actualSide === 'bottom' ? `${along} 0px`
+        : actualSide === 'top' ? `${along} 100%`
+          : actualSide === 'right' ? `0px ${along}`
+            : `100% ${along}`;
+    content.style.setProperty(`${vars}-content-available-height`, `${Math.max(0, availableHeight)}px`);
+    content.style.setProperty(`${vars}-content-available-width`, `${Math.max(0, availableWidth)}px`);
+    content.style.setProperty(`${vars}-content-transform-origin`, origin);
+  }
+  content.setAttribute('data-side', actualSide);
+  content.setAttribute('data-align', align);
+}

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

@@ -21,8 +21,9 @@
  *   `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.
+ * Events:
+ *   `ui-open-change` on <ui-hover-card>: `{ detail: { open } }` on every open
+ *   and close, shadcn's `onOpenChange`. The `open` attribute is reflected too.
  *
  * Programmatic API on <ui-hover-card>: `.show()` · `.hide()`.
  *
@@ -70,16 +71,18 @@
  * ```
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
-import { ensureId } from '../lib/utils.ts';
+import { cn, ensureId, takeAuthoredClass } from '../lib/utils.ts';
 import { onBeforeCache } from '../lib/dom.ts';
-import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
+import { positionFloating } from './floating.ts';
+import type { PopoverSide, 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.
+// visual layer sits on top. `not-open:hidden` hides a closed panel, which
+// the UA `[popover]:not(:popover-open)` rule cannot do once any author
+// `display` applies (see popoverContentClass).
 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';
+  'cn-hover-card-content z-50 origin-(--radix-hover-card-content-transform-origin) outline-hidden not-open:hidden';
 
 // --------------------------------------------------------------------------
 // <ui-hover-card>
@@ -314,6 +317,7 @@ export class UiHoverCard extends WebComponent({
     // engines with no Popover API: Escape has to work regardless of that.
     if (this.open) this._bindEscape();
     else this._unbindEscape();
+    this.dispatchEvent(new CustomEvent('ui-open-change', { detail: { open: this.open }, bubbles: true }));
     // Wait one microtask for <ui-hover-card-content>'s inner [popover]
     // element to commit; we drive its showPopover() / hidePopover() and
     // refresh the trigger's aria-expanded.
@@ -352,6 +356,7 @@ export class UiHoverCard extends WebComponent({
       align: (contentHost.getAttribute('align') ?? 'center') as PopoverAlign,
       sideOffset: Number(contentHost.getAttribute('side-offset') ?? 4),
       alignOffset: Number(contentHost.getAttribute('align-offset') ?? 0),
+      radix: this.localName.slice(3),
     });
   }
 }
@@ -419,12 +424,18 @@ UiHoverCardTrigger.register('ui-hover-card-trigger');
 // --------------------------------------------------------------------------
 
 export class UiHoverCardContent extends WebComponent {
+  _authored: string | null = null;
+
+  // shadcn's className on HoverCardContent lands on the card panel (a `w-80`,
+  // say), so the class written on this host moves there, read once at first
+  // render.
   render() {
+    this._authored = takeAuthoredClass(this, null);
     return html`<div
       data-slot="hover-card-content"
       role="dialog"
       popover="manual"
-      class=${hoverCardContentClass()}
+      class=${cn(hoverCardContentClass(), this._authored)}
       @mouseenter=${this._onEnter}
       @mouseleave=${this._onLeave}
       @focusin=${this._onEnter}

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

@@ -0,0 +1,118 @@
+/**
+ * Input group: an input or textarea with addons inside its border (an icon, a
+ * prefix such as "https://", a button, a counter), sharing one focus ring.
+ * Tier-1 class helper; compose with a real `<input>` or `<textarea>`.
+ *
+ * shadcn parity:
+ *   InputGroup                 → inputGroupClass()
+ *   InputGroupAddon (align: inline-start | inline-end | block-start | block-end)
+ *                              → inputGroupAddonClass({ align }), alias inputGroupAddonVariants,
+ *                                plus the same `data-align` on the addon (the styles pad the
+ *                                control beside it by it)
+ *   InputGroupButton (size)    → inputGroupButtonClass({ size }) with buttonClass({ variant })
+ *   InputGroupText             → inputGroupTextClass()
+ *   InputGroupInput / InputGroupTextarea
+ *                              → inputGroupInputClass() / inputGroupTextareaClass()
+ *
+ * The group draws the border and the focus ring, so the control inside drops
+ * its own. Clicking an addon focuses the control through a `<label for>`, with
+ * no script: make the addon a `<label>` pointing at the control's id.
+ *
+ * A11y (required for accessible output): the control still needs its own
+ * accessible name, from a visible `<label for>` outside the group or an
+ * `aria-label` on the control; an addon's text is not its name. A decorative
+ * icon addon takes `aria-hidden="true"`. An addon button is a real
+ * `<button type="button">` with its own name.
+ *
+ * Design tokens used: --input, --ring, --muted-foreground, --destructive.
+ *
+ * @example
+ * ```html
+ * <div class=${inputGroupClass()} data-slot="input-group" role="group">
+ *   <label class=${inputGroupAddonClass()} data-slot="input-group-addon" data-align="inline-start" for="site">https://</label>
+ *   <input class=${inputGroupInputClass()} data-slot="input-group-control" id="site" name="site" aria-label="Website">
+ * </div>
+ * ```
+ */
+import { cn } from '../lib/utils.ts';
+import { inputClass } from './input.ts';
+import { textareaClass } from './textarea.ts';
+import { buttonClass, type ButtonVariant } from './button.ts';
+
+/** Set `data-slot="input-group"` on the element. */
+export function inputGroupClass(): string {
+  return 'group/input-group cn-input-group relative flex w-full min-w-0 items-center outline-none has-[>textarea]:h-auto';
+}
+
+const INPUT_GROUP_ADDON_BASE =
+  'cn-input-group-addon flex cursor-text items-center justify-center select-none';
+
+const INPUT_GROUP_ADDON_ALIGNS = {
+  'inline-start': 'cn-input-group-addon-align-inline-start order-first',
+  'inline-end': 'cn-input-group-addon-align-inline-end order-last',
+  'block-start': 'cn-input-group-addon-align-block-start order-first w-full justify-start',
+  'block-end': 'cn-input-group-addon-align-block-end order-last w-full justify-start',
+} as const;
+
+/** The part, with its variant options. Set its `data-slot` and any `data-variant` / `data-size` to match. */
+export function inputGroupAddonClass(opts: { align?: keyof typeof INPUT_GROUP_ADDON_ALIGNS } = {}): string {
+  return cn(INPUT_GROUP_ADDON_BASE, INPUT_GROUP_ADDON_ALIGNS[opts.align ?? 'inline-start']);
+}
+
+/**
+ * shadcn's name for {@link inputGroupAddonClass}, so shadcn code ports verbatim. Like cva,
+ * it merges a `className` into the result.
+ */
+export function inputGroupAddonVariants(opts: { align?: keyof typeof INPUT_GROUP_ADDON_ALIGNS } & { className?: string } = {}): string {
+  return cn(inputGroupAddonClass(opts), opts.className);
+}
+
+const INPUT_GROUP_BUTTON_BASE =
+  'cn-input-group-button flex items-center shadow-none';
+
+const INPUT_GROUP_BUTTON_SIZES = {
+  xs: 'cn-input-group-button-size-xs',
+  sm: 'cn-input-group-button-size-sm',
+  'icon-xs': 'cn-input-group-button-size-icon-xs',
+  'icon-sm': 'cn-input-group-button-size-icon-sm',
+} as const;
+
+/**
+ * The part, with its variant options. Set its `data-slot` and any `data-variant` / `data-size` to match.
+ *
+ * shadcn's InputGroupButton IS its Button (`variant` defaulting to ghost)
+ * with these classes on top, so the button's own classes come first and the
+ * group's size wins a conflict.
+ */
+export function inputGroupButtonClass(opts: { size?: keyof typeof INPUT_GROUP_BUTTON_SIZES; variant?: ButtonVariant } = {}): string {
+  return cn(buttonClass({ variant: opts.variant ?? 'ghost' }), INPUT_GROUP_BUTTON_BASE, INPUT_GROUP_BUTTON_SIZES[opts.size ?? 'xs']);
+}
+
+/**
+ * shadcn's name for {@link inputGroupButtonClass}, so shadcn code ports verbatim. Like cva,
+ * it merges a `className` into the result.
+ */
+export function inputGroupButtonVariants(opts: { size?: keyof typeof INPUT_GROUP_BUTTON_SIZES; variant?: ButtonVariant } & { className?: string } = {}): string {
+  return cn(inputGroupButtonClass(opts), opts.className);
+}
+
+/** A part with no `data-slot` of its own. */
+export function inputGroupTextClass(): string {
+  return 'cn-input-group-text flex items-center [&_svg]:pointer-events-none';
+}
+
+/**
+ * Set `data-slot="input-group-control"` on the element. shadcn's
+ * InputGroupInput is its Input with these classes on top, so the input's own
+ * base (its `outline-none` and focus treatment included) comes first and the
+ * group's resets win a conflict. Without it a focused control shows the
+ * browser's own outline inside the group's ring.
+ */
+export function inputGroupInputClass(): string {
+  return cn(inputClass(), 'cn-input-group-input flex-1');
+}
+
+/** Set `data-slot="input-group-control"` on the element. The Textarea's classes, then the group's, as shadcn composes it. */
+export function inputGroupTextareaClass(): string {
+  return cn(textareaClass(), 'cn-input-group-textarea flex-1 resize-none');
+}