@webjsdev/ui 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "description": "An AI-first component library - class-helper functions for visuals, custom elements only where state matters. Source-copied into your repo, you own it. Works with any Tailwind v4 project.",
   "bin": {
@@ -15,6 +15,7 @@
   "files": [
     "bin",
     "src",
+    "packages/registry",
     "README.md"
   ],
   "scripts": {
@@ -31,11 +32,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vivek7405/webjs.git",
+    "url": "git+https://github.com/webjsdev/webjs.git",
     "directory": "packages/ui"
   },
   "homepage": "https://ui.webjs.dev",
-  "bugs": "https://github.com/vivek7405/webjs/issues",
+  "bugs": "https://github.com/webjsdev/webjs/issues",
   "license": "MIT",
   "keywords": [
     "shadcn",

package/packages/registry/README.md

@@ -0,0 +1,35 @@
+# @webjsdev/ui-registry
+
+Internal: sources for the `@webjsdev/ui` component registry.
+
+Not published. `registry.json` is the manifest, and the files it points at
+are the source of truth. The website
+([`@webjsdev/ui-website`](../ui-website)) composes shadcn-compatible JSON on
+demand and serves it at `https://ui.webjs.dev/registry/<name>.json`, which the
+`@webjsdev/ui` CLI fetches. There is no build step, no generated output, no
+`prestart` hook.
+
+## Layout
+
+```
+components/        one .ts per shadcn component (web component port, light DOM + Tailwind)
+lib/               shared lib code shipped into user projects (utils.ts → cn)
+themes/
+  index.css        neutral @theme block + CSS variables (light + dark defaults)
+  base-colors.js   per-base-colour overrides (stone, zinc, mauve, olive, mist, taupe) + mergeThemeCss
+registry.json      manifest read by the website composer at request time
+```
+
+Only `theme-neutral` is in `registry.json`. The other 6 base colours are
+synthesized by the composer at request time: neutral CSS + per-colour
+overrides → merged CSS, same `files[]` shape.
+
+## Wire endpoints
+
+Served by `@webjsdev/ui-website` (`app/_lib/registry.server.ts` +
+`app/registry/**`):
+
+- `GET /registry/<name>.json`: single registry item (`type: registry:ui` /
+  `registry:theme` / `registry:lib`), with file contents inlined.
+- `GET /registry/index.json`: flat metadata-only list.
+- `GET /registry`: full manifest with every item's content inlined.

package/packages/registry/components/accordion.ts

@@ -0,0 +1,74 @@
+/**
+ * Accordion: vertical collapsible list built on native <details>/<summary>.
+ *
+ * Tier-1 (no custom element). Exclusive open behaviour (Radix's
+ * `type="single"`) comes from giving every <details> the same
+ * `name="..."` attribute. Independent open (`type="multiple"`) is the
+ * default when `name` is omitted. Both modes give `collapsible` for
+ * free: clicking the open <summary> closes it.
+ *
+ * shadcn parity:
+ *   <Accordion type="single" collapsible> → <div class=${accordionClass()}> wrapping
+ *                                            <details name="..."> items
+ *   <Accordion type="multiple">           → same, omit `name`
+ *   <AccordionItem>                       → <details class=${accordionItemClass()}>
+ *   <AccordionTrigger>                    → <summary class=${accordionTriggerClass()}>
+ *   <AccordionContent>                    → <div class=${accordionContentClass()}>
+ *
+ * Usage (single-open, exclusive):
+ *   <div class=${accordionClass()}>
+ *     <details name="faq" class=${accordionItemClass()}>
+ *       <summary class=${accordionTriggerClass()}>
+ *         <span>Is it accessible?</span>
+ *         <svg class="size-4 transition-transform group-open:rotate-180">…</svg>
+ *       </summary>
+ *       <div class=${accordionContentClass()}>Yes, native disclosure widget.</div>
+ *     </details>
+ *     <details name="faq" class=${accordionItemClass()} open>
+ *       <summary class=${accordionTriggerClass()}>Is it styled?</summary>
+ *       <div class=${accordionContentClass()}>Yes, shadcn design tokens.</div>
+ *     </details>
+ *   </div>
+ *
+ * Initial state: add `open` on the <details> that should render expanded
+ * on first paint. Programmatic toggling: `el.open = true | false`.
+ *
+ * `<details name="X">` is the platform's exclusive-accordion primitive:
+ * Chrome 120+, Safari 17.2+, Firefox 130+. Migrated from the prior
+ * <ui-accordion> custom element set.
+ *
+ * Design tokens used: --border, --ring, --foreground.
+ */
+
+/** Root wrapper. Holds the column-of-items rhythm; no display: rules. */
+export const accordionClass = (): string => 'w-full';
+
+/**
+ * Item: each <details>. The `group` utility lets the trigger's chevron
+ * rotate on open via `group-open:rotate-180`. `last:border-b-0` cleans
+ * the trailing edge.
+ */
+export const accordionItemClass = (): string => 'group border-b last:border-b-0';
+
+/**
+ * Trigger: applied to <summary>. Hides the native disclosure triangle so
+ * authors can compose their own chevron icon (typical pattern: trailing
+ * lucide chevron with `group-open:rotate-180`).
+ *
+ * `disabled: true` returns the visual disabled state (greyed out,
+ * not-allowed cursor, no pointer events). For true keyboard prevention
+ *, the native disabled-disclosure-widget gap, add the standard
+ * `inert` attribute to the <details> element. shadcn's React `disabled`
+ * prop combines both; native HTML has no `disabled` on <details>.
+ */
+export const accordionTriggerClass = (opts: { disabled?: boolean } = {}): string => {
+  const base = 'flex w-full cursor-pointer list-none items-center justify-between gap-4 py-4 text-left text-sm font-medium outline-none transition-all hover:underline focus-visible:ring-2 focus-visible:ring-ring/50 marker:hidden [&::-webkit-details-marker]:hidden';
+  if (opts.disabled) return `${base} pointer-events-none cursor-not-allowed opacity-50`;
+  return base;
+};
+
+/**
+ * Content: <details> hides this entirely when not [open], so all we add
+ * is the typography rhythm matching shadcn (bottom padding, small text).
+ */
+export const accordionContentClass = (): string => 'pb-4 text-sm';

package/packages/registry/components/alert-dialog.ts

@@ -0,0 +1,359 @@
+/**
+ * AlertDialog: modal requiring explicit Cancel / Action confirmation.
+ * Tier-2. Variant of Dialog with `role="alertdialog"`, no
+ * Escape-to-close, no overlay-click-to-close. Built on the native
+ * `<dialog>` element.
+ *
+ * APG pattern: https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/
+ *
+ * Composition follows dialog.ts: `<ui-alert-dialog-content>` owns the
+ * native `<dialog>` (its render() emits the `<dialog>` wrapper around
+ * its slotted content); the parent tracks open state and drives
+ * showModal() / close() on the content child. Every <slot> is a default
+ * slot, so SSR doesn't need to route children by name (which wouldn't
+ * work because slot="..." set in connectedCallback never runs
+ * server-side).
+ *
+ * shadcn parity:
+ *   AlertDialog              → <ui-alert-dialog open>
+ *   AlertDialogTrigger       → <ui-alert-dialog-trigger>
+ *   AlertDialogContent       → <ui-alert-dialog-content size>
+ *   AlertDialogHeader        → <div class=${alertDialogHeaderClass()}>
+ *   AlertDialogTitle         → <h2 class=${alertDialogTitleClass()}>
+ *   AlertDialogDescription   → <p class=${alertDialogDescriptionClass()}>
+ *   AlertDialogFooter        → <div class=${alertDialogFooterClass()}>
+ *   AlertDialogAction        → <ui-alert-dialog-action variant size>
+ *   AlertDialogCancel        → <ui-alert-dialog-cancel variant size>
+ *
+ * Usage:
+ *   <ui-alert-dialog>
+ *     <ui-alert-dialog-trigger>
+ *       <button class=${buttonClass({ variant: 'destructive' })}>Delete</button>
+ *     </ui-alert-dialog-trigger>
+ *     <ui-alert-dialog-content>
+ *       <div class=${alertDialogHeaderClass()}>
+ *         <h2 class=${alertDialogTitleClass()}>Delete account?</h2>
+ *         <p class=${alertDialogDescriptionClass()}>This cannot be undone.</p>
+ *       </div>
+ *       <div class=${alertDialogFooterClass()}>
+ *         <ui-alert-dialog-cancel>Cancel</ui-alert-dialog-cancel>
+ *         <ui-alert-dialog-action variant="destructive">Delete</ui-alert-dialog-action>
+ *       </div>
+ *     </ui-alert-dialog-content>
+ *   </ui-alert-dialog>
+ *
+ * Attributes on <ui-alert-dialog>:
+ *   `open`:  boolean (reflected). Presence shows the dialog.
+ *
+ * Attributes on <ui-alert-dialog-content>:
+ *   `size`:  "default" (default) | "sm". The sm size flips the footer to
+ *           a 2-column grid with full-width buttons.
+ *
+ * Attributes on <ui-alert-dialog-action> / <ui-alert-dialog-cancel>:
+ *   `variant`: ButtonVariant. Action defaults to "default", cancel to "outline".
+ *   `size`:    ButtonSize. Defaults to "default".
+ *
+ * Events: none dispatched at present (no `ui-open-change`); observe the
+ * reflected `open` attribute on `<ui-alert-dialog>`.
+ *
+ * Programmatic API on <ui-alert-dialog>: `.show()` · `.hide()`.
+ *
+ * Keyboard: Escape is blocked (alert dialogs require explicit choice);
+ * Tab cycles trapped within the dialog (native focus trap).
+ *
+ * Design tokens used: --background, --border, --muted-foreground.
+ */
+import { WebComponent, html } from '@webjsdev/core';
+import { buttonClass, type ButtonVariant, type ButtonSize } from './button.ts';
+
+export const alertDialogContentClass = (): string =>
+  'group/alert-dialog-content fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border bg-background p-6 shadcn-lg shadow-lg duration-200 data-[size=sm]:max-w-xs data-[size=default]:sm:max-w-lg';
+
+export const alertDialogHeaderClass = (): string =>
+  'grid grid-rows-[auto_1fr] place-items-center gap-1.5 text-center sm:group-data-[size=default]/alert-dialog-content:place-items-start sm:group-data-[size=default]/alert-dialog-content:text-left';
+
+export const alertDialogFooterClass = (): string =>
+  'flex flex-col-reverse gap-2 group-data-[size=sm]/alert-dialog-content:grid group-data-[size=sm]/alert-dialog-content:grid-cols-2 sm:flex-row sm:justify-end';
+
+export const alertDialogTitleClass = (): string => 'text-lg font-semibold';
+
+export const alertDialogDescriptionClass = (): string => 'text-sm text-muted-foreground';
+
+// Pre-hydration paint fallback (see dialog.ts for the long version).
+const STYLES = `
+ui-alert-dialog:not([open]) ui-alert-dialog-content { display: none !important; }
+ui-alert-dialog-content { display: grid; }
+`;
+
+const NATIVE_DIALOG_CLASS = 'border-0 bg-transparent p-0 m-0 w-0 h-0 max-w-none max-h-none overflow-visible text-inherit backdrop:bg-black/50';
+
+function installStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('ui-alert-dialog-styles')) return;
+  const style = document.createElement('style');
+  style.id = 'ui-alert-dialog-styles';
+  style.textContent = STYLES;
+  document.head.appendChild(style);
+}
+
+// Body scroll lock. Refcounted so nested dialogs unlock in order. Kept in
+// lockstep with dialog.ts (not imported) so `webjs ui add alert-dialog`
+// doesn't pull in the full dialog component.
+let scrollLockCount = 0;
+let savedOverflow = '';
+let savedPaddingRight = '';
+
+function lockScroll(): void {
+  if (scrollLockCount === 0) {
+    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+    savedOverflow = document.body.style.overflow;
+    savedPaddingRight = document.body.style.paddingRight;
+    document.body.style.overflow = 'hidden';
+    if (scrollbarWidth > 0) document.body.style.paddingRight = `${scrollbarWidth}px`;
+  }
+  scrollLockCount++;
+}
+
+function unlockScroll(): void {
+  scrollLockCount = Math.max(0, scrollLockCount - 1);
+  if (scrollLockCount === 0) {
+    document.body.style.overflow = savedOverflow;
+    document.body.style.paddingRight = savedPaddingRight;
+  }
+}
+
+// --------------------------------------------------------------------------
+// <ui-alert-dialog>
+// Owns the open state. Defers the actual <dialog> element to the child
+// <ui-alert-dialog-content>, so no named slot is needed (which avoids
+// the SSR slot-routing problem). Drives showModal() / close() on the
+// content child via prop transitions.
+// --------------------------------------------------------------------------
+
+export class UiAlertDialog extends WebComponent {
+  static properties = {
+    open: { type: Boolean, reflect: true },
+  };
+  declare open: boolean;
+
+  constructor() {
+    super();
+    this.open = false;
+  }
+
+  connectedCallback(): void {
+    installStyles();
+    // Legacy <ui-alert-dialog-overlay> isn't supported anymore; the native
+    // ::backdrop pseudo replaces it. Strip it if a stale doc uses it.
+    this.querySelector<HTMLElement>(':scope > ui-alert-dialog-overlay')?.remove();
+    super.connectedCallback?.();
+  }
+
+  disconnectedCallback(): void {
+    if (this.open) this._teardown();
+    super.disconnectedCallback?.();
+  }
+
+  show(): void { this.open = true; }
+  hide(): void { this.open = false; }
+
+  // Back-compat getter alongside the reactive `open` prop.
+  get isOpen(): boolean { return this.open; }
+
+  render() {
+    return html`<div data-slot="alert-dialog" data-state=${this.open ? 'open' : 'closed'}>
+      <slot></slot>
+    </div>`;
+  }
+
+  updated(changedProperties: Map<string, unknown>): void {
+    if (!changedProperties.has('open')) return;
+    // Skip the constructor's initial open=false set so we don't fire
+    // teardown for the closed-on-mount state.
+    if (changedProperties.get('open') === undefined) return;
+    // Defer one microtask so the content child has rendered its inner
+    // native <dialog>; that's where showModal() / close() act.
+    queueMicrotask(() => {
+      if (this.open) this._setup();
+      else this._teardown();
+    });
+  }
+
+  get _content(): UiAlertDialogContent | null {
+    return this.querySelector('ui-alert-dialog-content') as UiAlertDialogContent | null;
+  }
+
+  _setup(): void {
+    const content = this._content;
+    if (!content) return;
+    lockScroll();
+    content.showModal();
+  }
+
+  _teardown(): void {
+    unlockScroll();
+    this._content?.close();
+  }
+}
+UiAlertDialog.register('ui-alert-dialog');
+
+// --------------------------------------------------------------------------
+// <ui-alert-dialog-trigger>
+// --------------------------------------------------------------------------
+
+export class UiAlertDialogTrigger extends WebComponent {
+  render() {
+    return html`<div
+      data-slot="alert-dialog-trigger"
+      @click=${this._onClick}
+    ><slot></slot></div>`;
+  }
+
+  _onClick = (): void => (this.closest('ui-alert-dialog') as UiAlertDialog | null)?.show();
+}
+UiAlertDialogTrigger.register('ui-alert-dialog-trigger');
+
+// --------------------------------------------------------------------------
+// <ui-alert-dialog-content>
+// Owns the native <dialog> element. Renders a <dialog> wrapper around its
+// slotted children. Exposes showModal() / close() so the parent
+// <ui-alert-dialog> can drive the open state imperatively without a
+// named slot. Escape-to-close is blocked here (alert dialogs require an
+// explicit choice via Cancel / Action).
+// --------------------------------------------------------------------------
+
+export class UiAlertDialogContent extends WebComponent {
+  static properties = {
+    size: { type: String, reflect: true },
+  };
+  declare size: 'default' | 'sm';
+
+  constructor() {
+    super();
+    this.size = 'default';
+  }
+
+  showModal(): void {
+    const native = this.querySelector<HTMLDialogElement>('dialog[data-slot="alert-dialog-native"]');
+    if (native && !native.open) native.showModal();
+  }
+
+  close(): void {
+    const native = this.querySelector<HTMLDialogElement>('dialog[data-slot="alert-dialog-native"]');
+    if (native?.open) native.close();
+  }
+
+  render() {
+    const parentOpen = !!this._parent()?.open;
+    return html`<dialog
+      data-slot="alert-dialog-native"
+      class=${NATIVE_DIALOG_CLASS}
+      @cancel=${this._onNativeCancel}
+      @close=${this._onNativeClose}
+    ><div
+      data-slot="alert-dialog-content"
+      role="alertdialog"
+      aria-modal="true"
+      tabindex="-1"
+      data-size=${this.size}
+      data-state=${parentOpen ? 'open' : 'closed'}
+      class=${alertDialogContentClass()}
+    ><slot></slot></div></dialog>`;
+  }
+
+  // Block native Escape-to-close. Alert dialogs require an explicit
+  // Cancel / Action choice.
+  _onNativeCancel = (e: Event): void => e.preventDefault();
+  _onNativeClose = (): void => {
+    const p = this._parent();
+    if (p?.open) p.open = false;
+  };
+
+  // SSR-safe: linkedom doesn't implement closest() on custom elements.
+  _parent(): UiAlertDialog | null {
+    if (typeof this.closest !== 'function') return null;
+    return this.closest('ui-alert-dialog') as UiAlertDialog | null;
+  }
+}
+UiAlertDialogContent.register('ui-alert-dialog-content');
+
+// --------------------------------------------------------------------------
+// <ui-alert-dialog-cancel> + <ui-alert-dialog-action>
+// shadcn's <AlertDialogAction> and <AlertDialogCancel> ARE button-styled
+// elements with forwarded `variant` and `size` props. Each renders its
+// own native <button> with @click handler; the user's label text or
+// inline icon SVG projects through a slot inside that button.
+//
+// Authoring is bare text / icons, not a wrapped <button>:
+//
+//   <ui-alert-dialog-cancel>Cancel</ui-alert-dialog-cancel>
+//   <ui-alert-dialog-action variant="destructive">Delete</ui-alert-dialog-action>
+//
+// (A legacy wrap-a-button form used to be supported by sniffing for an
+// authored <button> in connectedCallback. SSR rendered the wrong branch
+// because connectedCallback never fires server-side, producing invalid
+// nested-<button> HTML that the parser flattened into siblings -- the
+// "buttons have no text" symptom. Removed in favour of one canonical
+// authoring shape that works in both SSR and CSR.)
+//
+// The extra `group-data-[size=sm]/alert-dialog-content:w-full` class
+// makes the inner button stretch when the parent's footer flips to
+// `grid grid-cols-2` (size=sm); otherwise the inline-flex button is
+// content-width and sits at the start of its grid cell.
+// --------------------------------------------------------------------------
+
+const ALERT_DIALOG_ACTION_GRID_STRETCH = 'group-data-[size=sm]/alert-dialog-content:w-full';
+
+export class UiAlertDialogCancel extends WebComponent {
+  static properties = {
+    variant: { type: String, reflect: true },
+    size: { type: String, reflect: true },
+  };
+  declare variant: ButtonVariant;
+  declare size: ButtonSize;
+
+  constructor() {
+    super();
+    this.variant = 'outline';
+    this.size = 'default';
+  }
+
+  render() {
+    return html`<button
+      type="button"
+      data-slot="alert-dialog-cancel"
+      class="${buttonClass({ variant: this.variant, size: this.size })} ${ALERT_DIALOG_ACTION_GRID_STRETCH}"
+      @click=${this._onClick}
+    ><slot></slot></button>`;
+  }
+
+  _onClick = (): void => (this.closest('ui-alert-dialog') as UiAlertDialog | null)?.hide();
+}
+UiAlertDialogCancel.register('ui-alert-dialog-cancel');
+
+export class UiAlertDialogAction extends WebComponent {
+  static properties = {
+    variant: { type: String, reflect: true },
+    size: { type: String, reflect: true },
+  };
+  declare variant: ButtonVariant;
+  declare size: ButtonSize;
+
+  constructor() {
+    super();
+    this.variant = 'default';
+    this.size = 'default';
+  }
+
+  render() {
+    return html`<button
+      type="button"
+      data-slot="alert-dialog-action"
+      class="${buttonClass({ variant: this.variant, size: this.size })} ${ALERT_DIALOG_ACTION_GRID_STRETCH}"
+      @click=${this._onClick}
+    ><slot></slot></button>`;
+  }
+
+  _onClick = (): void => (this.closest('ui-alert-dialog') as UiAlertDialog | null)?.hide();
+}
+UiAlertDialogAction.register('ui-alert-dialog-action');

package/packages/registry/components/alert.ts

@@ -0,0 +1,51 @@
+/**
+ * Alert: informational banner. Tier-1 class helpers; compose with a
+ * native `<div role="alert">` (or `role="status"` for non-urgent updates).
+ *
+ * shadcn parity:
+ *   Alert (variant: default | destructive)  → alertClass({ variant })
+ *   AlertTitle                              → alertTitleClass()
+ *   AlertDescription                        → alertDescriptionClass()
+ *
+ * Usage:
+ *   <div role="alert" class=${alertClass()}>
+ *     <svg>…</svg>
+ *     <div data-slot="alert-title" class=${alertTitleClass()}>Heads up</div>
+ *     <div data-slot="alert-description" class=${alertDescriptionClass()}>
+ *       Something happened. Probably fine.
+ *     </div>
+ *   </div>
+ *
+ *   <!-- Destructive variant: accent stripe + colored title/description. -->
+ *   <div role="alert" class=${alertClass({ variant: 'destructive' })}>
+ *     <svg>…</svg>
+ *     <div data-slot="alert-title" class=${alertTitleClass()}>Failed</div>
+ *     <div data-slot="alert-description" class=${alertDescriptionClass()}>
+ *       Couldn't save your changes.
+ *     </div>
+ *   </div>
+ *
+ * Design tokens used: --card, --card-foreground, --destructive, --muted-foreground.
+ */
+import { cn } from '../lib/utils.ts';
+
+const BASE =
+  'relative grid w-full grid-cols-[0_1fr] items-start gap-y-0.5 rounded-lg border px-4 py-3 text-sm has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] has-[>svg]:gap-x-3 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current';
+
+const VARIANTS = {
+  default: 'bg-card text-card-foreground',
+  destructive:
+    'bg-card text-destructive *:data-[slot=alert-description]:text-destructive/90 [&>svg]:text-current',
+} as const;
+
+export type AlertVariant = keyof typeof VARIANTS;
+
+export function alertClass(opts: { variant?: AlertVariant } = {}): string {
+  return cn(BASE, VARIANTS[opts.variant ?? 'default']);
+}
+
+export const alertTitleClass = (): string =>
+  'col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight';
+
+export const alertDescriptionClass = (): string =>
+  'col-start-2 grid justify-items-start gap-1 text-sm text-muted-foreground [&_p]:leading-relaxed';

package/packages/registry/components/aspect-ratio.ts

@@ -0,0 +1,22 @@
+/**
+ * AspectRatio: preserve a width:height ratio for its child. Tier-1
+ * class helper over the modern CSS `aspect-ratio` property (Baseline
+ * 2022). No JS, no custom element.
+ *
+ * shadcn parity:
+ *   AspectRatio (Radix primitive)  → aspectRatioClass() + inline `aspect-ratio` style
+ *
+ * Usage:
+ *   <div style="aspect-ratio: 16/9;" class="${aspectRatioClass()}">
+ *     <img src="…" class="h-full w-full object-cover rounded-md">
+ *   </div>
+ *
+ *   <!-- Or with Tailwind's arbitrary aspect-ratio (no helper needed): -->
+ *   <div class="aspect-[16/9]">
+ *     <img …>
+ *   </div>
+ *
+ * Design tokens used: none (layout only).
+ */
+
+export const aspectRatioClass = (): string => 'relative w-full';

package/packages/registry/components/avatar.ts

@@ -0,0 +1,52 @@
+/**
+ * Avatar: circular user image with fallback. Tier-1 class helpers;
+ * compose with a native `<span>` or `<img>`. The fallback shows when the
+ * `<img>` is missing or fails to load (`onerror`).
+ *
+ * shadcn parity:
+ *   Avatar (size: default | sm | lg)  → avatarClass({ size }) with `data-size`
+ *   AvatarImage                       → avatarImageClass()
+ *   AvatarFallback                    → avatarFallbackClass()
+ *   AvatarBadge                       → avatarBadgeClass()
+ *   AvatarGroup                       → avatarGroupClass()
+ *   AvatarGroupCount                  → avatarGroupCountClass()
+ *
+ * Usage:
+ *   <span class=${avatarClass()} data-size="default" data-slot="avatar">
+ *     <img class=${avatarImageClass()} src="…" alt="…">
+ *     <span class=${avatarFallbackClass()}>VK</span>
+ *   </span>
+ *
+ *   <div class=${avatarGroupClass()}>
+ *     <span class=${avatarClass()} data-size="default" data-slot="avatar">…</span>
+ *     <span class=${avatarClass()} data-size="default" data-slot="avatar">…</span>
+ *     <div class=${avatarGroupCountClass()}>+3</div>
+ *   </div>
+ *
+ * Design tokens used: --muted, --muted-foreground, --primary, --background.
+ */
+import { cn } from '../lib/utils.ts';
+
+export type AvatarSize = 'default' | 'sm' | 'lg';
+
+const AVATAR_BASE =
+  'group/avatar relative flex size-8 shrink-0 overflow-hidden rounded-full select-none data-[size=lg]:size-10 data-[size=sm]:size-6';
+
+export function avatarClass(_opts: { size?: AvatarSize } = {}): string {
+  // Size driven by data-size attribute on the element (matches shadcn).
+  return cn(AVATAR_BASE);
+}
+
+export const avatarImageClass = (): string => 'aspect-square size-full';
+
+export const avatarFallbackClass = (): string =>
+  'flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground group-data-[size=sm]/avatar:text-xs';
+
+export const avatarBadgeClass = (): string =>
+  'absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground ring-2 ring-background select-none group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2 group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2';
+
+export const avatarGroupClass = (): string =>
+  'group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background';
+
+export const avatarGroupCountClass = (): string =>
+  'relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3';

package/packages/registry/components/badge.ts

@@ -0,0 +1,40 @@
+/**
+ * Badge: small visual label. Tier-1 class helper; compose with any
+ * inline element (commonly `<span>` or `<a>` for linked badges).
+ *
+ * shadcn parity:
+ *   Badge (variant: default | secondary | destructive | outline | ghost | link)
+ *                                  → badgeClass({ variant })
+ *
+ * Usage:
+ *   <span class=${badgeClass()}>New</span>
+ *   <span class=${badgeClass({ variant: 'destructive' })}>Error</span>
+ *   <a    class=${badgeClass({ variant: 'link' })} href="/profile">@vivek</a>
+ *
+ * The `[a&]:hover:...` hover styles only apply when the element is an `<a>`,
+ * so a static `<span>` doesn't pick up an unwanted hover.
+ *
+ * Design tokens used: --primary, --secondary, --destructive, --foreground,
+ * --accent, --border, --ring.
+ */
+import { cn } from '../lib/utils.ts';
+
+const BASE =
+  'inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-full border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-[color,box-shadow] 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 [&>svg]:pointer-events-none [&>svg]:size-3';
+
+const VARIANTS = {
+  default: 'bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+  secondary: 'bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+  destructive:
+    'bg-destructive text-white focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40 [a&]:hover:bg-destructive/90',
+  outline:
+    'border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+  ghost: '[a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+  link: 'text-primary underline-offset-4 [a&]:hover:underline',
+} as const;
+
+export type BadgeVariant = keyof typeof VARIANTS;
+
+export function badgeClass(opts: { variant?: BadgeVariant } = {}): string {
+  return cn(BASE, VARIANTS[opts.variant ?? 'default']);
+}