nuxt-ui-tools 1.12.0 → 1.13.0

package/dist/runtime/spreadsheet/components/spreadsheet-import.vue.d.ts

@@ -1,18 +1,33 @@
 import type { UiToolsLocale, UiToolsMessages } from '#ui-tools/i18n';
-import type { SpreadsheetComponentApi } from './types.js';
+import type { SpreadsheetImporter, SpreadsheetStep } from '../types/index.js';
+/**
+ * A ready-made import wizard built from the public parts: file, columns and values when needed,
+ * review, and import. Pass `steps` to reorder them or add your own; a slot named after a step key
+ * replaces its content.
+ */
 type __VLS_Props = {
-    spreadsheet: SpreadsheetComponentApi;
+    importer: SpreadsheetImporter;
+    steps?: readonly SpreadsheetStep[];
     title?: string;
-    description?: string;
-    onDownloadTemplate?: () => void;
     closable?: boolean;
-    mode?: 'inline' | 'fullscreen';
     locale?: UiToolsLocale<UiToolsMessages>;
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare var __VLS_28: string, __VLS_29: {
+    step: import("../types/index.js").SpreadsheetStepStatus;
+};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_28>]?: (props: typeof __VLS_29) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     close: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onClose?: (() => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/spreadsheet/components/{layout/spreadsheet-import-header.d.vue.ts → steps/spreadsheet-import-step-nav.d.vue.ts}

@@ -1,6 +1,10 @@
+import type { SpreadsheetImporter, SpreadsheetSteps } from '../../types/index.js';
 type __VLS_Props = {
-    title: string;
-    description?: string;
+    importer?: SpreadsheetImporter;
+    steps?: SpreadsheetSteps;
+    /** Page the Cancel button of the first step goes to. */
+    cancelTo?: string;
+    /** Shows Cancel on the first step and Close after the import, emitting `close`. */
     closable?: boolean;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {

package/dist/runtime/spreadsheet/components/steps/spreadsheet-import-step-nav.vue

@@ -0,0 +1,116 @@
+<script setup>
+import UButton from "@nuxt/ui/components/Button.vue";
+import { computed } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import {
+  useSpreadsheetImporter,
+  useSpreadsheetStepsContext
+} from "../../composables/use-spreadsheet-import-context";
+import SpreadsheetImportSubmitButton from "../parts/spreadsheet-import-submit-button.vue";
+const props = defineProps({
+  importer: { type: Object, required: false },
+  steps: { type: Object, required: false },
+  cancelTo: { type: String, required: false },
+  closable: { type: Boolean, required: false }
+});
+const emit = defineEmits(["close"]);
+const importer = useSpreadsheetImporter(() => props.importer);
+const steps = useSpreadsheetStepsContext(() => props.steps);
+const { t } = useUiToolsLocale();
+const step = computed(() => steps.value?.step ?? null);
+const submitting = computed(() => step.value?.builtIn === "submit");
+const status = computed(() => importer.value.submit.status);
+const hint = computed(() => {
+  const current = step.value;
+  if (!current) return { blocking: false, text: "" };
+  if (current.builtIn === "file" && !importer.value.file.loaded)
+    return { blocking: false, text: t("spreadsheet.nav.blockers.file") };
+  if (current.builtIn === "columns" && current.blockers)
+    return {
+      blocking: true,
+      text: t("spreadsheet.nav.blockers.columns", { count: current.blockers })
+    };
+  if (current.builtIn === "values" && current.blockers)
+    return {
+      blocking: true,
+      text: t("spreadsheet.nav.blockers.values", { count: current.blockers })
+    };
+  if (current.builtIn === "review") {
+    if (!importer.value.readiness.importable)
+      return { blocking: true, text: t("spreadsheet.nav.blockers.review") };
+    const invalid = importer.value.readiness.invalidRows;
+    return {
+      blocking: false,
+      text: invalid ? t("spreadsheet.nav.blockers.invalid", { count: invalid }) : ""
+    };
+  }
+  return { blocking: false, text: "" };
+});
+function next() {
+  steps.value?.next();
+}
+function back() {
+  steps.value?.back();
+}
+function another() {
+  importer.value.reset();
+  steps.value?.reset();
+}
+</script>
+
+<template>
+  <div v-if="steps" data-spreadsheet-step-nav class="flex flex-wrap items-center gap-x-3 gap-y-2">
+    <UButton
+      v-if="steps.canBack && status !== 'running' && status !== 'done'"
+      color="neutral"
+      variant="outline"
+      icon="i-lucide-arrow-left"
+      :label="t('spreadsheet.nav.back')"
+      @click="back"
+    />
+    <UButton
+      v-else-if="!steps.canBack && cancelTo"
+      color="neutral"
+      variant="ghost"
+      :to="cancelTo"
+      :label="t('spreadsheet.nav.cancel')"
+    />
+    <UButton
+      v-else-if="!steps.canBack && closable"
+      color="neutral"
+      variant="ghost"
+      :label="t('spreadsheet.nav.cancel')"
+      @click="emit('close')"
+    />
+    <span
+      v-if="hint.text"
+      class="order-last basis-full text-sm sm:order-none sm:ms-auto sm:basis-auto sm:text-end"
+      :class="hint.blocking ? 'font-medium text-error' : 'text-muted'"
+    >
+      {{ hint.text }}
+    </span>
+    <div class="ms-auto flex gap-2" :class="hint.text ? 'sm:ms-0' : ''">
+      <template v-if="submitting">
+        <SpreadsheetImportSubmitButton v-if="status === 'idle' || status === 'running'" />
+        <template v-else-if="status === 'done'">
+          <UButton
+            color="neutral"
+            variant="outline"
+            :label="t('spreadsheet.nav.another')"
+            @click="another"
+          />
+          <UButton v-if="closable" :label="t('spreadsheet.nav.close')" @click="emit('close')" />
+          <UButton v-else-if="cancelTo" :to="cancelTo" :label="t('spreadsheet.nav.close')" />
+        </template>
+      </template>
+      <UButton
+        v-else
+        data-spreadsheet-next
+        trailing-icon="i-lucide-arrow-right"
+        :label="t('spreadsheet.nav.continue')"
+        :disabled="!steps.canNext"
+        @click="next"
+      />
+    </div>
+  </div>
+</template>

package/dist/runtime/spreadsheet/components/{layout/spreadsheet-import-header.vue.d.ts → steps/spreadsheet-import-step-nav.vue.d.ts}

@@ -1,6 +1,10 @@
+import type { SpreadsheetImporter, SpreadsheetSteps } from '../../types/index.js';
 type __VLS_Props = {
-    title: string;
-    description?: string;
+    importer?: SpreadsheetImporter;
+    steps?: SpreadsheetSteps;
+    /** Page the Cancel button of the first step goes to. */
+    cancelTo?: string;
+    /** Shows Cancel on the first step and Close after the import, emitting `close`. */
     closable?: boolean;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {

package/dist/runtime/spreadsheet/components/steps/spreadsheet-import-step.d.vue.ts

@@ -0,0 +1,26 @@
+import type { SpreadsheetImporter, SpreadsheetSteps } from '../../types/index.js';
+/**
+ * The current step. A slot named after the step key replaces its content; built-in steps
+ * otherwise render their default parts.
+ */
+type __VLS_Props = {
+    importer?: SpreadsheetImporter;
+    steps?: SpreadsheetSteps;
+    /** Shows the built-in title and description above the default content. */
+    headings?: boolean;
+};
+declare var __VLS_2: string, __VLS_3: {
+    step: import("../../types/index.js").SpreadsheetStepStatus;
+};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_2>]?: (props: typeof __VLS_3) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/spreadsheet/components/steps/spreadsheet-import-step.vue

@@ -0,0 +1,106 @@
+<script setup>
+import { computed } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import {
+  useSpreadsheetImporter,
+  useSpreadsheetStepsContext
+} from "../../composables/use-spreadsheet-import-context";
+import SpreadsheetImportHeading from "../internal/spreadsheet-import-heading.vue";
+import SpreadsheetImportColumnMapping from "../parts/spreadsheet-import-column-mapping.vue";
+import SpreadsheetImportDropzone from "../parts/spreadsheet-import-dropzone.vue";
+import SpreadsheetImportExpectedColumns from "../parts/spreadsheet-import-expected-columns.vue";
+import SpreadsheetImportExportButton from "../parts/spreadsheet-import-export-button.vue";
+import SpreadsheetImportFileCard from "../parts/spreadsheet-import-file-card.vue";
+import SpreadsheetImportProgress from "../parts/spreadsheet-import-progress.vue";
+import SpreadsheetImportRowInspector from "../parts/spreadsheet-import-row-inspector.vue";
+import SpreadsheetImportSourceSettings from "../parts/spreadsheet-import-source-settings.vue";
+import SpreadsheetImportStats from "../parts/spreadsheet-import-stats.vue";
+import SpreadsheetImportSummary from "../parts/spreadsheet-import-summary.vue";
+import SpreadsheetImportTableToolbar from "../parts/spreadsheet-import-table-toolbar.vue";
+import SpreadsheetImportTable from "../parts/spreadsheet-import-table.vue";
+import SpreadsheetImportTemplateButton from "../parts/spreadsheet-import-template-button.vue";
+import SpreadsheetImportValueMapping from "../parts/spreadsheet-import-value-mapping.vue";
+const props = defineProps({
+  importer: { type: Object, required: false },
+  steps: { type: Object, required: false },
+  headings: { type: Boolean, required: false }
+});
+const importer = useSpreadsheetImporter(() => props.importer);
+const steps = useSpreadsheetStepsContext(() => props.steps);
+const { t } = useUiToolsLocale();
+const step = computed(() => steps.value?.step ?? null);
+</script>
+
+<template>
+  <div v-if="step" :key="step.key" :data-spreadsheet-step="step.key" class="grid min-w-0 gap-5">
+    <slot :name="step.key" :step="step">
+      <template v-if="step.builtIn === 'file'">
+        <SpreadsheetImportHeading
+          v-if="headings"
+          :title="t('spreadsheet.headings.file.title')"
+          :description="t('spreadsheet.headings.file.description')"
+        >
+          <SpreadsheetImportTemplateButton v-if="!importer.file.loaded" />
+        </SpreadsheetImportHeading>
+        <template v-if="importer.file.loaded">
+          <SpreadsheetImportFileCard />
+          <SpreadsheetImportSourceSettings />
+        </template>
+        <template v-else>
+          <SpreadsheetImportDropzone />
+          <SpreadsheetImportExpectedColumns />
+        </template>
+      </template>
+      <template v-else-if="step.builtIn === 'columns'">
+        <SpreadsheetImportHeading
+          v-if="headings"
+          :title="t('spreadsheet.headings.columns.title')"
+          :description="t('spreadsheet.headings.columns.description')"
+        />
+        <SpreadsheetImportColumnMapping />
+      </template>
+      <template v-else-if="step.builtIn === 'values'">
+        <SpreadsheetImportHeading
+          v-if="headings"
+          :title="t('spreadsheet.headings.values.title')"
+          :description="t('spreadsheet.headings.values.description')"
+        />
+        <SpreadsheetImportValueMapping />
+      </template>
+      <template v-else-if="step.builtIn === 'review'">
+        <SpreadsheetImportHeading
+          v-if="headings"
+          :title="t('spreadsheet.headings.review.title')"
+          :description="t('spreadsheet.headings.review.description')"
+        >
+          <SpreadsheetImportExportButton />
+        </SpreadsheetImportHeading>
+        <SpreadsheetImportStats />
+        <div class="min-w-0 overflow-hidden rounded-xl border border-default">
+          <SpreadsheetImportTableToolbar />
+          <div
+            class="grid min-w-0"
+            :class="importer.review.inspected ? 'lg:grid-cols-[minmax(0,1fr)_24rem]' : ''"
+          >
+            <SpreadsheetImportTable />
+            <SpreadsheetImportRowInspector
+              v-if="importer.review.inspected"
+              class="border-default max-lg:border-t lg:border-s"
+            />
+          </div>
+        </div>
+      </template>
+      <template v-else-if="step.builtIn === 'submit'">
+        <SpreadsheetImportProgress v-if="importer.submit.status !== 'idle'" />
+        <template v-else>
+          <SpreadsheetImportHeading
+            v-if="headings"
+            :title="t('spreadsheet.headings.submit.title')"
+            :description="t('spreadsheet.headings.submit.description')"
+          />
+          <SpreadsheetImportSummary />
+        </template>
+      </template>
+    </slot>
+  </div>
+</template>

package/dist/runtime/spreadsheet/components/steps/spreadsheet-import-step.vue.d.ts

@@ -0,0 +1,26 @@
+import type { SpreadsheetImporter, SpreadsheetSteps } from '../../types/index.js';
+/**
+ * The current step. A slot named after the step key replaces its content; built-in steps
+ * otherwise render their default parts.
+ */
+type __VLS_Props = {
+    importer?: SpreadsheetImporter;
+    steps?: SpreadsheetSteps;
+    /** Shows the built-in title and description above the default content. */
+    headings?: boolean;
+};
+declare var __VLS_2: string, __VLS_3: {
+    step: import("../../types/index.js").SpreadsheetStepStatus;
+};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_2>]?: (props: typeof __VLS_3) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/spreadsheet/components/steps/spreadsheet-import-stepper.d.vue.ts

@@ -0,0 +1,15 @@
+import type { SpreadsheetSteps } from '../../types/index.js';
+type __VLS_Props = {
+    steps?: SpreadsheetSteps;
+    /** `vertical` lists steps with their hints from `lg` up, and a row of steps below. */
+    orientation?: 'horizontal' | 'vertical';
+    /** Vertical only: numbers without labels, for a narrow rail. */
+    compact?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    compact: boolean;
+    steps: SpreadsheetSteps;
+    orientation: "horizontal" | "vertical";
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/spreadsheet/components/steps/spreadsheet-import-stepper.vue

@@ -0,0 +1,131 @@
+<script setup>
+import UIcon from "@nuxt/ui/components/Icon.vue";
+import { computed } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import { resolveTextValue } from "#ui-tools/shared/utils/render";
+import { useSpreadsheetStepsContext } from "../../composables/use-spreadsheet-import-context";
+const props = defineProps({
+  steps: { type: Object, required: false, default: void 0 },
+  orientation: { type: String, required: false, default: "horizontal" },
+  compact: { type: Boolean, required: false, default: false }
+});
+const steps = useSpreadsheetStepsContext(() => props.steps);
+const { t } = useUiToolsLocale();
+const entries = computed(
+  () => (steps.value?.list ?? []).map((step) => ({
+    ...step,
+    hintText: resolveTextValue(
+      step.hint,
+      step.builtIn ? t(`spreadsheet.stepHints.${step.builtIn}`) : ""
+    ),
+    labelText: resolveTextValue(
+      step.label,
+      step.builtIn ? t(`spreadsheet.steps.${step.builtIn}`) : step.key
+    )
+  }))
+);
+function open(step) {
+  if (step.state === "done") steps.value?.goTo(step.key);
+}
+function markerClass(state) {
+  return {
+    current: "border-primary bg-primary text-[var(--nut-sheet-accent-fg,var(--ui-text-inverted))]",
+    done: "border-inverted bg-inverted text-inverted",
+    skipped: "border-transparent bg-accented text-muted",
+    upcoming: "border-accented bg-default text-muted"
+  }[state];
+}
+</script>
+
+<template>
+  <ol
+    v-if="orientation === 'vertical'"
+    data-spreadsheet-stepper="vertical"
+    class="flex gap-1 overflow-x-auto lg:flex-col lg:gap-0.5 lg:overflow-visible"
+  >
+    <li v-for="entry in entries" :key="entry.key" class="shrink-0 lg:shrink">
+      <button
+        type="button"
+        class="flex w-full items-start gap-3 rounded-lg p-2.5 text-start transition-colors"
+        :class="[
+  entry.state === 'current' ? 'bg-default shadow-xs ring-1 ring-default' : '',
+  entry.state === 'done' ? 'cursor-pointer hover:bg-default/60' : 'cursor-default',
+  compact ? 'lg:justify-center' : ''
+]"
+        :aria-current="entry.state === 'current' ? 'step' : void 0"
+        :tabindex="entry.state === 'done' ? 0 : -1"
+        :title="compact ? entry.labelText : void 0"
+        @click="open(entry)"
+      >
+        <span
+          class="grid size-6 shrink-0 place-items-center rounded-full border-[1.5px] text-[11.5px] font-semibold tabular-nums"
+          :class="markerClass(entry.state)"
+        >
+          <UIcon
+            v-if="entry.state === 'done' || entry.state === 'skipped'"
+            name="i-lucide-check"
+            class="size-3"
+          />
+          <template v-else>{{ entry.position }}</template>
+        </span>
+        <span class="grid min-w-0 gap-px pt-0.5" :class="compact ? 'lg:sr-only' : ''">
+          <span
+            class="flex items-baseline gap-1.5 text-[13.5px] leading-5 whitespace-nowrap"
+            :class="{
+  'font-semibold text-highlighted': entry.state === 'current',
+  'font-medium text-toned': entry.state === 'done',
+  'font-medium text-muted': entry.state === 'upcoming' || entry.state === 'skipped'
+}"
+          >
+            {{ entry.labelText }}
+            <small v-if="entry.skipped" class="text-[11px] font-normal text-dimmed">{{
+              t("spreadsheet.steps.auto")
+            }}</small>
+          </span>
+          <span v-if="entry.hintText" class="hidden text-xs leading-4 text-dimmed lg:block">{{
+            entry.hintText
+          }}</span>
+        </span>
+      </button>
+    </li>
+  </ol>
+  <ol v-else data-spreadsheet-stepper="horizontal" class="flex border-b border-default">
+    <li
+      v-for="entry in entries"
+      :key="entry.key"
+      class="min-w-0 flex-1"
+      :class="entry.state === 'current' ? 'max-sm:flex-[3]' : ''"
+    >
+      <button
+        type="button"
+        class="relative flex w-full items-center gap-2 pb-3 text-start text-sm"
+        :class="[
+  entry.state === 'current' ? 'font-semibold text-highlighted' : 'text-muted',
+  entry.state === 'done' ? 'cursor-pointer text-toned hover:text-highlighted' : 'cursor-default'
+]"
+        :aria-current="entry.state === 'current' ? 'step' : void 0"
+        :tabindex="entry.state === 'done' ? 0 : -1"
+        @click="open(entry)"
+      >
+        <span
+          class="grid size-[22px] shrink-0 place-items-center rounded-full border-[1.5px] text-[11px] font-semibold tabular-nums"
+          :class="markerClass(entry.state)"
+        >
+          <UIcon
+            v-if="entry.state === 'done' || entry.state === 'skipped'"
+            name="i-lucide-check"
+            class="size-3"
+          />
+          <template v-else>{{ entry.position }}</template>
+        </span>
+        <span class="truncate" :class="entry.state === 'current' ? 'inline' : 'hidden sm:inline'">{{
+          entry.labelText
+        }}</span>
+        <span
+          v-if="entry.state === 'current'"
+          class="absolute inset-x-0 -bottom-px h-0.5 rounded-full bg-primary"
+        />
+      </button>
+    </li>
+  </ol>
+</template>

package/dist/runtime/spreadsheet/components/steps/spreadsheet-import-stepper.vue.d.ts

@@ -0,0 +1,15 @@
+import type { SpreadsheetSteps } from '../../types/index.js';
+type __VLS_Props = {
+    steps?: SpreadsheetSteps;
+    /** `vertical` lists steps with their hints from `lg` up, and a row of steps below. */
+    orientation?: 'horizontal' | 'vertical';
+    /** Vertical only: numbers without labels, for a narrow rail. */
+    compact?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    compact: boolean;
+    steps: SpreadsheetSteps;
+    orientation: "horizontal" | "vertical";
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/spreadsheet/composables/index.d.ts

@@ -1 +1,3 @@
 export * from './use-spreadsheet-import.js';
+export * from './use-spreadsheet-steps.js';
+export * from './use-spreadsheet-import-context.js';

package/dist/runtime/spreadsheet/composables/index.js

@@ -1 +1,3 @@
 export * from "./use-spreadsheet-import.js";
+export * from "./use-spreadsheet-steps.js";
+export * from "./use-spreadsheet-import-context.js";

package/dist/runtime/spreadsheet/composables/use-spreadsheet-answers.d.ts

@@ -0,0 +1,8 @@
+import type { SpreadsheetValueAnswer } from '../types/index.js';
+/** Answers given by the user to values that match no option, by field and normalized value. */
+export declare function useSpreadsheetAnswers(): {
+    answers: import("vue").ShallowRef<Readonly<Record<string, Readonly<Record<string, SpreadsheetValueAnswer>>>>, Readonly<Record<string, Readonly<Record<string, SpreadsheetValueAnswer>>>>>;
+    clear: () => void;
+    remove: (field: string, key: string) => void;
+    set: (field: string, key: string, answer: SpreadsheetValueAnswer) => void;
+};

package/dist/runtime/spreadsheet/composables/use-spreadsheet-answers.js

@@ -0,0 +1,19 @@
+import { shallowRef } from "vue";
+export function useSpreadsheetAnswers() {
+  const answers = shallowRef({});
+  function set(field, key, answer) {
+    answers.value = { ...answers.value, [field]: { ...answers.value[field], [key]: answer } };
+  }
+  function remove(field, key) {
+    const current = answers.value[field];
+    if (!current || !(key in current)) return;
+    answers.value = {
+      ...answers.value,
+      [field]: Object.fromEntries(Object.entries(current).filter(([entry]) => entry !== key))
+    };
+  }
+  function clear() {
+    answers.value = {};
+  }
+  return { answers, clear, remove, set };
+}

package/dist/runtime/spreadsheet/composables/use-spreadsheet-columns.d.ts

@@ -0,0 +1,23 @@
+import type { SpreadsheetFieldState } from '../types/index.js';
+import type { useSpreadsheetContext } from './use-spreadsheet-context.js';
+import type { useSpreadsheetFields } from './use-spreadsheet-fields.js';
+import type { useSpreadsheetLayout } from './use-spreadsheet-layout.js';
+export interface UseSpreadsheetColumnsParams {
+    fields: ReturnType<typeof useSpreadsheetFields>;
+    layout: ReturnType<typeof useSpreadsheetLayout>;
+    context: ReturnType<typeof useSpreadsheetContext>;
+}
+/**
+ * Which column each field reads. Headers name fields exactly; the user can choose another column
+ * or none. Choices are kept while the header texts stay the same.
+ */
+export declare function useSpreadsheetColumns(params: UseSpreadsheetColumnsParams): {
+    assign: (field: string, header: number) => void;
+    clear: () => void;
+    ignore: (field: string) => void;
+    manual: import("vue").ShallowRef<Readonly<Record<string, number | null>>, Readonly<Record<string, number | null>>>;
+    matches: import("vue").ComputedRef<Map<string, number>>;
+    reset: (field: string) => void;
+    states: import("vue").ComputedRef<SpreadsheetFieldState<string>[]>;
+    unusedHeaders: import("vue").ComputedRef<import("..").SpreadsheetHeaderCell[]>;
+};

package/dist/runtime/spreadsheet/composables/use-spreadsheet-columns.js

@@ -0,0 +1,75 @@
+import { computed, shallowRef, watch } from "vue";
+import { matchSpreadsheetHeaders } from "../utils/index.js";
+export function useSpreadsheetColumns(params) {
+  const manual = shallowRef({});
+  const headerSignature = computed(
+    () => params.layout.headers.value.map((header) => header.normalized).join("|")
+  );
+  watch(headerSignature, () => {
+    manual.value = {};
+  });
+  const matches = computed(
+    () => matchSpreadsheetHeaders({
+      ctx: params.context.ctx.value,
+      fields: params.fields.columnFields.value,
+      headers: params.layout.headers.value,
+      manual: manual.value
+    })
+  );
+  function samplesOf(column) {
+    const values = [];
+    for (const row of params.layout.dataRows.value) {
+      const text = String(row[column] ?? "").trim();
+      if (text && !values.includes(text)) values.push(text);
+      if (values.length === 3) break;
+    }
+    return values;
+  }
+  const states = computed(
+    () => params.fields.fields.value.map((field) => {
+      const from = field.select?.from ?? null;
+      const column = from ? matches.value.get(from) : matches.value.get(field.path);
+      const header = column === void 0 ? null : params.layout.headers.value[column] ?? null;
+      const status = header !== null ? "matched" : field.hasDefault ? "default" : field.required ? "missing" : "unmatched";
+      return {
+        assignedBy: header === null ? null : field.path in manual.value ? "user" : "file",
+        description: field.description,
+        example: field.example,
+        from,
+        group: field.group,
+        header,
+        kind: field.kind,
+        label: field.label,
+        name: field.name,
+        path: field.path,
+        required: field.required,
+        samples: column === void 0 ? [] : samplesOf(column),
+        status,
+        suggestion: null
+      };
+    })
+  );
+  const unusedHeaders = computed(() => {
+    const used = new Set(matches.value.values());
+    return params.layout.headers.value.filter((header) => header.text && !used.has(header.index));
+  });
+  function assign(field, header) {
+    const next = {};
+    for (const [path, index] of Object.entries(manual.value))
+      if (index !== header) next[path] = index;
+    next[field] = header;
+    manual.value = next;
+  }
+  function ignore(field) {
+    manual.value = { ...manual.value, [field]: null };
+  }
+  function reset(field) {
+    manual.value = Object.fromEntries(
+      Object.entries(manual.value).filter(([path]) => path !== field)
+    );
+  }
+  function clear() {
+    manual.value = {};
+  }
+  return { assign, clear, ignore, manual, matches, reset, states, unusedHeaders };
+}