@cahyo-dimas/freeday 1.7.1 → 1.9.0

package/adapters/react/components/FdyTable.tsx

@@ -0,0 +1,263 @@
+import type { CSSProperties, JSX, ReactNode } from 'react';
+import { useEffect, useMemo, useState } from 'react';
+import {
+  cellValue,
+  cellText,
+  distinctValues,
+  filterRows,
+  sortRows,
+  paginate,
+  pageWindow,
+} from '../../core/table-model.js';
+import type {
+  FdyTableColumn,
+  FdySortState,
+  FdyColumnFilter,
+  FdyFilterMap,
+  FdyPageState,
+} from '../../core/table-model.js';
+import { FdyTableFilter } from './FdyTableFilter';
+
+// A controlled React data table over freeday's `.fdy-datatable` / `.fdy-table*` / `.fdy-filter*` /
+// `.fdy-pagination__*` classes. React port of adapters/vue/components/FdyTable.vue. Unlike the
+// freeday-table.js enhancer (which snapshots static rows and fights React's reconciler), this reads
+// `rows` as the source of truth on every render. Two modes:
+//   • Client mode (no `page` prop): the component sorts/filters (and paginates when `pageSize` is
+//     set) over the full `rows`. `sort`/`filters` are controlled when provided, else internal.
+//   • Server mode (`page` prop present): `rows` render exactly as given (server already
+//     sorted/filtered/paged); the headers, filters and pager only signal intent via
+//     `onSortChange` / `onFiltersChange` / `onPageChange` for the caller to feed back into its query.
+// Column filters (text/enum/number/date) apply live; in server mode, debounce the callback if needed.
+
+export interface FdyTableProps<Row extends object> {
+  columns: ReadonlyArray<FdyTableColumn<Row>>;
+  rows: ReadonlyArray<Row>;
+  rowKey: (row: Row) => string | number;
+  /** Controlled sort. Provide (even as null) to own sorting; omit for internal client sort. */
+  sort?: FdySortState | null;
+  onSortChange?: (sort: FdySortState | null) => void;
+  /** Controlled filter map keyed by column key. Provide to own filtering; omit for internal. */
+  filters?: FdyFilterMap;
+  onFiltersChange?: (filters: FdyFilterMap) => void;
+  /** Server pagination state (0-based index). Presence switches the table into server mode. */
+  page?: FdyPageState;
+  onPageChange?: (page: FdyPageState) => void;
+  /** Client-side page size when `page` is absent; 0/undefined = render all rows (no pager). */
+  pageSize?: number;
+  loading?: boolean;
+  emptyText?: string;
+  ariaLabel?: string;
+  /** Custom cell renderer; return undefined for a column to use the default text. */
+  renderCell?: (column: FdyTableColumn<Row>, row: Row, value: unknown) => ReactNode;
+  toolbar?: ReactNode;
+  empty?: ReactNode;
+  /** Opt in to row activation: rows become focusable and call `onRowActivate` on click/Enter/Space. */
+  rowActivatable?: boolean;
+  /** Per-row class hook, e.g. to mark a selected row. */
+  rowClass?: (row: Row) => string | undefined;
+  /** A row was activated (click, or Enter/Space while the row itself is focused). */
+  onRowActivate?: (row: Row) => void;
+}
+
+export function FdyTable<Row extends object>(props: FdyTableProps<Row>): JSX.Element {
+  const serverPaged: boolean = props.page != null;
+  const sortControlled: boolean = serverPaged || props.sort !== undefined;
+  const filtersControlled: boolean = serverPaged || props.filters !== undefined;
+
+  const [internalSort, setInternalSort] = useState<FdySortState | null>(null);
+  const [internalFilters, setInternalFilters] = useState<FdyFilterMap>({});
+  const [internalPageIndex, setInternalPageIndex] = useState<number>(0);
+
+  const effectiveSort: FdySortState | null = sortControlled ? (props.sort ?? null) : internalSort;
+  const effectiveFilters: FdyFilterMap = filtersControlled ? (props.filters ?? {}) : internalFilters;
+
+  // Enum options: explicit (server mode) or distinct values across the current rows (client mode).
+  const enumOptionsMap: Record<string, ReadonlyArray<string>> = useMemo(() => {
+    const out: Record<string, ReadonlyArray<string>> = {};
+    for (const col of props.columns) {
+      if (col.filter === 'enum') out[col.key] = col.options ?? distinctValues(props.rows, col);
+    }
+    return out;
+  }, [props.columns, props.rows]);
+
+  const filteredSorted: Row[] = useMemo(() => {
+    if (serverPaged) return props.rows.slice();
+    return sortRows(filterRows(props.rows, props.columns, effectiveFilters), props.columns, effectiveSort);
+  }, [serverPaged, props.rows, props.columns, effectiveFilters, effectiveSort]);
+
+  const totalCount: number = serverPaged ? (props.page as FdyPageState).total : filteredSorted.length;
+
+  const displayRows: Row[] = useMemo(() => {
+    if (serverPaged) return props.rows.slice();
+    if (props.pageSize && props.pageSize > 0) return paginate(filteredSorted, internalPageIndex, props.pageSize);
+    return filteredSorted;
+  }, [serverPaged, props.rows, props.pageSize, filteredSorted, internalPageIndex]);
+
+  const pageSizeEff: number = serverPaged ? (props.page as FdyPageState).size : (props.pageSize ?? 0);
+  const currentPage1: number = (serverPaged ? (props.page as FdyPageState).index : internalPageIndex) + 1;
+  const totalPages: number = pageSizeEff > 0 ? Math.max(1, Math.ceil(totalCount / pageSizeEff)) : 1;
+  const hasPager: boolean = pageSizeEff > 0 && totalPages > 1;
+  const pages: Array<number | 'ellipsis'> = pageWindow(currentPage1, totalPages);
+  const rangeFrom: number = totalCount === 0 ? 0 : (currentPage1 - 1) * pageSizeEff + 1;
+  const rangeTo: number = totalCount === 0 ? 0 : rangeFrom - 1 + displayRows.length;
+
+  // Client mode: keep the page in range when a filter shrinks the row set.
+  useEffect((): void => {
+    if (!serverPaged && internalPageIndex > totalPages - 1) setInternalPageIndex(Math.max(0, totalPages - 1));
+  }, [serverPaged, internalPageIndex, totalPages]);
+
+  function ariaSortOf(col: FdyTableColumn<Row>): 'ascending' | 'descending' | undefined {
+    if (effectiveSort === null || effectiveSort.key !== col.key) return undefined;
+    return effectiveSort.dir === 'asc' ? 'ascending' : 'descending';
+  }
+  function onSort(col: FdyTableColumn<Row>): void {
+    if (col.sortable !== true) return;
+    const next: FdySortState =
+      effectiveSort !== null && effectiveSort.key === col.key
+        ? { key: col.key, dir: effectiveSort.dir === 'asc' ? 'desc' : 'asc' }
+        : { key: col.key, dir: 'asc' };
+    if (sortControlled) props.onSortChange?.(next);
+    else {
+      setInternalSort(next);
+      setInternalPageIndex(0);
+    }
+  }
+  function onFilterChange(col: FdyTableColumn<Row>, filter: FdyColumnFilter | null): void {
+    const nextMap: FdyFilterMap = { ...effectiveFilters };
+    if (filter === null) delete nextMap[col.key];
+    else nextMap[col.key] = filter;
+    if (filtersControlled) props.onFiltersChange?.(nextMap);
+    else {
+      setInternalFilters(nextMap);
+      setInternalPageIndex(0);
+    }
+  }
+  function goTo(page1: number): void {
+    const clamped: number = Math.min(Math.max(1, page1), totalPages);
+    const index0: number = clamped - 1;
+    if (serverPaged) {
+      const p: FdyPageState = props.page as FdyPageState;
+      props.onPageChange?.({ index: index0, size: p.size, total: p.total });
+    } else {
+      setInternalPageIndex(index0);
+    }
+  }
+
+  function cellClass(col: FdyTableColumn<Row>): string | undefined {
+    return col.mono === true ? 'fdy-mono' : undefined;
+  }
+  function alignStyle(col: FdyTableColumn<Row>): CSSProperties | undefined {
+    return col.align !== undefined ? { textAlign: col.align } : undefined;
+  }
+  function rowClassName(row: Row): string | undefined {
+    const cls: string = [props.rowClass?.(row), props.rowActivatable === true ? 'fdy-table__row--activatable' : undefined]
+      .filter(Boolean)
+      .join(' ');
+    return cls === '' ? undefined : cls;
+  }
+  // Enter/Space activate only when the row itself is focused — a control inside a cell keeps its own
+  // event (the `event.target !== event.currentTarget` guard). Click relies on inner controls calling
+  // stopPropagation, matching the pattern consumers hand-roll today.
+  function onRowKeydown(e: React.KeyboardEvent<HTMLTableRowElement>, row: Row): void {
+    if (props.rowActivatable !== true || e.target !== e.currentTarget) return;
+    if (e.key !== 'Enter' && e.key !== ' ') return;
+    e.preventDefault();
+    props.onRowActivate?.(row);
+  }
+  function renderCellContent(col: FdyTableColumn<Row>, row: Row): ReactNode {
+    if (props.renderCell !== undefined) {
+      const custom: ReactNode = props.renderCell(col, row, cellValue(row, col));
+      if (custom !== undefined) return custom;
+    }
+    return cellText(row, col);
+  }
+
+  const colCount: number = props.columns.length;
+
+  return (
+    <div className="fdy-datatable">
+      {props.toolbar !== undefined && <div className="fdy-table-toolbar">{props.toolbar}</div>}
+
+      <div className="fdy-table-scroll">
+        <table className="fdy-table" aria-label={props.ariaLabel}>
+          <thead>
+            <tr>
+              {props.columns.map((col: FdyTableColumn<Row>): JSX.Element => (
+                <th key={col.key} scope="col" style={alignStyle(col)} aria-sort={ariaSortOf(col)}>
+                  {col.sortable ? (
+                    <button type="button" className="fdy-table__sortbtn" onClick={(): void => onSort(col)}>{col.label}</button>
+                  ) : (
+                    col.label
+                  )}
+                  {col.filter && (
+                    <FdyTableFilter
+                      label={col.label}
+                      type={col.filter}
+                      filter={effectiveFilters[col.key]}
+                      options={enumOptionsMap[col.key] ?? []}
+                      onChange={(f: FdyColumnFilter | null): void => onFilterChange(col, f)}
+                    />
+                  )}
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {props.loading ? (
+              <tr>
+                <td colSpan={colCount} className="fdy-table__state" role="status">Loading…</td>
+              </tr>
+            ) : displayRows.length === 0 ? (
+              <tr>
+                <td colSpan={colCount} className="fdy-table__state">{props.empty ?? props.emptyText ?? 'No data'}</td>
+              </tr>
+            ) : (
+              displayRows.map((row: Row): JSX.Element => (
+                <tr
+                  key={props.rowKey(row)}
+                  className={rowClassName(row)}
+                  tabIndex={props.rowActivatable ? 0 : undefined}
+                  onClick={(): void => {
+                    if (props.rowActivatable === true) props.onRowActivate?.(row);
+                  }}
+                  onKeyDown={(e): void => onRowKeydown(e, row)}
+                >
+                  {props.columns.map((col: FdyTableColumn<Row>): JSX.Element => (
+                    <td key={col.key} className={cellClass(col)} style={alignStyle(col)}>{renderCellContent(col, row)}</td>
+                  ))}
+                </tr>
+              ))
+            )}
+          </tbody>
+        </table>
+      </div>
+
+      {hasPager && (
+        <div className="fdy-table-footer">
+          <span className="fdy-table-footer__info">Showing {rangeFrom}–{rangeTo} of {totalCount}</span>
+          <nav aria-label="Pagination">
+            <ul className="fdy-pagination__list">
+              <li>
+                <button type="button" className="fdy-pagination__link" aria-label="Previous page" disabled={currentPage1 === 1} onClick={(): void => goTo(currentPage1 - 1)}>‹</button>
+              </li>
+              {pages.map((p: number | 'ellipsis', i: number): JSX.Element => (
+                <li key={typeof p === 'number' ? `p-${p}` : `gap-${i}`}>
+                  {p === 'ellipsis' ? (
+                    <span className="fdy-pagination__ellipsis">…</span>
+                  ) : p === currentPage1 ? (
+                    <span className="fdy-pagination__link" aria-current="page">{p}</span>
+                  ) : (
+                    <button type="button" className="fdy-pagination__link" aria-label={`Go to page ${p}`} onClick={(): void => goTo(p)}>{p}</button>
+                  )}
+                </li>
+              ))}
+              <li>
+                <button type="button" className="fdy-pagination__link" aria-label="Next page" disabled={currentPage1 === totalPages} onClick={(): void => goTo(currentPage1 + 1)}>›</button>
+              </li>
+            </ul>
+          </nav>
+        </div>
+      )}
+    </div>
+  );
+}

package/adapters/react/components/FdyTableFilter.tsx

@@ -0,0 +1,193 @@
+import type { JSX } from 'react';
+import { useEffect, useRef, useState } from 'react';
+import { usePopover } from '../usePopover';
+import { isFilterActive } from '../../core/table-model.js';
+import type { FdyColumnFilter, FdyColumnFilterType } from '../../core/table-model.js';
+
+// Internal to FdyTable: one column's header funnel button + its type-aware filter popover
+// (text / enum / number / date) over freeday's `.fdy-table__filterbtn` + `.fdy-filter*` classes.
+// React port of adapters/vue/components/FdyTableFilter.vue. Reuses usePopover so the panel escapes
+// the table's `overflow:hidden` via the top layer. Purely controlled — renders the current
+// `filter`, emits the next one (or null to clear); the parent owns where it goes. Not exported.
+
+export interface FdyTableFilterProps {
+  label: string;
+  type: FdyColumnFilterType;
+  filter: FdyColumnFilter | undefined;
+  /** Distinct values for an enum filter (computed by the parent over the full row set). */
+  options: ReadonlyArray<string>;
+  /** The next filter for this column, or null to clear it. */
+  onChange: (filter: FdyColumnFilter | null) => void;
+}
+
+export function FdyTableFilter(props: FdyTableFilterProps): JSX.Element {
+  const rootRef = useRef<HTMLSpanElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [open, setOpen] = useState<boolean>(false);
+
+  usePopover(panelRef, triggerRef, open);
+  // Popover attr for React 18/19 JSX typing: set once on mount (same as the other components).
+  useEffect((): void => {
+    panelRef.current?.setAttribute('popover', 'manual');
+  }, []);
+
+  const active: boolean = isFilterActive(props.filter);
+  const filter: FdyColumnFilter | undefined = props.filter;
+  const textValue: string = filter?.type === 'text' ? filter.text : '';
+  const enumValues: ReadonlyArray<string> = filter?.type === 'enum' ? filter.values : [];
+  const numMin: string = filter?.type === 'number' && filter.min !== null ? String(filter.min) : '';
+  const numMax: string = filter?.type === 'number' && filter.max !== null ? String(filter.max) : '';
+  const dateFrom: string = filter?.type === 'date' && filter.from !== null ? filter.from : '';
+  const dateTo: string = filter?.type === 'date' && filter.to !== null ? filter.to : '';
+
+  function apply(next: FdyColumnFilter): void {
+    props.onChange(isFilterActive(next) ? next : null);
+  }
+  function parseNum(v: string): number | null {
+    const t: string = v.trim();
+    if (t === '') return null;
+    const n: number = Number(t);
+    return Number.isNaN(n) ? null : n;
+  }
+  function onEnumToggle(value: string, checked: boolean): void {
+    const set: string[] = enumValues.filter((v: string): boolean => v !== value);
+    if (checked) set.push(value);
+    apply({ type: 'enum', values: set });
+  }
+  function close(returnFocus: boolean): void {
+    setOpen(false);
+    if (returnFocus) triggerRef.current?.focus();
+  }
+  function reset(): void {
+    props.onChange(null);
+    close(true);
+  }
+
+  // Dismiss on outside pointer or Escape while open.
+  useEffect((): void | (() => void) => {
+    if (!open) return;
+    function onPointerDown(e: MouseEvent): void {
+      const t: EventTarget | null = e.target;
+      if (rootRef.current !== null && t instanceof Node && !rootRef.current.contains(t)) close(false);
+    }
+    function onKeydown(e: KeyboardEvent): void {
+      if (e.key === 'Escape') close(true);
+    }
+    document.addEventListener('mousedown', onPointerDown);
+    document.addEventListener('keydown', onKeydown);
+    return (): void => {
+      document.removeEventListener('mousedown', onPointerDown);
+      document.removeEventListener('keydown', onKeydown);
+    };
+  }, [open]);
+
+  return (
+    <span ref={rootRef} className="fdy-table__filterwrap">
+      <button
+        ref={triggerRef}
+        type="button"
+        className={active ? 'fdy-table__filterbtn is-active' : 'fdy-table__filterbtn'}
+        aria-haspopup="dialog"
+        aria-pressed={active}
+        aria-expanded={open}
+        aria-label={`Filter ${props.label}`}
+        onClick={(e): void => {
+          e.stopPropagation();
+          setOpen((v: boolean): boolean => !v);
+        }}
+      >
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+          <path d="M3 5h18l-7 8v5l-4 2v-7z" />
+        </svg>
+      </button>
+
+      <div ref={panelRef} className="fdy-filter" hidden={!open} role="dialog" aria-label={`Filter ${props.label}`}>
+        {props.type === 'text' && (
+          <>
+            <div className="fdy-filter__title">Contains text</div>
+            <input
+              className="fdy-input"
+              type="search"
+              placeholder="Contains…"
+              value={textValue}
+              onChange={(e): void => apply({ type: 'text', text: e.target.value })}
+            />
+          </>
+        )}
+
+        {props.type === 'enum' && (
+          <>
+            <div className="fdy-filter__title">Show values</div>
+            <div className="fdy-filter__list">
+              {props.options.map((val: string): JSX.Element => (
+                <label key={val} className="fdy-filter__check">
+                  <input
+                    type="checkbox"
+                    className="fdy-checkbox"
+                    checked={enumValues.includes(val)}
+                    onChange={(e): void => onEnumToggle(val, e.target.checked)}
+                  />
+                  {val}
+                </label>
+              ))}
+            </div>
+          </>
+        )}
+
+        {props.type === 'number' && (
+          <>
+            <div className="fdy-filter__title">Value range</div>
+            <div className="fdy-filter__range">
+              <input
+                className="fdy-input"
+                type="text"
+                inputMode="numeric"
+                placeholder="Min"
+                value={numMin}
+                onChange={(e): void => apply({ type: 'number', min: parseNum(e.target.value), max: parseNum(numMax) })}
+              />
+              <span aria-hidden="true">–</span>
+              <input
+                className="fdy-input"
+                type="text"
+                inputMode="numeric"
+                placeholder="Max"
+                value={numMax}
+                onChange={(e): void => apply({ type: 'number', min: parseNum(numMin), max: parseNum(e.target.value) })}
+              />
+            </div>
+          </>
+        )}
+
+        {props.type === 'date' && (
+          <>
+            <div className="fdy-filter__title">Date range</div>
+            <div className="fdy-filter__range">
+              <input
+                className="fdy-input"
+                type="date"
+                aria-label="From"
+                value={dateFrom}
+                onChange={(e): void => apply({ type: 'date', from: e.target.value || null, to: dateTo || null })}
+              />
+              <span aria-hidden="true">–</span>
+              <input
+                className="fdy-input"
+                type="date"
+                aria-label="To"
+                value={dateTo}
+                onChange={(e): void => apply({ type: 'date', from: dateFrom || null, to: e.target.value || null })}
+              />
+            </div>
+          </>
+        )}
+
+        <div className="fdy-filter__foot">
+          <button type="button" className="fdy-btn fdy-btn--ghost fdy-btn--sm" onClick={reset}>Reset</button>
+          <button type="button" className="fdy-btn fdy-btn--sm" onClick={(): void => close(true)}>Close</button>
+        </div>
+      </div>
+    </span>
+  );
+}

package/adapters/react/index.d.ts

@@ -35,3 +35,19 @@ export { FdyAutocomplete, type FdyAutocompleteProps } from './components/FdyAuto
 export { FdyCascade, type FdyCascadeProps, type CascadeNode } from './components/FdyCascade';
 export { FdyCfl, type FdyCflProps, type CflColumn, type CflPage } from './components/FdyCfl';
 export { FdyChart, type FdyChartProps, type FdyChartSeries } from './components/FdyChart';
+export { FdyTable, type FdyTableProps } from './components/FdyTable';
+export { FdyModal, type FdyModalProps } from './components/FdyModal';
+export { FdyDrawer, type FdyDrawerProps } from './components/FdyDrawer';
+
+/** Controlled data-table types (shared, framework-agnostic core). */
+export type {
+  FdyTableColumn,
+  FdySortState,
+  FdySortDir,
+  FdyColumnType,
+  FdyColumnAlign,
+  FdyColumnFilterType,
+  FdyColumnFilter,
+  FdyFilterMap,
+  FdyPageState,
+} from '../core/table-model';

package/adapters/react/index.js

@@ -7,3 +7,6 @@ export { FdyAutocomplete } from './components/FdyAutocomplete.tsx';
 export { FdyCascade } from './components/FdyCascade.tsx';
 export { FdyCfl } from './components/FdyCfl.tsx';
 export { FdyChart } from './components/FdyChart.tsx';
+export { FdyTable } from './components/FdyTable.tsx';
+export { FdyModal } from './components/FdyModal.tsx';
+export { FdyDrawer } from './components/FdyDrawer.tsx';

package/adapters/vue/components/FdyDrawer.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import { computed, onMounted, useId, watch, type ComputedRef, type Ref, ref } from 'vue';
+
+// A controlled Vue wrapper over freeday's `.fdy-drawer` native <dialog> side panel
+// (src/components/drawer.css). Same controlled contract and glue as FdyModal — showModal()/close()
+// guarded, @cancel.prevent so Esc routes through app state, backdrop-click via `event.target ===
+// dialogEl` — applied to a drawer that anchors left (default) or right. Native <dialog> supplies the
+// focus trap, focus restore, top-layer stacking and inert background; `dismissible` (default true)
+// gates Esc + backdrop dismissal.
+
+const props = defineProps<{
+  open: boolean;
+  title: string;
+  side?: 'left' | 'right';
+  dismissible?: boolean;
+}>();
+
+const emit = defineEmits<{
+  close: [];
+}>();
+
+const dialogEl: Ref<HTMLDialogElement | null> = ref(null);
+const titleId: string = `${useId()}-title`;
+const dismissible: ComputedRef<boolean> = computed((): boolean => props.dismissible !== false);
+const drawerClass: ComputedRef<string> = computed((): string =>
+  props.side === 'right' ? 'fdy-drawer fdy-drawer--right' : 'fdy-drawer',
+);
+
+function sync(open: boolean): void {
+  const el: HTMLDialogElement | null = dialogEl.value;
+  if (el === null) return;
+  if (open && !el.open) el.showModal();
+  else if (!open && el.open) el.close();
+}
+watch((): boolean => props.open, sync, { flush: 'post' });
+onMounted((): void => sync(props.open));
+
+function onCancel(): void {
+  if (dismissible.value) emit('close');
+}
+function onClick(e: MouseEvent): void {
+  if (dismissible.value && e.target === dialogEl.value) emit('close');
+}
+</script>
+
+<template>
+  <dialog
+    ref="dialogEl"
+    :class="drawerClass"
+    :aria-labelledby="titleId"
+    @cancel.prevent="onCancel"
+    @click="onClick"
+  >
+    <div class="fdy-drawer__header">
+      <h3 :id="titleId" class="fdy-drawer__title">
+        <slot name="title">{{ title }}</slot>
+      </h3>
+      <button v-if="dismissible" class="fdy-drawer__close" type="button" aria-label="Close" @click="$emit('close')">&times;</button>
+    </div>
+
+    <div class="fdy-drawer__body">
+      <slot />
+    </div>
+
+    <div v-if="$slots.footer" class="fdy-drawer__footer">
+      <slot name="footer" />
+    </div>
+  </dialog>
+</template>

package/adapters/vue/components/FdyModal.vue

@@ -0,0 +1,76 @@
+<script setup lang="ts">
+import { computed, onMounted, useId, watch, type ComputedRef, type Ref, ref } from 'vue';
+
+// A controlled Vue wrapper over freeday's `.fdy-modal` native <dialog> (src/components/modal.css).
+// The kit styles the dialog but nothing drives it; every consumer re-derives the same imperative
+// glue to reconcile a reactive `open` boolean with a DOM element whose open/close is a method call.
+// This writes that glue once: showModal()/close() guarded against the already-open/closed cases
+// (showModal() on an open dialog throws), @cancel.prevent so Esc routes through app state instead of
+// closing the DOM behind its back, and backdrop-click detection via `event.target === dialogEl`.
+// Native <dialog> already provides the focus trap, focus restore, top-layer stacking and inert
+// background — the wrapper only avoids breaking them. `dismissible` (default true) gates Esc + backdrop.
+
+const props = defineProps<{
+  open: boolean;
+  title: string;
+  size?: 'sm' | 'md' | 'lg' | 'wide';
+  dismissible?: boolean;
+}>();
+
+const emit = defineEmits<{
+  close: [];
+}>();
+
+const dialogEl: Ref<HTMLDialogElement | null> = ref(null);
+const titleId: string = `${useId()}-title`;
+const dismissible: ComputedRef<boolean> = computed((): boolean => props.dismissible !== false);
+const modalClass: ComputedRef<string> = computed((): string =>
+  props.size !== undefined ? `fdy-modal fdy-modal--${props.size}` : 'fdy-modal',
+);
+
+// Reconcile the reactive `open` with the dialog's method-driven state. Both guards matter:
+// showModal() on an already-open dialog throws; close() on a closed one is a no-op but kept symmetric.
+function sync(open: boolean): void {
+  const el: HTMLDialogElement | null = dialogEl.value;
+  if (el === null) return;
+  if (open && !el.open) el.showModal();
+  else if (!open && el.open) el.close();
+}
+watch((): boolean => props.open, sync, { flush: 'post' });
+onMounted((): void => sync(props.open));
+
+// Esc fires `cancel`; .prevent stops the native close so app state stays the single source of truth.
+function onCancel(): void {
+  if (dismissible.value) emit('close');
+}
+// The ::backdrop is not a separate element — a click whose target is the dialog box itself (not its
+// content) is a backdrop click.
+function onClick(e: MouseEvent): void {
+  if (dismissible.value && e.target === dialogEl.value) emit('close');
+}
+</script>
+
+<template>
+  <dialog
+    ref="dialogEl"
+    :class="modalClass"
+    :aria-labelledby="titleId"
+    @cancel.prevent="onCancel"
+    @click="onClick"
+  >
+    <div class="fdy-modal__header">
+      <h3 :id="titleId" class="fdy-modal__title">
+        <slot name="title">{{ title }}</slot>
+      </h3>
+      <button v-if="dismissible" class="fdy-modal__close" type="button" aria-label="Close" @click="$emit('close')">&times;</button>
+    </div>
+
+    <div class="fdy-modal__body">
+      <slot />
+    </div>
+
+    <div v-if="$slots.footer" class="fdy-modal__footer">
+      <slot name="footer" />
+    </div>
+  </dialog>
+</template>