velvetkit 0.1.0.beta

data/registry/app/javascript/controllers/ui/_internal/use_floating.ts

@@ -0,0 +1,112 @@
+// frozen_string_literal: true
+
+import {
+  computePosition,
+  autoUpdate,
+  offset,
+  flip,
+  shift,
+  arrow,
+  type Placement,
+  type Middleware,
+} from '@floating-ui/dom';
+
+interface UseFloatingOptions {
+  placement?: Placement;
+  offset?: number;
+  flip?: boolean;
+  shift?: boolean;
+  arrow?: HTMLElement | null;
+  /** 'fixed' escapes scrolling or clipped ancestors, such as a drawer. */
+  strategy?: 'absolute' | 'fixed';
+}
+
+interface UseFloatingReturn {
+  update: () => void;
+  destroy: () => void;
+}
+
+const STATIC_SIDES: Record<string, string> = {
+  top: 'bottom',
+  right: 'left',
+  bottom: 'top',
+  left: 'right',
+};
+
+/**
+ * Floating UI wrapper for positioning floating elements relative to a reference.
+ * Used by Tooltip, Popover, and Dropdown components.
+ */
+export function useFloating(
+  reference: HTMLElement,
+  floating: HTMLElement,
+  options: UseFloatingOptions = {}
+): UseFloatingReturn {
+  const {
+    placement = 'top',
+    offset: offsetValue = 8,
+    flip: enableFlip = true,
+    shift: enableShift = true,
+    arrow: arrowElement,
+    strategy = 'absolute',
+  } = options;
+
+  const middleware: Middleware[] = [];
+
+  if (offsetValue) {
+    middleware.push(offset(offsetValue));
+  }
+
+  if (enableFlip) {
+    middleware.push(flip());
+  }
+
+  if (enableShift) {
+    middleware.push(shift({ padding: 8 }));
+  }
+
+  if (arrowElement) {
+    middleware.push(arrow({ element: arrowElement }));
+  }
+
+  const cleanup = autoUpdate(reference, floating, () => {
+    computePosition(reference, floating, {
+      placement,
+      strategy,
+      middleware,
+    }).then(({ x, y, placement: finalPlacement, middlewareData }) => {
+      Object.assign(floating.style, {
+        left: `${x}px`,
+        top: `${y}px`,
+        position: strategy,
+      });
+
+      // Position arrow if present
+      if (arrowElement && middlewareData.arrow) {
+        const { x: arrowX, y: arrowY } = middlewareData.arrow;
+        const basePlacement = finalPlacement.split('-')[0];
+        const staticSide = basePlacement ? STATIC_SIDES[basePlacement] : undefined;
+
+        if (staticSide) {
+          // Clear the side a flip left behind, and tell the arrow which way
+          // it now points so its borders follow.
+          Object.assign(arrowElement.style, {
+            left: arrowX != null ? `${arrowX}px` : '',
+            top: arrowY != null ? `${arrowY}px` : '',
+            right: '',
+            bottom: '',
+            [staticSide]: '-4px',
+          });
+          arrowElement.dataset.side = basePlacement;
+        }
+      }
+    });
+  });
+
+  return {
+    update: () => {},
+    destroy: cleanup,
+  };
+}
+
+export type { Placement };

data/registry/app/javascript/controllers/ui/accordion_controller.ts

@@ -0,0 +1,100 @@
+import { Controller } from '@hotwired/stimulus';
+
+export default class extends Controller<HTMLElement> {
+  static targets = ['item', 'trigger', 'content'];
+  static values = {
+    type: { type: String, default: 'single' },
+    values: { type: Array, default: [] },
+  };
+
+  declare readonly itemTargets: HTMLElement[];
+  declare readonly triggerTargets: HTMLButtonElement[];
+  declare readonly contentTargets: HTMLElement[];
+  declare typeValue: string;
+  declare valuesValue: string[];
+
+  connect() {
+    this.sync();
+  }
+
+  toggle(event: Event) {
+    const trigger = event.currentTarget as HTMLButtonElement;
+    const item = trigger.closest("[data-ui--accordion-target='item']") as HTMLElement;
+    if (!item) return;
+    const value = item.dataset.value!;
+    const open = !this.valuesValue.includes(value);
+
+    if (this.typeValue === 'single') {
+      if (open) {
+        this.valuesValue = [value];
+      } else {
+        this.valuesValue = [];
+      }
+    } else {
+      if (open) {
+        this.valuesValue = [...this.valuesValue, value];
+      } else {
+        this.valuesValue = this.valuesValue.filter((v) => v !== value);
+      }
+    }
+
+    this.sync();
+  }
+
+  keydown(event: KeyboardEvent) {
+    const enabled = this.triggerTargets.filter((t) => !t.disabled);
+    if (enabled.length === 0) return;
+    const currentIndex = enabled.indexOf(event.currentTarget as HTMLButtonElement);
+    let next = -1;
+
+    switch (event.key) {
+      case 'ArrowDown':
+        next = (currentIndex + 1) % enabled.length;
+        break;
+      case 'ArrowUp':
+        next = (currentIndex - 1 + enabled.length) % enabled.length;
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = enabled.length - 1;
+        break;
+      default:
+        return;
+    }
+
+    event.preventDefault();
+    const target = enabled[next];
+    if (!target) return;
+    target.focus();
+  }
+
+  private sync() {
+    this.itemTargets.forEach((item) => {
+      const value = item.dataset.value!;
+      const open = this.valuesValue.includes(value);
+      item.dataset.state = open ? 'open' : 'closed';
+    });
+    this.triggerTargets.forEach((trigger) => {
+      const item = trigger.closest("[data-ui--accordion-target='item']") as HTMLElement;
+      if (!item) return;
+      const value = item.dataset.value!;
+      const open = this.valuesValue.includes(value);
+      trigger.setAttribute('aria-expanded', open ? 'true' : 'false');
+      trigger.dataset.state = open ? 'open' : 'closed';
+    });
+    this.contentTargets.forEach((content) => {
+      const item = content.closest("[data-ui--accordion-target='item']") as HTMLElement;
+      if (!item) return;
+      const value = item.dataset.value!;
+      const open = this.valuesValue.includes(value);
+      content.dataset.state = open ? 'open' : 'closed';
+      if (open) {
+        content.removeAttribute('inert');
+      } else {
+        content.setAttribute('inert', '');
+      }
+    });
+  }
+}

data/registry/app/javascript/controllers/ui/alert_controller.ts

@@ -0,0 +1,7 @@
+import { Controller } from '@hotwired/stimulus';
+
+export default class extends Controller<HTMLElement> {
+  dismiss() {
+    this.element.remove();
+  }
+}

data/registry/app/javascript/controllers/ui/banner_controller.ts

@@ -0,0 +1,7 @@
+import { Controller } from '@hotwired/stimulus';
+
+export default class extends Controller<HTMLElement> {
+  dismiss() {
+    this.element.remove();
+  }
+}

data/registry/app/javascript/controllers/ui/data_grid_controller.ts

@@ -0,0 +1,198 @@
+import { Controller } from '@hotwired/stimulus';
+
+// Connects to data-controller="ui--data-grid"
+//
+// The grid holds one page at a time. Each page — and each sort or filter the
+// user applies — is a request to the server, which does the work in Postgres
+// against the whole table. Filtering in the browser would only ever see the
+// page the browser was sent.
+//
+// AG Grid is ~365 KB gzipped, several times the rest of the application, so it
+// is built as its own entry point (app/javascript/ag_grid.ts) and imported at
+// connect time. A page without a grid never downloads it.
+//
+// The URL is passed in from Ruby rather than written here, because Propshaft
+// serves digested filenames. Importing a variable also stops the bundler
+// resolving it statically and folding AG Grid back into application.js.
+// turbo-rails installs Turbo on window from application.ts. Importing it here
+// instead would bundle a second copy into this entry point, and two Turbo
+// instances means two sets of event listeners on every navigation.
+declare global {
+  interface Window {
+    Turbo?: { visit: (url: string) => void };
+  }
+}
+
+type ColumnSpec = {
+  field: string;
+  headerName: string;
+  width?: number;
+  type?: 'text' | 'number';
+  sortable: boolean;
+  filterable: boolean;
+};
+
+type GridRequest = {
+  startRow: number;
+  endRow: number;
+  sortModel: unknown[];
+  filterModel: Record<string, unknown>;
+  successCallback: (rows: unknown[], lastRow: number) => void;
+  failCallback: () => void;
+};
+
+export default class extends Controller<HTMLElement> {
+  static values = {
+    url: String,
+    columns: Array,
+    pageSize: { type: Number, default: 15 },
+    emptyMessage: { type: String, default: 'Nothing to show' },
+    moduleUrl: String,
+  };
+
+  declare readonly urlValue: string;
+  declare readonly columnsValue: ColumnSpec[];
+  declare readonly pageSizeValue: number;
+  declare readonly emptyMessageValue: string;
+  declare readonly moduleUrlValue: string;
+
+  private grid?: {
+    destroy: () => void;
+    setGridOption: (key: string, value: unknown) => void;
+    paginationGetPageSize: () => number;
+  };
+
+  async connect() {
+    const {
+      createGrid,
+      ModuleRegistry,
+      InfiniteRowModelModule,
+      PaginationModule,
+      TextFilterModule,
+      NumberFilterModule,
+      CustomFilterModule,
+      ColumnAutoSizeModule,
+      themeQuartz,
+    } = await import(this.moduleUrlValue);
+
+    ModuleRegistry.registerModules([
+      InfiniteRowModelModule,
+      PaginationModule,
+      TextFilterModule,
+      NumberFilterModule,
+      CustomFilterModule,
+      ColumnAutoSizeModule,
+    ]);
+
+    // The grid paints its own surface, so it is pointed at the app's design
+    // tokens rather than AG Grid's palette. Because these are the same CSS
+    // variables the rest of the page uses, switching to dark mode re-themes
+    // the grid with no JavaScript involved.
+    const theme = themeQuartz.withParams({
+      backgroundColor: 'var(--card)',
+      foregroundColor: 'var(--card-foreground)',
+      borderColor: 'var(--border)',
+      chromeBackgroundColor: 'var(--muted)',
+      // The header stays neutral; the primary colour shows in the sort and
+      // filter controls and in hover and selection, where it marks what the
+      // user is doing rather than tinting the whole chrome.
+      headerTextColor: 'var(--foreground)',
+      accentColor: 'var(--primary)',
+      rowHoverColor: 'color-mix(in oklab, var(--primary) 7%, transparent)',
+      selectedRowBackgroundColor: 'color-mix(in oklab, var(--primary) 12%, transparent)',
+      oddRowBackgroundColor: 'color-mix(in oklab, var(--muted-foreground) 6%, transparent)',
+      inputBackgroundColor: 'var(--background)',
+      inputBorder: { color: 'var(--input)' },
+      fontFamily: 'inherit',
+      fontSize: '14px',
+      headerFontSize: '14px',
+      headerFontWeight: 500,
+      wrapperBorderRadius: 'var(--radius-lg)',
+      borderRadius: 'var(--radius-sm)',
+      rowHeight: '36px',
+      cellFontFamily: 'inherit',
+      headerHeight: '36px',
+      cellHorizontalPadding: '12px',
+    });
+
+    this.grid = createGrid(this.element, {
+      theme,
+      columnDefs: this.columnsValue.map((column) => ({
+        field: column.field,
+        headerName: column.headerName,
+        width: column.width,
+        flex: column.width ? undefined : 1,
+        sortable: column.sortable,
+        filter: column.filterable
+          ? column.type === 'number'
+            ? 'agNumberColumnFilter'
+            : 'agTextColumnFilter'
+          : false,
+        // Every filter is a round trip, so it waits for a pause in typing
+        // rather than firing per keystroke.
+        filterParams: { debounceMs: 400, buttons: ['reset'] },
+        resizable: true,
+      })),
+      rowModelType: 'infinite',
+      datasource: { getRows: this.fetchRows.bind(this) },
+      // One request per page: the block the grid caches is the page it shows.
+      cacheBlockSize: this.pageSizeValue,
+      pagination: true,
+      paginationPageSize: this.pageSizeValue,
+      paginationPageSizeSelector: [15, 25, 50, 100],
+      // Changing the page size has to change the block size with it, or the
+      // grid asks for pages the server was never told about.
+      onPaginationChanged: () => {
+        const size = this.grid?.paginationGetPageSize();
+        if (size && size !== this.blockSize) {
+          this.blockSize = size;
+          this.grid?.setGridOption('cacheBlockSize', size);
+        }
+      },
+      overlayNoRowsTemplate: `<span class="text-sm text-muted-foreground">${this.emptyMessageValue}</span>`,
+      // A row is clickable when the server sent a path with it, so which
+      // screens open a record is decided in Ruby rather than here.
+      onRowClicked: (event: { data?: { _path?: string }; event?: Event }) => {
+        const path = event.data?._path;
+        if (!path) return;
+
+        // A click on a link or button inside a cell is that control's, not
+        // the row's.
+        const target = event.event?.target as HTMLElement | null;
+        if (target?.closest('a, button, input')) return;
+
+        window.Turbo?.visit(path);
+      },
+    });
+  }
+
+  disconnect() {
+    this.grid?.destroy();
+    this.grid = undefined;
+  }
+
+  private blockSize = 0;
+
+  private async fetchRows(params: GridRequest) {
+    const query = new URLSearchParams({
+      startRow: String(params.startRow),
+      endRow: String(params.endRow),
+      sortModel: JSON.stringify(params.sortModel),
+      filterModel: JSON.stringify(params.filterModel),
+    });
+
+    try {
+      const response = await fetch(`${this.urlValue}?${query}`, {
+        headers: { Accept: 'application/json' },
+      });
+      if (!response.ok) throw new Error(`${response.status}`);
+
+      const { rows, total } = await response.json();
+      // The total is what lets the grid show a page count rather than an
+      // endless scroll.
+      params.successCallback(rows, total);
+    } catch {
+      params.failCallback();
+    }
+  }
+}

data/registry/app/javascript/controllers/ui/date_picker_controller.ts

@@ -0,0 +1,141 @@
+import { Controller } from '@hotwired/stimulus';
+
+// Connects to data-controller="ui--date-picker"
+//
+// A typed field with a calendar beside it, over a hidden ISO input the form
+// actually submits.
+//
+// Typed first, calendar second, because people who know a date type it in a
+// second, and reaching a date years away by clicking back through a calendar
+// takes month after month. The calendar is for dates you pick rather than know.
+//
+// The written order is not decided here. Ruby derives it from
+// date.formats.typed in the locale and passes it in as "DMY" plus a
+// separator, so one locale file governs what the field accepts, what it shows
+// and what the hint says.
+const ISO = /^(\d{4})-(\d{2})-(\d{2})$/;
+// Any of / - . or a space between the parts: people type what is in front of
+// them, and being strict about the separator only creates work.
+const PARTS = /^(\d{1,4})[/\-. ](\d{1,4})[/\-. ](\d{1,4})$/;
+
+export default class extends Controller<HTMLElement> {
+  static targets = ['input', 'hidden', 'calendar', 'panel', 'toggle'];
+  static values = {
+    moduleUrl: String,
+    order: { type: String, default: 'DMY' },
+    separator: { type: String, default: '/' },
+  };
+
+  declare readonly inputTarget: HTMLInputElement;
+  declare readonly hiddenTarget: HTMLInputElement;
+  declare readonly calendarTarget: HTMLElement;
+  declare readonly panelTarget: HTMLElement;
+  declare readonly toggleTarget: HTMLButtonElement;
+  declare readonly moduleUrlValue: string;
+  declare readonly orderValue: string;
+  declare readonly separatorValue: string;
+
+  private loaded = false;
+
+  connect() {
+    // The typed field is the source of truth on load, so a value already on
+    // the record shows in the locale's written format.
+    this.inputTarget.value = this.toTyped(this.hiddenTarget.value);
+  }
+
+  // Parsed on every keystroke rather than on blur, so a half-typed date simply
+  // clears the hidden field instead of submitting yesterday's value.
+  typed() {
+    const iso = this.toIso(this.inputTarget.value);
+    this.hiddenTarget.value = iso ?? '';
+    this.inputTarget.setAttribute('aria-invalid', this.invalid() ? 'true' : 'false');
+    if (iso && this.loaded) this.calendarTarget.setAttribute('value', iso);
+  }
+
+  async toggle(event: Event) {
+    event.preventDefault();
+    if (!this.panelTarget.hidden) return this.close();
+
+    await this.load();
+    this.panelTarget.hidden = false;
+    this.toggleTarget.setAttribute('aria-expanded', 'true');
+    (this.calendarTarget as HTMLElement & { focus?: () => void }).focus?.();
+  }
+
+  // Cally fires `change` with the chosen date on its own value attribute.
+  picked() {
+    const iso = (this.calendarTarget as HTMLElement & { value?: string }).value;
+    if (!iso) return;
+
+    this.hiddenTarget.value = iso;
+    this.inputTarget.value = this.toTyped(iso);
+    this.inputTarget.setAttribute('aria-invalid', 'false');
+    this.close();
+    this.inputTarget.focus();
+  }
+
+  close() {
+    this.panelTarget.hidden = true;
+    this.toggleTarget.setAttribute('aria-expanded', 'false');
+  }
+
+  // Clicking away and Escape both close it, which is what every other menu in
+  // the app does.
+  closeOnOutsideClick(event: Event) {
+    if (this.panelTarget.hidden) return;
+    if (this.element.contains(event.target as Node)) return;
+
+    this.close();
+  }
+
+  closeOnEscape(event: KeyboardEvent) {
+    if (event.key === 'Escape' && !this.panelTarget.hidden) {
+      this.close();
+      this.toggleTarget.focus();
+    }
+  }
+
+  private async load() {
+    if (this.loaded) return;
+
+    await import(this.moduleUrlValue);
+    this.loaded = true;
+    if (this.hiddenTarget.value) this.calendarTarget.setAttribute('value', this.hiddenTarget.value);
+  }
+
+  private invalid() {
+    const typed = this.inputTarget.value.trim();
+    return typed !== '' && this.toIso(typed) === null;
+  }
+
+  // The locale's order in, ISO out. Rejects 31/02 rather than rolling it into
+  // the 3rd of March, which is what Date does and how a wrong birth date gets
+  // stored without anyone seeing an error.
+  private toIso(typed: string): string | null {
+    const match = PARTS.exec(typed.trim());
+    if (!match) return null;
+
+    const order = this.orderValue.split('');
+    const day = match[order.indexOf('D') + 1];
+    const month = match[order.indexOf('M') + 1];
+    const year = match[order.indexOf('Y') + 1];
+    if (!day || !month || !year || year.length !== 4) return null;
+
+    const iso = `${year}-${month.padStart(2, '0')}-${day.padStart(2, '0')}`;
+    const date = new Date(`${iso}T00:00:00`);
+    if (Number.isNaN(date.getTime())) return null;
+
+    // Round-tripped, because Date accepts the 31st of February and quietly
+    // returns the 3rd of March.
+    return date.getDate() === Number(day) && date.getMonth() + 1 === Number(month) ? iso : null;
+  }
+
+  private toTyped(iso: string): string {
+    const match = ISO.exec((iso ?? '').trim());
+    if (!match) return '';
+
+    const [, year, month, day] = match;
+    const parts: Record<string, string> = { D: day, M: month, Y: year };
+    return this.orderValue.split('').map((key) => parts[key]).join(this.separatorValue);
+  }
+}

data/registry/app/javascript/controllers/ui/dialog_controller.ts

@@ -0,0 +1,70 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * UI::Dialog controller — opens and closes a native <dialog> via showModal().
+ *
+ * What we DO:
+ *   - open()  : trigger.click → dialog.showModal() → set data-state=open
+ *   - close() : close-button.click or backdrop click → dialog.close()
+ *
+ * What we DELEGATE TO THE PLATFORM:
+ *   - modal mode, inert background, return focus, focus trap, ESC dismissal —
+ *     all handled by <dialog>.showModal() natively.
+ */
+export default class extends Controller<HTMLElement> {
+  static targets = ['trigger', 'content'];
+
+  declare readonly hasTriggerTarget: boolean;
+  declare readonly triggerTarget: HTMLElement;
+  declare readonly contentTarget: HTMLDialogElement;
+
+  connect() {
+    this.contentTarget.addEventListener('close', this.handleClose);
+    this.contentTarget.addEventListener('cancel', this.handleCancel);
+    this.contentTarget.addEventListener('click', this.handleBackdropClick);
+  }
+
+  disconnect() {
+    this.contentTarget.removeEventListener('close', this.handleClose);
+    this.contentTarget.removeEventListener('cancel', this.handleCancel);
+    this.contentTarget.removeEventListener('click', this.handleBackdropClick);
+    if (this.contentTarget.open) this.contentTarget.close();
+  }
+
+  open(event?: Event) {
+    event?.preventDefault();
+    if (this.contentTarget.open) return;
+    this.contentTarget.showModal();
+    this.setState('open');
+  }
+
+  close(event?: Event) {
+    event?.preventDefault();
+    if (this.contentTarget.open) this.contentTarget.close();
+  }
+
+  // Native `cancel` fires on ESC. Let the default close happen, just sync
+  // state via the close listener.
+  private handleCancel = (_event: Event) => {
+    /* noop — close listener handles state */
+  };
+
+  private handleClose = () => {
+    this.setState('closed');
+  };
+
+  // Click outside the panel = click on the dialog element itself (because the
+  // panel is a child of the dialog). Close in that case.
+  private handleBackdropClick = (event: MouseEvent) => {
+    if (event.target === this.contentTarget) this.close();
+  };
+
+  private setState(state: 'open' | 'closed') {
+    this.contentTarget.dataset.state = state;
+    const panel = this.contentTarget.querySelector<HTMLElement>('[data-ui--dialog-part="panel"]');
+    if (panel) panel.dataset.state = state;
+    if (this.hasTriggerTarget) {
+      this.triggerTarget.setAttribute('aria-expanded', state === 'open' ? 'true' : 'false');
+    }
+  }
+}