nuxt-ui-tools-spreadsheet

Files (1)

• SKILL.md

SKILL.md (first lines)

# nuxt-ui-tools Spreadsheet Import

Three layers, each usable without the next:

1. **Schema** (`defineSpreadsheetSchema`): the data contract. Columns, how headers and values
   match, rules, row identity, output. No UI.
2. **Runtime** (`useSpreadsheetImport`): headless state and commands, one reactive model per
   concern: `file`, `context`, `layout`, `columns`, `values`, `rows`, `review`, `submit`,
   `readiness`. Tests, scripts, and fully custom screens stop here.
3. **UI**: `UiSpreadsheetImport*` parts placed wherever you want (one page, a drawer, a wizard),
   optional steps (`useSpreadsheetSteps`), and one ready composition (`UiSpreadsheetImport`).

Matching is exact: a header or a value matches a declared name, ignoring case, accents, line
breaks, repeated spaces, and a trailing `*`. Anything else goes to the column's policy or to the
user. The engine never guesses.

Files are read with SheetJS (`xlsx`), an optional peer that must be 0.20.2 or later. npm only
serves 0.18.5, which has known vulnerabilities, so install it from the SheetJS CDN:
`bun add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`.

## Schema

Declare the context type first when columns depend on data the page provides. Every callback
receives it as `ctx`. Columns are a chain: each method adds a column, and the callbacks of a column
(`options`, `default`, `rules`, `parse`) receive `row`, typed with the columns declared above it.
Write `columns` before the callbacks that read whole rows (`rows`, `validate`, `output`): they are
typed from it.

```ts
interface AssessmentsContext {
  center: TestCenter
  products: readonly Product[] // each with its own `scale` and `skills`
}

const productOf = (ctx: AssessmentsContext, id: string) =>
  ctx.products.find((product) => product.id === id)

export const assessmentsImport = defineSpreadsheetSchema<AssessmentsContext>()({
  key: 'assessments',
  file: { accept: ['.xlsx', '.csv'], maxRows: 5000 },
  columns: (c) =>
    c
      .select('testCenterId', {
        label: 'Test center',
        headers: 'Test center ID',
        options: ({ ctx }) => [ctx.center.vtestId],
        default: ({ ctx }) => ctx.center.vtestId,
        unknown: 'error',
      })
      .text('secureCode', { label: 'Secure code', required: true })
      .text('examName', { label: 'Exam name', required: true })
      .select('productId', {
        label: 'Product',
        from: 'examName',
        options: ({ ctx }) =>
          ctx.products.map((product) => ({
            label: product.name,
            value: product.id,
            aliases: product.examNames,
          })),
        required: true,
      })
      .date('completedAt', {
        label: 'Completed at',
        formats: ['MMMM d, yyyy h:mm a'],
        rules: (v) => [v.notFuture()],
      })
      .number('score', {
        // `row.productId` is typed: the product column is declared above.
        rules: (v, { row, ctx }) => [v.max(productOf(ctx, row.productId)?.maxScore ?? 100)],
      })
      .group('levels', { label: 'CEFR levels' }, (g) =>
        g
          .select('general', {
            label: 'General',
            headers: 'General level',
            // Each product has its own scale: the options follow the row's product.
            options: ({ row, ctx }) => productOf(ctx, row.productId)?.scale ?? CEFR,
          })
          .select('listening', { label: 'Listening', headers: 'Listening level', options: CEFR }),
      )
      .dynamic('affiliations', {
        label: 'Affiliations',
        items: ({ ctx }) => ctx.center.affiliationGroups,
        column: (group, c) =>
          c.select(group.slug, {
            label: group.name,
            headers: `${group.name}: PRÉREQUIS CECR`,
            options: {
              source: toOptions(group.items),
              create: { handler: ({ label }) => api.affiliations.create(label) },
            },
            multiple: true,
            unknown: 'create',
          }),
      }),
  rows: {
    key: (row) => row.secureCode,
    duplicates: 'error',
    existing: {
      lookup: ({ keys, ctx }) => assessmentsByCodeQuery({ centerId: ctx.center.id, codes: keys }),
      action: ({ row, existing }) =>
        row.levels.general === existing.levels.general ? 'skip' : 'update',
    },
  },
  validate: ({ row, issue }) => [
    !row.levels.general &&
      row.status === 'Done' &&
      issue('levels.general', 'Required when the test is done'),
  ],
  output: ({ row, mode, existing, ctx }) => ({
    ...row,
    centerId: ctx.center.id,
    assessmentId: existing?.id,
  }),
})
```

A schema without context skips the type argument: `defineSpreadsheetSchema({ ... })`.

From ChronicStone/nuxt-ui-tools, MIT.

More from ChronicStone/nuxt-ui-tools