@ecoma-io/loom 0.3.0 → 0.5.0

package/dist/packages/primitives/copy-button/src/CopyButton.vue.d.ts

@@ -0,0 +1,64 @@
+import { type LabelOverrides } from "../../../labels/src/index";
+import type { CopyButtonLabels } from "../../../labels/src/index";
+import type { IconButtonSize, IconButtonVariant } from "../../icon-button/src/index";
+/**
+ * The visual weights and hit areas are IconButton's, verbatim — a copy button
+ * is an icon button that happens to own a clipboard contract, and there is no
+ * second press language to maintain.
+ */
+export type CopyButtonVariant = IconButtonVariant;
+export type CopyButtonSize = IconButtonSize;
+export declare const COPY_BUTTON_LABELS: CopyButtonLabels;
+/** How long the copied/failed feedback holds before the button returns to its resting glyph. */
+export declare const COPY_REVERT_MS = 2000;
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import("vue").DefineComponent<{
+    /** The text to copy. Provide `value` or `getText` — a `CopyButton` with neither has nothing to do. */
+    value?: string;
+    /** Resolved at click time instead of a static `value` — for text the host computes on demand, possibly asynchronously. */
+    getText?: () => string | Promise<string>;
+    /**
+     * Names for what the button says, as any subset of `CopyButtonLabels` —
+     * the per-instance correction over `COPY_BUTTON_LABELS`, in the same
+     * shape every component's `labels` prop takes. `copy` is the button's
+     * accessible name and never changes with the state; `copied` and
+     * `failed` are what assistive technology hears.
+     */
+    labels?: LabelOverrides<CopyButtonLabels>;
+    /** Visual weight, shared with IconButton. */
+    variant?: CopyButtonVariant;
+    /** Square hit area, shared with IconButton. */
+    size?: CopyButtonSize;
+    /** Unavailable rather than dimmed — drains to the neutral well and blocks pointer events. */
+    disabled?: boolean;
+    /** The native button type. Defaults to `button`, never an accidental submit. */
+    type?: "button" | "submit" | "reset";
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{
+    /** The text to copy. Provide `value` or `getText` — a `CopyButton` with neither has nothing to do. */
+    value?: string;
+    /** Resolved at click time instead of a static `value` — for text the host computes on demand, possibly asynchronously. */
+    getText?: () => string | Promise<string>;
+    /**
+     * Names for what the button says, as any subset of `CopyButtonLabels` —
+     * the per-instance correction over `COPY_BUTTON_LABELS`, in the same
+     * shape every component's `labels` prop takes. `copy` is the button's
+     * accessible name and never changes with the state; `copied` and
+     * `failed` are what assistive technology hears.
+     */
+    labels?: LabelOverrides<CopyButtonLabels>;
+    /** Visual weight, shared with IconButton. */
+    variant?: CopyButtonVariant;
+    /** Square hit area, shared with IconButton. */
+    size?: CopyButtonSize;
+    /** Unavailable rather than dimmed — drains to the neutral well and blocks pointer events. */
+    disabled?: boolean;
+    /** The native button type. Defaults to `button`, never an accidental submit. */
+    type?: "button" | "submit" | "reset";
+}> & Readonly<{}>, {
+    size: CopyButtonSize;
+    type: "button" | "submit" | "reset";
+    disabled: boolean;
+    variant: CopyButtonVariant;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+//# sourceMappingURL=CopyButton.vue.d.ts.map

package/dist/packages/primitives/copy-button/src/CopyButton.vue_vue_type_script_setup_true_lang.js

@@ -0,0 +1,113 @@
+import { useLabels } from "../../../labels/src/labels.js";
+import "../../../labels/src/index.js";
+import IconButton_default from "../../icon-button/src/IconButton.js";
+import "../../icon-button/src/index.js";
+import { useAnnounce } from "../../live-region/src/useAnnounce.js";
+import "../../live-region/src/index.js";
+import { createBlock, defineComponent, onBeforeUnmount, openBlock, ref, unref, withCtx } from "vue";
+import { Check, Copy, X } from "@lucide/vue";
+//#region packages/primitives/copy-button/src/CopyButton.vue?vue&type=script&setup=true&lang.ts
+var COPY_BUTTON_LABELS = {
+	copy: "Copy to clipboard",
+	copied: "Copied to clipboard",
+	failed: "Could not copy to clipboard"
+};
+/** How long the copied/failed feedback holds before the button returns to its resting glyph. */
+var COPY_REVERT_MS = 2e3;
+var CopyButton_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineComponent({
+	__name: "CopyButton",
+	props: {
+		value: {},
+		getText: {},
+		labels: {},
+		variant: { default: "default" },
+		size: { default: "md" },
+		disabled: {
+			type: Boolean,
+			default: false
+		},
+		type: { default: "button" }
+	},
+	setup(__props) {
+		const props = __props;
+		/**
+		* The outcome is announced through the shared LiveRegion seam, not a
+		* region of this component's own: a region must pre-exist the messages it
+		* announces, and the seam's standalone pair on `document.body` guarantees
+		* that without every copy button mounting its own.
+		*/
+		const announce = useAnnounce();
+		const text = useLabels("copyButton", COPY_BUTTON_LABELS, () => props.labels);
+		/**
+		* idle → copied | failed → idle, on a two-second revert timer. The guard
+		* covers only the await window: a click during the feedback window is a
+		* legitimate "copy again", not a duplicate — the announcement seam re-adds
+		* the message, so a repeat is heard.
+		*/
+		const state = ref("idle");
+		let pending = false;
+		let revertTimer = null;
+		function scheduleRevert() {
+			if (revertTimer !== null) clearTimeout(revertTimer);
+			revertTimer = setTimeout(() => {
+				state.value = "idle";
+				revertTimer = null;
+			}, COPY_REVERT_MS);
+		}
+		onBeforeUnmount(() => {
+			if (revertTimer !== null) clearTimeout(revertTimer);
+			revertTimer = null;
+		});
+		async function copy() {
+			if (props.disabled || pending) return;
+			pending = true;
+			try {
+				const value = props.getText ? await props.getText() : props.value ?? "";
+				await navigator.clipboard.writeText(value);
+				state.value = "copied";
+				announce(text.value.copied);
+			} catch {
+				state.value = "failed";
+				announce(text.value.failed);
+			} finally {
+				pending = false;
+				scheduleRevert();
+			}
+		}
+		return (_ctx, _cache) => {
+			return openBlock(), createBlock(unref(IconButton_default), {
+				label: unref(text).copy,
+				variant: __props.variant,
+				size: __props.size,
+				disabled: __props.disabled,
+				type: __props.type,
+				onClick: copy
+			}, {
+				default: withCtx(() => [state.value === "copied" ? (openBlock(), createBlock(unref(Check), {
+					key: 0,
+					class: "h-4 w-4",
+					"aria-hidden": "true"
+				})) : state.value === "failed" ? (openBlock(), createBlock(unref(X), {
+					key: 1,
+					class: "h-4 w-4",
+					"aria-hidden": "true"
+				})) : (openBlock(), createBlock(unref(Copy), {
+					key: 2,
+					class: "h-4 w-4",
+					"aria-hidden": "true"
+				}))]),
+				_: 1
+			}, 8, [
+				"label",
+				"variant",
+				"size",
+				"disabled",
+				"type"
+			]);
+		};
+	}
+});
+//#endregion
+export { COPY_BUTTON_LABELS, COPY_REVERT_MS, CopyButton_vue_vue_type_script_setup_true_lang_default as default };
+
+//# sourceMappingURL=CopyButton.vue_vue_type_script_setup_true_lang.js.map

package/dist/packages/primitives/copy-button/src/CopyButton.vue_vue_type_script_setup_true_lang.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CopyButton.vue_vue_type_script_setup_true_lang.js","names":[],"sources":["../../../../../packages/primitives/copy-button/src/CopyButton.vue"],"sourcesContent":["<script lang=\"ts\">\nimport type { CopyButtonLabels } from \"@ecoma-io/loom-labels\";\nimport type { IconButtonSize, IconButtonVariant } from \"@ecoma-io/loom-icon-button\";\n\n/**\n * The visual weights and hit areas are IconButton's, verbatim — a copy button\n * is an icon button that happens to own a clipboard contract, and there is no\n * second press language to maintain.\n */\nexport type CopyButtonVariant = IconButtonVariant;\nexport type CopyButtonSize = IconButtonSize;\n\nexport const COPY_BUTTON_LABELS: CopyButtonLabels = {\n  copy: \"Copy to clipboard\",\n  copied: \"Copied to clipboard\",\n  failed: \"Could not copy to clipboard\",\n};\n\n/** How long the copied/failed feedback holds before the button returns to its resting glyph. */\nexport const COPY_REVERT_MS = 2000;\n</script>\n\n<script setup lang=\"ts\">\nimport { onBeforeUnmount, ref } from \"vue\";\nimport { Check, Copy, X } from \"@lucide/vue\";\nimport IconButton from \"@ecoma-io/loom-icon-button\";\nimport { useAnnounce } from \"@ecoma-io/loom-live-region\";\nimport { useLabels, type LabelOverrides } from \"@ecoma-io/loom-labels\";\n\nconst props = withDefaults(\n  defineProps<{\n    /** The text to copy. Provide `value` or `getText` — a `CopyButton` with neither has nothing to do. */\n    value?: string;\n    /** Resolved at click time instead of a static `value` — for text the host computes on demand, possibly asynchronously. */\n    getText?: () => string | Promise<string>;\n    /**\n     * Names for what the button says, as any subset of `CopyButtonLabels` —\n     * the per-instance correction over `COPY_BUTTON_LABELS`, in the same\n     * shape every component's `labels` prop takes. `copy` is the button's\n     * accessible name and never changes with the state; `copied` and\n     * `failed` are what assistive technology hears.\n     */\n    labels?: LabelOverrides<CopyButtonLabels>;\n    /** Visual weight, shared with IconButton. */\n    variant?: CopyButtonVariant;\n    /** Square hit area, shared with IconButton. */\n    size?: CopyButtonSize;\n    /** Unavailable rather than dimmed — drains to the neutral well and blocks pointer events. */\n    disabled?: boolean;\n    /** The native button type. Defaults to `button`, never an accidental submit. */\n    type?: \"button\" | \"submit\" | \"reset\";\n  }>(),\n  { variant: \"default\", size: \"md\", disabled: false, type: \"button\" },\n);\n\n/**\n * The outcome is announced through the shared LiveRegion seam, not a\n * region of this component's own: a region must pre-exist the messages it\n * announces, and the seam's standalone pair on `document.body` guarantees\n * that without every copy button mounting its own.\n */\nconst announce = useAnnounce();\n\n// `text`, not `labels`: the prop of that name is one of the three sources\n// this resolves (own prop, then the host vocabulary from\n// `provideLoomLabels`, then these English defaults), and a template reading\n// the raw prop would be reading the overrides rather than the answer.\nconst text = useLabels(\"copyButton\", COPY_BUTTON_LABELS, () => props.labels);\n\n/**\n * idle → copied | failed → idle, on a two-second revert timer. The guard\n * covers only the await window: a click during the feedback window is a\n * legitimate \"copy again\", not a duplicate — the announcement seam re-adds\n * the message, so a repeat is heard.\n */\ntype CopyState = \"idle\" | \"copied\" | \"failed\";\nconst state = ref<CopyState>(\"idle\");\nlet pending = false;\nlet revertTimer: ReturnType<typeof setTimeout> | null = null;\n\nfunction scheduleRevert(): void {\n  if (revertTimer !== null) clearTimeout(revertTimer);\n  revertTimer = setTimeout(() => {\n    state.value = \"idle\";\n    revertTimer = null;\n  }, COPY_REVERT_MS);\n}\n\nonBeforeUnmount(() => {\n  // The timer holds the only writer into `state`; firing after unmount\n  // would write into a dead component. Cleared, not waited out.\n  if (revertTimer !== null) clearTimeout(revertTimer);\n  revertTimer = null;\n});\n\nasync function copy(): Promise<void> {\n  if (props.disabled || pending) return;\n  pending = true;\n  try {\n    // A throwing `getText` and a refusing clipboard take the same road:\n    // the failed state is announced, the glyph says so, and the button\n    // stays operable so the very next click retries the whole attempt.\n    const value = props.getText ? await props.getText() : (props.value ?? \"\");\n    await navigator.clipboard.writeText(value);\n    state.value = \"copied\";\n    announce(text.value.copied);\n  } catch {\n    state.value = \"failed\";\n    announce(text.value.failed);\n  } finally {\n    pending = false;\n    scheduleRevert();\n  }\n}\n</script>\n\n<template>\n  <IconButton\n    :label=\"text.copy\"\n    :variant=\"variant\"\n    :size=\"size\"\n    :disabled=\"disabled\"\n    :type=\"type\"\n    @click=\"copy\"\n  >\n    <!-- The glyph swap is the feedback's visual half only — never its only\n         carrier. The announcement carries the state to assistive technology,\n         and the accessible name stays `copy` throughout: a button whose name\n         changes under a screen reader's cursor is its own confusion. -->\n    <Check v-if=\"state === 'copied'\" class=\"h-4 w-4\" aria-hidden=\"true\" />\n    <X v-else-if=\"state === 'failed'\" class=\"h-4 w-4\" aria-hidden=\"true\" />\n    <Copy v-else class=\"h-4 w-4\" aria-hidden=\"true\" />\n  </IconButton>\n</template>\n"],"mappings":";;;;;;;;;AAYA,IAAa,qBAAuC;CAClD,MAAM;CACN,QAAQ;CACR,QAAQ;AACV;;AAGA,IAAa,iBAAiB;;;;;;;;;;;;;;;;EAU9B,MAAM,QAAQ;;;;;;;EAgCd,MAAM,WAAW,YAAY;EAM7B,MAAM,OAAO,UAAU,cAAc,0BAA0B,MAAM,MAAM;;;;;;;EAS3E,MAAM,QAAQ,IAAe,MAAM;EACnC,IAAI,UAAU;EACd,IAAI,cAAoD;EAExD,SAAS,iBAAuB;GAC9B,IAAI,gBAAgB,MAAM,aAAa,WAAW;GAClD,cAAc,iBAAiB;IAC7B,MAAM,QAAQ;IACd,cAAc;GAChB,GAAG,cAAc;EACnB;EAEA,sBAAsB;GAGpB,IAAI,gBAAgB,MAAM,aAAa,WAAW;GAClD,cAAc;EAChB,CAAC;EAED,eAAe,OAAsB;GACnC,IAAI,MAAM,YAAY,SAAS;GAC/B,UAAU;GACV,IAAI;IAIF,MAAM,QAAQ,MAAM,UAAU,MAAM,MAAM,QAAQ,IAAK,MAAM,SAAS;IACtE,MAAM,UAAU,UAAU,UAAU,KAAK;IACzC,MAAM,QAAQ;IACd,SAAS,KAAK,MAAM,MAAM;GAC5B,QAAQ;IACN,MAAM,QAAQ;IACd,SAAS,KAAK,MAAM,MAAM;GAC5B,UAAU;IACR,UAAU;IACV,eAAe;GACjB;EACF;;GAIE,OAAA,UAAA,GAAA,YAea,MAAA,kBAAA,GAAA;IAdV,OAAO,MAAA,IAAA,CAAI,CAAC;IACZ,SAAS,QAAA;IACT,MAAM,QAAA;IACN,UAAU,QAAA;IACV,MAAM,QAAA;IACN,SAAO;;IAMK,SAAA,cAAA,CAAA,MAAA,UAAK,YAAlB,UAAA,GAAA,YAAsE,MAAA,KAAA,GAAA;;KAArC,OAAM;KAAU,eAAY;IAC/C,CAAA,KAAA,MAAA,UAAK,YAAnB,UAAA,GAAA,YAAuE,MAAA,CAAA,GAAA;;KAArC,OAAM;KAAU,eAAY;IAC9D,CAAA,MAAA,UAAA,GAAA,YAAkD,MAAA,IAAA,GAAA;;KAArC,OAAM;KAAU,eAAY"}

package/dist/packages/primitives/copy-button/src/index.d.ts

@@ -0,0 +1,4 @@
+export { COPY_BUTTON_LABELS, COPY_REVERT_MS, default } from "./CopyButton.vue";
+export type { CopyButtonSize, CopyButtonVariant } from "./CopyButton.vue";
+export type { CopyButtonLabels } from "../../../labels/src/index";
+//# sourceMappingURL=index.d.ts.map

package/dist/packages/primitives/copy-button/src/index.js

@@ -0,0 +1,3 @@
+import "./CopyButton.vue_vue_type_script_setup_true_lang.js";
+import CopyButton_default from "./CopyButton.js";
+export { CopyButton_default as default };

package/dist/packages/primitives/data-grid/src/DataGrid.js

@@ -0,0 +1,7 @@
+import DataGrid_vue_vue_type_script_setup_true_lang_default, { DATA_GRID_LABELS } from "./DataGrid.vue_vue_type_script_setup_true_lang.js";
+//#region packages/primitives/data-grid/src/DataGrid.vue
+var DataGrid_default = DataGrid_vue_vue_type_script_setup_true_lang_default;
+//#endregion
+export { DATA_GRID_LABELS, DataGrid_default as default };
+
+//# sourceMappingURL=DataGrid.js.map

package/dist/packages/primitives/data-grid/src/DataGrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataGrid.js","names":[],"sources":["../../../../../packages/primitives/data-grid/src/DataGrid.vue"],"sourcesContent":["<script lang=\"ts\">\nimport type { DataGridLabels } from \"@ecoma-io/loom-labels\";\nimport type { TableAlign, TableDensity } from \"@ecoma-io/loom-table\";\n\n/**\n * Loom's English, co-located with the component so it tree-shakes with it,\n * and exported so a host can build a partial vocabulary against the real\n * thing rather than a transcription of it.\n */\nexport const DATA_GRID_LABELS: DataGridLabels = {\n  region: \"Data grid\",\n  selectAll: \"Select all rows\",\n  selectRow: \"Select row\",\n  sortedAscending: \"Sorted ascending\",\n  sortedDescending: \"Sorted descending\",\n  sort: \"Sort\",\n};\n\n/** One column: what it reads, whether it sorts, how it aligns. */\nexport interface DataGridColumn {\n  /** The row field this column renders; also the sort key. */\n  key: string;\n  /** The column header's text. */\n  header: string;\n  /** Renders the header as the tri-state sort control. */\n  sortable?: boolean;\n  /** Text alignment; numeric columns want `\"right\"`. */\n  align?: TableAlign;\n  /** Any CSS width, e.g. `\"6rem\"` — pins the column in the scrolling grid. */\n  width?: string;\n}\n\n/** Sort direction, compact union — `aria-sort` takes the full ARIA tokens. */\nexport type DataGridSort = \"asc\" | \"desc\";\n\n/** Which column is sorted, and which way. Absent: nothing is. */\nexport type DataGridSortState = { key: string; direction: DataGridSort } | undefined;\n\n/**\n * DataGrid — the WAI-ARIA grids pattern: `Table`'s visual language with the\n * interactive half added. Table reads, DataGrid acts — rows are selectable\n * (`v-model:selectedRowKeys`, select-all with a real `aria-checked=\"mixed\"`),\n * sortable headers carry `aria-sort`, and a row answers Enter/double-click\n * through `@row-activate`.\n *\n * The keyboard model is the APG one, and it is the reason this is not a\n * Table variant: the cell matrix holds exactly one Tab stop (roving\n * tabindex), so Tab enters and leaves the grid once while the arrow keys,\n * Home/End and their Ctrl variants move focus cell to cell. Focus — not\n * the pointer — is what a grid sells.\n *\n * There is no `aria-rowcount` on purpose: every row is in the DOM, so the\n * count is the DOM's to state. The attribute earns its place the day the\n * grid virtualizes, not before — an asserted virtual size over a real\n * partial DOM is the lie `aria-rowcount` exists to correct.\n */\n</script>\n\n<script setup lang=\"ts\">\nimport { computed, onBeforeUnmount, onMounted, ref, watch } from \"vue\";\nimport { ChevronDown, ChevronsUpDown, ChevronUp } from \"@lucide/vue\";\nimport { cn } from \"@ecoma-io/loom-core\";\nimport Checkbox from \"@ecoma-io/loom-checkbox\";\nimport { useLabels, type LabelOverrides } from \"@ecoma-io/loom-labels\";\nimport { headAlignClass, nextSort, tableRowVariants } from \"@ecoma-io/loom-table\";\n\nconst props = withDefaults(\n  defineProps<{\n    /** The columns, left to right. */\n    columns: DataGridColumn[];\n    /** The row objects; a column renders `row[column.key]`. */\n    rows: Array<Record<string, unknown>>;\n    /** The row field whose value keys selection. Defaults to `\"id\"`. */\n    rowKey?: string;\n    /** Adds the selection column: per-row checkboxes plus select-all with its mixed state. */\n    selectable?: boolean;\n    /**\n     * The selected row keys when the host owns the selection through\n     * `v-model:selectedRowKeys`; omit the binding and the grid owns the\n     * state itself while still reporting every change.\n     */\n    selectedRowKeys?: Array<string | number>;\n    /**\n     * The active sort when the host owns it through `v-model:sort`; omit it\n     * and the headers cycle on their own while still reporting each change.\n     */\n    sort?: DataGridSortState;\n    /** Row padding. Compact suits dense application chrome. */\n    density?: TableDensity;\n    /** The grid's accessible name, read before a screen reader enters it. */\n    caption?: string;\n    /** Names what the grid says on its own account, as any subset of `DataGridLabels`. */\n    labels?: LabelOverrides<DataGridLabels>;\n  }>(),\n  { rowKey: \"id\", selectable: false, density: \"comfortable\" },\n);\n\nconst emit = defineEmits<{\n  \"update:selectedRowKeys\": [value: Array<string | number>];\n  \"update:sort\": [value: DataGridSortState];\n  \"sort-change\": [value: DataGridSortState];\n  rowActivate: [row: Record<string, unknown>];\n}>();\n\n// `text`, not `labels`: the prop of that name is one of the three sources\n// this resolves (own prop, then the host vocabulary from\n// `provideLoomLabels`, then these English defaults), and a template reading\n// the raw prop would be reading the overrides rather than the answer.\nconst text = useLabels(\"dataGrid\", DATA_GRID_LABELS, () => props.labels);\n\n// ---------- selection ----------\n\nconst innerSelected = ref<Array<string | number>>([]);\nconst selected = computed(() => props.selectedRowKeys ?? innerSelected.value);\n\nconst keyOf = (row: Record<string, unknown>): string | number =>\n  row[props.rowKey] as string | number;\nconst isSelected = (row: Record<string, unknown>): boolean => selected.value.includes(keyOf(row));\n\nfunction setSelection(next: Array<string | number>): void {\n  innerSelected.value = next;\n  emit(\"update:selectedRowKeys\", next);\n}\n\nconst allSelected = computed(\n  () => props.rows.length > 0 && props.rows.every((row) => isSelected(row)),\n);\nconst someSelected = computed(\n  () => !allSelected.value && props.rows.some((row) => isSelected(row)),\n);\n\n// Checkbox's own third state: reka renders it as `aria-checked=\"mixed\"`,\n// which is the select-all announcement the grid owes — a dash glyph alone is\n// shape-only semantics.\nconst selectAllState = computed<\"indeterminate\" | boolean>(() =>\n  allSelected.value ? true : someSelected.value ? \"indeterminate\" : false,\n);\n\nfunction toggleAll(): void {\n  setSelection(allSelected.value ? [] : props.rows.map((row) => keyOf(row)));\n}\n\nfunction toggleRow(row: Record<string, unknown>): void {\n  setSelection(\n    isSelected(row)\n      ? selected.value.filter((key) => key !== keyOf(row))\n      : [...selected.value, keyOf(row)],\n  );\n}\n\nconst innerSort = ref<DataGridSortState>(undefined);\nconst currentSort = computed<DataGridSortState>(() => props.sort ?? innerSort.value);\n\nconst sortDirectionOf = (col: DataGridColumn): DataGridSort | undefined =>\n  currentSort.value?.key === col.key ? currentSort.value.direction : undefined;\n\nconst ARIA_SORT = { asc: \"ascending\", desc: \"descending\" } as const;\nconst SORT_ICON = { asc: ChevronUp, desc: ChevronDown } as const;\nconst ariaSortOf = (col: DataGridColumn): (typeof ARIA_SORT)[DataGridSort] | undefined => {\n  const direction = sortDirectionOf(col);\n  return direction ? ARIA_SORT[direction] : undefined;\n};\nconst sortIconOf = (col: DataGridColumn) => {\n  const direction = sortDirectionOf(col);\n  return direction ? SORT_ICON[direction] : ChevronsUpDown;\n};\nconst sortWordsOf = (col: DataGridColumn): string => {\n  const direction = sortDirectionOf(col);\n  return direction === \"asc\"\n    ? text.value.sortedAscending\n    : direction === \"desc\"\n      ? text.value.sortedDescending\n      : text.value.sort;\n};\n\nfunction toggleSort(col: DataGridColumn): void {\n  const direction = nextSort(sortDirectionOf(col));\n  const next: DataGridSortState = direction ? { key: col.key, direction } : undefined;\n  innerSort.value = next;\n  // `sort-change` for hosts following the sketch's `@sort-change`,\n  // `update:sort` so `v-model:sort` works the way every other control's does.\n  emit(\"update:sort\", next);\n  emit(\"sort-change\", next);\n}\n\nconst colCount = computed(() => props.columns.length + (props.selectable ? 1 : 0));\n\n// Rows: -1 is the header row, 0.. are body rows. Columns count the selection\n// column first when `selectable`. Exactly one cell carries tabindex 0 — the\n// active cell — so Tab enters and leaves the grid once; everything else is\n// -1 and reachable only through the matrix moves.\nconst activeCell = ref({ row: props.rows.length > 0 ? 0 : -1, col: 0 });\nconst bodyColumnIndex = (i: number): number => (props.selectable ? i + 1 : i);\nconst isCellActive = (row: number, col: number): boolean =>\n  activeCell.value.row === row && activeCell.value.col === col;\n\n// Rows arriving or leaving can strand the active cell outside the matrix. The\n// floor is -1, not 0: the header row is a valid roving stop too, and a floor\n// of 0 would push the header onto a body row that does not exist once every\n// row is gone, leaving the grid with no Tab stop at all.\nwatch(\n  () => [props.rows.length, props.selectable, props.columns.length] as const,\n  () => {\n    const previous = activeCell.value;\n    const next = {\n      row: Math.min(Math.max(previous.row, -1), Math.max(props.rows.length - 1, -1)),\n      col: Math.min(previous.col, colCount.value - 1),\n    };\n    activeCell.value = next;\n    // A shrink that moves the active cell strands real focus too: the focused\n    // cell unmounts, focus falls to <body>, and onFocusin — which only hears\n    // focus arriving inside the grid — never learns. The clamped cell is\n    // within the surviving matrix, so it exists to take focus back.\n    if (\n      (previous.row !== next.row || previous.col !== next.col) &&\n      table.value?.contains(document.activeElement)\n    ) {\n      focusCell(next.row, next.col);\n    }\n  },\n);\n\nconst table = ref<HTMLElement | null>(null);\nconst region = ref<HTMLElement | null>(null);\n\nfunction focusCell(row: number, col: number): void {\n  activeCell.value = { row, col };\n  table.value?.querySelector<HTMLElement>(`[data-r='${row}'][data-c='${col}']`)?.focus();\n}\n\nfunction moveTo(row: number, col: number): void {\n  focusCell(\n    // The floor is -1, not 0, for the same reason the watcher below uses it:\n    // with no body row, 0 would clamp onto a row that does not exist and\n    // strand the grid with no Tab stop (the header is `data-r=\"-1\"`).\n    Math.min(Math.max(row, -1), Math.max(props.rows.length - 1, -1)),\n    Math.min(Math.max(col, 0), colCount.value - 1),\n  );\n}\n\n// Focus can also arrive outside the keymap — a pointer tap lands directly on\n// a cell — and the roving Tab stop has to follow whoever actually holds it.\nfunction onFocusin(event: FocusEvent): void {\n  const cell = (event.target as Element).closest(\"[data-r]\");\n  if (cell) {\n    activeCell.value = {\n      row: Number(cell.getAttribute(\"data-r\")),\n      col: Number(cell.getAttribute(\"data-c\")),\n    };\n  }\n}\n\nfunction activateCell(row: number, col: number): void {\n  if (row < 0) {\n    const col_ = props.columns[col - (props.selectable ? 1 : 0)];\n    if (col_?.sortable) toggleSort(col_);\n    return;\n  }\n  const target = props.rows[row];\n  if (target) emit(\"rowActivate\", target);\n}\n\nfunction spaceCell(row: number, col: number): void {\n  if (!props.selectable) return;\n  if (row < 0) {\n    if (col === 0) toggleAll();\n    return;\n  }\n  const target = props.rows[row];\n  if (target) toggleRow(target);\n}\n\nfunction onKeydown(event: KeyboardEvent): void {\n  const cell = (event.target as Element).closest(\"[data-r]\");\n  if (!cell) return;\n  const row = Number(cell.getAttribute(\"data-r\"));\n  const col = Number(cell.getAttribute(\"data-c\"));\n  const lastRow = Math.max(props.rows.length - 1, 0);\n  const lastCol = colCount.value - 1;\n\n  switch (event.key) {\n    case \"ArrowRight\":\n      moveTo(row, col + 1);\n      break;\n    case \"ArrowLeft\":\n      moveTo(row, col - 1);\n      break;\n    case \"ArrowDown\":\n      moveTo(row + 1, col);\n      break;\n    case \"ArrowUp\":\n      moveTo(row - 1, col);\n      break;\n    case \"Home\":\n      event.ctrlKey || event.metaKey ? moveTo(0, 0) : moveTo(row, 0);\n      break;\n    case \"End\":\n      event.ctrlKey || event.metaKey ? moveTo(lastRow, lastCol) : moveTo(row, lastCol);\n      break;\n    case \"Enter\":\n      activateCell(row, col);\n      break;\n    case \" \":\n      spaceCell(row, col);\n      break;\n    default:\n      return;\n  }\n  event.preventDefault();\n}\n\n// ---------- scroll region (Table's mechanism, verbatim in spirit) ----------\n\n// The region is focusable only while it can actually scroll: a Tab stop that\n// never moves is a dead one. Overflow is measured, not assumed.\nconst scrollable = ref(false);\n\nfunction measure(): void {\n  const el = region.value;\n  if (el) scrollable.value = el.scrollWidth > el.clientWidth;\n}\n\nlet observer: ResizeObserver | undefined;\nonMounted(() => {\n  measure();\n  observer = new ResizeObserver(measure);\n  if (table.value) observer.observe(table.value);\n  window.addEventListener(\"resize\", measure, { passive: true });\n});\nonBeforeUnmount(() => {\n  observer?.disconnect();\n  window.removeEventListener(\"resize\", measure);\n});\n</script>\n\n<template>\n  <!-- A scroll container, not the table itself, for the reason Table's\n       wrapper documents: a wide grid overflows its region instead of\n       stretching the page. -->\n  <div\n    ref=\"region\"\n    role=\"region\"\n    :aria-label=\"caption ?? text.region\"\n    :tabindex=\"scrollable ? 0 : undefined\"\n    class=\"w-full overflow-x-auto rounded-lg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring focus-visible:shadow-halo\"\n  >\n    <!-- Roving focus ring, not focus-visible: the moves that matter here are\n         programmatic (arrow keys), and a ring that only answers\n         focus-visible hides the one thing a grid must never hide — which\n         cell holds focus. -->\n    <!-- tabindex=\"-1\" marks the interactive grid focusable without adding a\n         Tab stop: the cells own the single roving stop, the container is\n         only a target for programmatic/assistive-tech focus. -->\n    <table\n      ref=\"table\"\n      role=\"grid\"\n      tabindex=\"-1\"\n      :data-density=\"density\"\n      class=\"w-full border-collapse text-left text-sm focus:outline-none [&_th]:border-b [&_th]:border-border-strong [&_th]:px-3 [&_th]:py-2.5 [&_th]:text-xs [&_th]:font-semibold [&_th]:text-muted-foreground [&_th]:whitespace-nowrap [&_td]:border-b [&_td]:border-border [&_td]:px-3 [&_td]:align-top [&_td]:text-foreground [&[data-density='comfortable']_td]:py-3 [&[data-density='compact']_td]:py-1.5 [&[data-density='compact']_th]:py-1.5 [&_tbody_tr:last-child_td]:border-b-0\"\n      @keydown=\"onKeydown\"\n      @focusin=\"onFocusin\"\n    >\n      <thead>\n        <!-- Inside role=\"grid\" the native tr→row mapping does not apply; the\n             plugin cannot see the ancestor role, so the explicit role is load-bearing. -->\n        <!-- eslint-disable-next-line vuejs-accessibility/no-redundant-roles -->\n        <tr role=\"row\">\n          <!-- eslint-disable-next-line vuejs-accessibility/no-redundant-roles -->\n          <th\n            v-if=\"selectable\"\n            scope=\"col\"\n            role=\"columnheader\"\n            data-r=\"-1\"\n            :data-c=\"0\"\n            :tabindex=\"isCellActive(-1, 0) ? 0 : -1\"\n            class=\"focus:outline-2 focus:-outline-offset-2 focus:outline-ring\"\n          >\n            <Checkbox\n              :model-value=\"selectAllState\"\n              :aria-label=\"text.selectAll\"\n              tabindex=\"-1\"\n              @update:model-value=\"toggleAll()\"\n            />\n          </th>\n          <!-- eslint-disable-next-line vuejs-accessibility/no-redundant-roles -->\n          <th\n            v-for=\"(col, i) in columns\"\n            :key=\"col.key\"\n            scope=\"col\"\n            role=\"columnheader\"\n            :aria-sort=\"ariaSortOf(col)\"\n            :data-r=\"-1\"\n            :data-c=\"bodyColumnIndex(i)\"\n            :tabindex=\"isCellActive(-1, bodyColumnIndex(i)) ? 0 : -1\"\n            :style=\"col.width ? { width: col.width } : undefined\"\n            :class=\"\n              cn(\n                headAlignClass(col.align),\n                'focus:outline-2 focus:-outline-offset-2 focus:outline-ring',\n              )\n            \"\n          >\n            <!-- The sort button is reachable only through its header cell:\n                 a second Tab stop inside the matrix would break the\n                 enter-once contract. Enter on the cell sorts instead. -->\n            <button\n              v-if=\"col.sortable\"\n              type=\"button\"\n              tabindex=\"-1\"\n              class=\"inline-flex min-h-6 items-center gap-1 rounded-sm px-1 transition-colors duration-fast ease-out hover:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring focus-visible:shadow-halo\"\n              @click=\"toggleSort(col)\"\n            >\n              <span class=\"inline-flex items-center gap-1 font-semibold\">{{ col.header }}</span>\n              <component\n                :is=\"sortIconOf(col)\"\n                class=\"h-3.5 w-3.5 shrink-0 text-muted-foreground\"\n                aria-hidden=\"true\"\n              />\n              <span class=\"sr-only\">{{ sortWordsOf(col) }}</span>\n            </button>\n            <template v-else>{{ col.header }}</template>\n          </th>\n        </tr>\n      </thead>\n      <tbody>\n        <!-- eslint-disable-next-line vuejs-accessibility/no-redundant-roles -->\n        <tr\n          v-for=\"(row, r) in rows\"\n          :key=\"String(keyOf(row))\"\n          role=\"row\"\n          :aria-selected=\"selectable ? isSelected(row) : undefined\"\n          :class=\"\n            cn(\n              tableRowVariants({\n                state: selectable ? (isSelected(row) ? 'selected' : 'interactive') : 'none',\n              }),\n            )\n          \"\n          @dblclick=\"emit('rowActivate', row)\"\n        >\n          <td\n            v-if=\"selectable\"\n            role=\"gridcell\"\n            :data-r=\"r\"\n            :data-c=\"0\"\n            :tabindex=\"isCellActive(r, 0) ? 0 : -1\"\n            class=\"focus:outline-2 focus:-outline-offset-2 focus:outline-ring\"\n          >\n            <Checkbox\n              :model-value=\"isSelected(row)\"\n              :aria-label=\"text.selectRow\"\n              tabindex=\"-1\"\n              @update:model-value=\"toggleRow(row)\"\n            />\n          </td>\n          <td\n            v-for=\"(col, i) in columns\"\n            :key=\"col.key\"\n            role=\"gridcell\"\n            :data-r=\"r\"\n            :data-c=\"bodyColumnIndex(i)\"\n            :tabindex=\"isCellActive(r, bodyColumnIndex(i)) ? 0 : -1\"\n            :class=\"\n              cn(\n                headAlignClass(col.align),\n                'focus:outline-2 focus:-outline-offset-2 focus:outline-ring',\n              )\n            \"\n          >\n            <!-- @slot One cell's content — a Badge, a RowActions cluster —\n                 with `row`, `column` and `value` scoped in. -->\n            <slot name=\"cell\" :row=\"row\" :column=\"col\" :value=\"row[col.key]\">\n              {{ row[col.key] ?? \"\" }}\n            </slot>\n          </td>\n        </tr>\n      </tbody>\n    </table>\n  </div>\n</template>\n"],"mappings":""}

package/dist/packages/primitives/data-grid/src/DataGrid.vue.d.ts

@@ -0,0 +1,128 @@
+import { type LabelOverrides } from "../../../labels/src/index";
+import type { DataGridLabels } from "../../../labels/src/index";
+import type { TableAlign, TableDensity } from "../../table/src/index";
+/**
+ * Loom's English, co-located with the component so it tree-shakes with it,
+ * and exported so a host can build a partial vocabulary against the real
+ * thing rather than a transcription of it.
+ */
+export declare const DATA_GRID_LABELS: DataGridLabels;
+/** One column: what it reads, whether it sorts, how it aligns. */
+export interface DataGridColumn {
+    /** The row field this column renders; also the sort key. */
+    key: string;
+    /** The column header's text. */
+    header: string;
+    /** Renders the header as the tri-state sort control. */
+    sortable?: boolean;
+    /** Text alignment; numeric columns want `"right"`. */
+    align?: TableAlign;
+    /** Any CSS width, e.g. `"6rem"` — pins the column in the scrolling grid. */
+    width?: string;
+}
+/** Sort direction, compact union — `aria-sort` takes the full ARIA tokens. */
+export type DataGridSort = "asc" | "desc";
+/** Which column is sorted, and which way. Absent: nothing is. */
+export type DataGridSortState = {
+    key: string;
+    direction: DataGridSort;
+} | undefined;
+/**
+ * DataGrid — the WAI-ARIA grids pattern: `Table`'s visual language with the
+ * interactive half added. Table reads, DataGrid acts — rows are selectable
+ * (`v-model:selectedRowKeys`, select-all with a real `aria-checked="mixed"`),
+ * sortable headers carry `aria-sort`, and a row answers Enter/double-click
+ * through `@row-activate`.
+ *
+ * The keyboard model is the APG one, and it is the reason this is not a
+ * Table variant: the cell matrix holds exactly one Tab stop (roving
+ * tabindex), so Tab enters and leaves the grid once while the arrow keys,
+ * Home/End and their Ctrl variants move focus cell to cell. Focus — not
+ * the pointer — is what a grid sells.
+ *
+ * There is no `aria-rowcount` on purpose: every row is in the DOM, so the
+ * count is the DOM's to state. The attribute earns its place the day the
+ * grid virtualizes, not before — an asserted virtual size over a real
+ * partial DOM is the lie `aria-rowcount` exists to correct.
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
+    /** The columns, left to right. */
+    columns: DataGridColumn[];
+    /** The row objects; a column renders `row[column.key]`. */
+    rows: Array<Record<string, unknown>>;
+    /** The row field whose value keys selection. Defaults to `"id"`. */
+    rowKey?: string;
+    /** Adds the selection column: per-row checkboxes plus select-all with its mixed state. */
+    selectable?: boolean;
+    /**
+     * The selected row keys when the host owns the selection through
+     * `v-model:selectedRowKeys`; omit the binding and the grid owns the
+     * state itself while still reporting every change.
+     */
+    selectedRowKeys?: Array<string | number>;
+    /**
+     * The active sort when the host owns it through `v-model:sort`; omit it
+     * and the headers cycle on their own while still reporting each change.
+     */
+    sort?: DataGridSortState;
+    /** Row padding. Compact suits dense application chrome. */
+    density?: TableDensity;
+    /** The grid's accessible name, read before a screen reader enters it. */
+    caption?: string;
+    /** Names what the grid says on its own account, as any subset of `DataGridLabels`. */
+    labels?: LabelOverrides<DataGridLabels>;
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:sort": (value: DataGridSortState) => any;
+    "update:selectedRowKeys": (value: (string | number)[]) => any;
+    "sort-change": (value: DataGridSortState) => any;
+    rowActivate: (row: Record<string, unknown>) => any;
+}, string, import("vue").PublicProps, Readonly<{
+    /** The columns, left to right. */
+    columns: DataGridColumn[];
+    /** The row objects; a column renders `row[column.key]`. */
+    rows: Array<Record<string, unknown>>;
+    /** The row field whose value keys selection. Defaults to `"id"`. */
+    rowKey?: string;
+    /** Adds the selection column: per-row checkboxes plus select-all with its mixed state. */
+    selectable?: boolean;
+    /**
+     * The selected row keys when the host owns the selection through
+     * `v-model:selectedRowKeys`; omit the binding and the grid owns the
+     * state itself while still reporting every change.
+     */
+    selectedRowKeys?: Array<string | number>;
+    /**
+     * The active sort when the host owns it through `v-model:sort`; omit it
+     * and the headers cycle on their own while still reporting each change.
+     */
+    sort?: DataGridSortState;
+    /** Row padding. Compact suits dense application chrome. */
+    density?: TableDensity;
+    /** The grid's accessible name, read before a screen reader enters it. */
+    caption?: string;
+    /** Names what the grid says on its own account, as any subset of `DataGridLabels`. */
+    labels?: LabelOverrides<DataGridLabels>;
+}> & Readonly<{
+    "onUpdate:sort"?: (value: DataGridSortState) => any;
+    "onUpdate:selectedRowKeys"?: (value: (string | number)[]) => any;
+    "onSort-change"?: (value: DataGridSortState) => any;
+    onRowActivate?: (row: Record<string, unknown>) => any;
+}>, {
+    density: TableDensity;
+    rowKey: string;
+    selectable: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
+    cell?: (props: {
+        row: Record<string, unknown>;
+        column: DataGridColumn;
+        value: unknown;
+    }) => any;
+}>;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+//# sourceMappingURL=DataGrid.vue.d.ts.map