@webjsdev/ui 0.3.16 → 0.3.17

package/README.md

@@ -8,7 +8,8 @@ function calls, not for a layered React abstraction over every primitive:
 
 - **Tier 1, class-helper functions** (`buttonClass`, `cardClass`,
   `inputClass`, `labelClass`, `alertClass`, `popoverContentClass`,
-  `accordionItemClass`, `collapsibleTriggerClass`, …). Pure functions that
+  `accordionItemClass`, `collapsibleTriggerClass`, `emptyClass`,
+  `fieldClass`, `fieldErrorClass`, `spinnerClass`, …). Pure functions that
   return Tailwind class strings. You spread them onto raw native elements
  , including `<button class=${buttonClass({ variant: 'outline' })}>`,
   `<details name="faq" class=${accordionItemClass()}>`, and
@@ -55,8 +56,9 @@ Tier-1 class helpers return only classes, so the semantic element and ARIA are
 yours to supply. Each one's JSDoc carries an `A11y (required for accessible
 output)` block stating exactly what to add: a name on an icon-only button, a
 role on an alert, `scope` on table headers, `alt` on an avatar image, a
-labelled `<nav>` with `aria-current="page"` on pagination and breadcrumb, and
-so on. Follow that block and the markup is fully accessible.
+labelled `<nav>` with `aria-current="page"` on pagination and breadcrumb,
+`aria-describedby` from a control to its field description and error, a
+disabled `aria-busy` button around a decorative spinner, and so on. Follow that block and the markup is fully accessible.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "type": "module",
   "description": "The AI-first component library for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Class-helper functions for visuals, custom elements only where state matters, source-copied into your repo so you own it.",
   "bin": {

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 =
+  'mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0';
+
+const MEDIA_VARIANTS = {
+  default: 'bg-transparent',
+  icon: "flex size-10 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground [&_svg:not([class*='size-'])]:size-6",
+} 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 =>
+  'flex min-w-0 flex-1 flex-col items-center justify-center gap-6 rounded-lg border-dashed p-6 text-center text-balance md:p-12';
+
+/** Empty header: groups the media, title, and description. */
+export const emptyHeaderClass = (): string =>
+  'flex max-w-sm flex-col items-center gap-2 text-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 => 'text-lg font-medium tracking-tight';
+
+/** Empty description: the muted line under the title, saying what to do next. */
+export const emptyDescriptionClass = (): string =>
+  'text-sm/relaxed 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 =>
+  'flex w-full max-w-sm min-w-0 flex-col items-center gap-4 text-sm text-balance';

package/packages/registry/components/field.ts

@@ -0,0 +1,163 @@
+/**
+ * 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: 'text-base',
+  label: 'text-sm',
+} as const;
+
+const ORIENTATIONS = {
+  vertical: 'flex-col [&>*]:w-full [&>.sr-only]:w-auto',
+  horizontal:
+    'flex-row items-center [&>[data-slot=field-label]]:flex-auto has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[type=checkbox],[type=radio]]:mt-px',
+  responsive:
+    'flex-col @md/field-group:flex-row @md/field-group:items-center [&>*]:w-full @md/field-group:[&>*]:w-auto [&>.sr-only]:w-auto @md/field-group:[&>[data-slot=field-label]]:flex-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[type=checkbox],[type=radio]]:mt-px',
+} as const;
+
+/** Field set: a native `<fieldset>` holding a legend and a group of fields. */
+export const fieldSetClass = (): string =>
+  'flex flex-col gap-6 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3';
+
+/**
+ * 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 'mb-3 font-medium ' + LEGEND_VARIANTS[opts.variant ?? 'legend'];
+}
+
+/** Field group: stacks fields, and is the container `responsive` fields measure. */
+export const fieldGroupClass = (): string =>
+  'group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4';
+
+/**
+ * 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 (
+    'group/field flex w-full gap-3 data-[invalid=true]:text-destructive ' +
+    ORIENTATIONS[opts.orientation ?? 'vertical']
+  );
+}
+
+/** Field content: wraps a label and description beside a horizontal control. */
+export const fieldContentClass = (): string =>
+  'group/field-content flex flex-1 flex-col gap-1.5 leading-snug';
+
+/** Field label: the `<label for>` of the control. Fades when the field is data-disabled. */
+export const fieldLabelClass = (): string =>
+  'group/field-label peer/field-label flex w-fit items-center gap-2 text-sm leading-snug font-medium select-none group-data-[disabled=true]/field:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50 has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border [&>*]:data-[slot=field]:p-4 has-checked:border-primary has-checked:bg-primary/5 dark:has-checked:bg-primary/10';
+
+/** Field title: label-styled text that is not a `<label>` (a choice card's heading). */
+export const fieldTitleClass = (): string =>
+  'flex w-fit items-center gap-2 text-sm leading-snug font-medium group-data-[disabled=true]/field:opacity-50';
+
+/** Field description: the muted helper text under (or beside) the control. */
+export const fieldDescriptionClass = (): string =>
+  'text-sm leading-normal font-normal text-muted-foreground group-has-[[data-orientation=horizontal]]/field:text-balance last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5 [&>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 => 'text-sm font-normal text-destructive';
+
+/**
+ * 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 =>
+  'relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2 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 =>
+  'relative mx-auto block w-fit bg-background px-2 text-muted-foreground';

package/packages/registry/components/spinner.ts

@@ -0,0 +1,63 @@
+/**
+ * Spinner: an animated busy indicator. Tier-1 helpers, `spinnerClass()` for
+ * the classes and `spinner()` for the whole inline SVG (the Lucide
+ * loader-circle path, so no icon package is needed). It inherits the text
+ * colour through `currentColor`, so it matches whatever it sits in.
+ *
+ * shadcn parity:
+ *   Spinner  → spinner({ class, label })   (the inline SVG)
+ *            → spinnerClass()              (the classes, for your own SVG)
+ *
+ * Size it with a size utility: `spinner({ class: 'size-6' })` replaces the
+ * default `size-4`.
+ *
+ * Design tokens used: none (it draws in `currentColor`).
+ *
+ * A11y (required for accessible output):
+ *   `spinner()` renders `role="status"` + `aria-label="Loading"`, so a
+ *   standalone spinner is announced. Pass `label` for a more specific name
+ *   (`spinner({ label: 'Loading invoices' })`).
+ *   Inside a BUTTON while a save is running, mark the button itself busy:
+ *   `disabled` (so a second click cannot submit twice) plus `aria-busy="true"`,
+ *   and keep a visible text label ("Saving"). The button's text already says
+ *   what is happening, so pass `decorative: true`, which renders the SVG with
+ *   `aria-hidden="true"` and no role, rather than nesting a second live status
+ *   inside the button's name. Re-enable the button and drop `aria-busy` when
+ *   the save settles, and report the outcome somewhere that is announced (a
+ *   toast, or the form's error text).
+ *   A spinner that replaces a whole region is better as a skeleton when the
+ *   final layout is known, with `aria-busy="true"` on the region.
+ *
+ * @example
+ * ```html
+ * <div class="flex items-center gap-2 text-sm text-muted-foreground">
+ *   ${spinner()} Loading invoices
+ * </div>
+ *
+ * <button class=${buttonClass()} type="submit" disabled aria-busy="true">
+ *   ${spinner({ decorative: true })} Saving
+ * </button>
+ * ```
+ */
+import { html } from '@webjsdev/core';
+import { cn } from '../lib/utils.ts';
+
+/** Spinner classes: `size-4` plus `animate-spin`. Apply to your own `<svg>`. */
+export const spinnerClass = (): string => 'size-4 animate-spin';
+
+/**
+ * The spinner as an inline SVG template. `class` is merged over
+ * `spinnerClass()` (a later size utility wins), `label` names it (default
+ * "Loading"), and `decorative` hides it from assistive tech for use beside
+ * visible text such as a busy button's label.
+ */
+export function spinner(opts: { class?: string; label?: string; decorative?: boolean } = {}) {
+  const cls = cn(spinnerClass(), opts.class);
+  // Branched rather than a nullish `role=${...}` hole: the server renderer
+  // stringifies a null attribute value, so a single template would serve
+  // `role=""` on the decorative form.
+  if (opts.decorative) {
+    return html`<svg data-slot="spinner" 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" class=${cls}><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>`;
+  }
+  return html`<svg data-slot="spinner" role="status" aria-label=${opts.label ?? 'Loading'} 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" class=${cls}><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>`;
+}

package/packages/registry/registry.json

@@ -232,6 +232,38 @@
         }
       ]
     },
+    {
+      "name": "empty",
+      "type": "registry:ui",
+      "registryDependencies": [
+        "lib-utils"
+      ],
+      "dependencies": [
+        "@webjsdev/core"
+      ],
+      "files": [
+        {
+          "path": "components/empty.ts",
+          "type": "registry:ui"
+        }
+      ]
+    },
+    {
+      "name": "field",
+      "type": "registry:ui",
+      "registryDependencies": [
+        "lib-utils"
+      ],
+      "dependencies": [
+        "@webjsdev/core"
+      ],
+      "files": [
+        {
+          "path": "components/field.ts",
+          "type": "registry:ui"
+        }
+      ]
+    },
     {
       "name": "hover-card",
       "type": "registry:ui",
@@ -410,6 +442,22 @@
         }
       ]
     },
+    {
+      "name": "spinner",
+      "type": "registry:ui",
+      "registryDependencies": [
+        "lib-utils"
+      ],
+      "dependencies": [
+        "@webjsdev/core"
+      ],
+      "files": [
+        {
+          "path": "components/spinner.ts",
+          "type": "registry:ui"
+        }
+      ]
+    },
     {
       "name": "switch",
       "type": "registry:ui",