@pilotiq/pilotiq 0.1.0

package/src/actions/importFactory.ts

@@ -0,0 +1,222 @@
+/**
+ * Internals for the `Action.import` factory. Lives in its own module
+ * to keep the cycle between `Action.ts` and the field types (Select /
+ * FileUpload) honest — `Action.import` calls in here via dynamic import
+ * inside the handler.
+ */
+
+import type { ActionContext } from './Action.js'
+import { parseCsv } from '../io/csv.js'
+import type { Element } from '../schema/Element.js'
+import { FileUpload } from '../fields/FileUploadField.js'
+import { SelectField } from '../fields/SelectField.js'
+
+export type ImportFormat = 'csv' | 'json'
+
+export interface ImportSummary {
+  created:  number
+  updated:  number
+  skipped:  number
+  /** Per-row failure messages (non-empty `validate` returns + thrown
+   *  errors during create / update). 1-indexed for human-friendly
+   *  display in the success notification. */
+  errors:   Array<{ row: number; message: string }>
+}
+
+export interface ImportContext extends ActionContext {
+  rowIndex?: number
+}
+
+export interface ImportOptions {
+  /** CSV / JSON header → model attribute key. Default: identity (the
+   *  CSV header IS the model attribute). For JSON, this remaps the
+   *  parsed object keys 1:1. */
+  columns?: Record<string, string>
+  /** Output format. Default `'csv'`. JSON-format imports parse the
+   *  uploaded file as `JSON.parse(text)`; arrays import as-is, single
+   *  objects wrap into `[obj]`. */
+  format?: ImportFormat
+  /** Model attribute used as the upsert key. When set, the importer
+   *  looks up an existing record by `M.query().where(upsertBy, row[upsertBy])`
+   *  before deciding create vs update. When omitted, every row is a
+   *  create. */
+  upsertBy?: string
+  /** Per-row guard. Return a string to skip the row + accumulate as a
+   *  failure; return `null` (or `undefined`) to allow the row through.
+   *  Async-aware. */
+  validate?: (
+    row: Record<string, unknown>,
+    ctx: ImportContext,
+  ) => string | null | undefined | Promise<string | null | undefined>
+  /** Mutate the row payload before `M.create`. Async-aware. */
+  beforeCreate?: (
+    row: Record<string, unknown>,
+    ctx: ImportContext,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>
+  /** Mutate the row payload before `M.update`. Receives the existing
+   *  record so the hook can copy / preserve fields the import shouldn't
+   *  overwrite. Async-aware. */
+  beforeUpdate?: (
+    row: Record<string, unknown>,
+    existing: unknown,
+    ctx: ImportContext,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>
+  /** Hard cap on the row count. Aborts with an error notification when
+   *  exceeded — protects against accidental million-row uploads. Default
+   *  `10_000`. */
+  maxRows?: number
+  /** Final hook after the import loop. Useful for audit-log writes,
+   *  cache invalidation, etc. Async-aware. */
+  onComplete?: (summary: ImportSummary, ctx: ImportContext) => void | Promise<void>
+}
+
+/**
+ * Parse an uploaded file's text into an array of row objects keyed by
+ * model attribute (after applying `opts.columns` remap for CSV).
+ *
+ * Throws on invalid CSV / JSON; the caller's outer `try` surfaces the
+ * error message via the result notification.
+ */
+export function parseImportText(
+  text:    string,
+  format:  ImportFormat,
+  columns?: Record<string, string>,
+): Array<Record<string, unknown>> {
+  if (format === 'json') {
+    const parsed = JSON.parse(text) as unknown
+    if (Array.isArray(parsed)) return parsed as Array<Record<string, unknown>>
+    if (parsed && typeof parsed === 'object') return [parsed as Record<string, unknown>]
+    throw new Error('JSON import expected an array or object')
+  }
+  const csv = parseCsv(text)
+  if (!columns || Object.keys(columns).length === 0) {
+    return csv.rows
+  }
+  // Remap CSV headers → model keys. CSV cells stay as strings; the ORM
+  // does any final coercion (or the user's `beforeCreate` hook).
+  return csv.rows.map(row => {
+    const out: Record<string, unknown> = {}
+    for (const [csvKey, value] of Object.entries(row)) {
+      const modelKey = columns[csvKey] ?? csvKey
+      out[modelKey] = value
+    }
+    return out
+  })
+}
+
+/**
+ * Run the per-row import loop. Pulled out of the factory body so the
+ * factory stays at the level of "compose modal + handler" instead of
+ * "do the work".
+ *
+ * Returns the aggregated summary (counts + per-row error messages).
+ * Failures don't roll back — partial-success is the contract. The
+ * caller surfaces the summary via a notification.
+ */
+export async function runImport(
+  rows: Array<Record<string, unknown>>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  M:    any,
+  mode: 'create' | 'upsert',
+  opts: ImportOptions,
+  ctx:  ImportContext,
+): Promise<ImportSummary> {
+  const summary: ImportSummary = { created: 0, updated: 0, skipped: 0, errors: [] }
+  const upsertBy = opts.upsertBy
+
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]!
+    const rowCtx: ImportContext = { ...ctx, rowIndex: i }
+    try {
+      const guard = await opts.validate?.(row, rowCtx)
+      if (typeof guard === 'string' && guard.length > 0) {
+        summary.skipped++
+        summary.errors.push({ row: i + 1, message: guard })
+        continue
+      }
+
+      if (mode === 'upsert' && upsertBy) {
+        const slice = await M.query().where(upsertBy, row[upsertBy]).paginate(1, 1)
+        const existing = (slice?.data ?? [])[0]
+        if (existing) {
+          const id = String((existing as { id?: unknown }).id ?? '')
+          const payload = opts.beforeUpdate
+            ? await opts.beforeUpdate(row, existing, rowCtx)
+            : row
+          await M.update(id, payload)
+          summary.updated++
+          continue
+        }
+      }
+
+      const payload = opts.beforeCreate
+        ? await opts.beforeCreate(row, rowCtx)
+        : row
+      await M.create(payload)
+      summary.created++
+    } catch (err) {
+      summary.skipped++
+      summary.errors.push({ row: i + 1, message: err instanceof Error ? err.message : 'unknown' })
+    }
+  }
+
+  await opts.onComplete?.(summary, ctx)
+  return summary
+}
+
+/** Build the modal-form schema for an import action. v1 ships:
+ *
+ *  - `FileUpload.make('file')` — required, capped at 10 MB, accepts
+ *    `.csv,.json` by default; users can override the field via the
+ *    `Action.schema([...])` chain.
+ *  - When `upsertBy` is set, a `Select.make('mode')` toggles between
+ *    "Create only" and "Create or update" with `'upsert'` as the
+ *    default selection.
+ *
+ *  Returns an `Element[]` the factory drops into `Action.schema(...)`
+ *  to drive the auto-built modal form. */
+export function buildImportSchema(opts: ImportOptions): Element[] {
+  const elements: Element[] = []
+
+  const file = FileUpload.make('file')
+    .label('File')
+    .accept(['.csv', '.json', 'text/csv', 'application/json'])
+    .maxSize(10_000_000)
+    .required()
+  elements.push(file as unknown as Element)
+
+  if (typeof opts.upsertBy === 'string' && opts.upsertBy.length > 0) {
+    const mode = SelectField.make('mode')
+      .label('Mode')
+      .options([
+        { value: 'create', label: 'Create only' },
+        { value: 'upsert', label: 'Create or update' },
+      ])
+      .default('upsert')
+    elements.push(mode as unknown as Element)
+  }
+
+  return elements
+}
+
+/** Build a one-line success / warning notification body for the
+ *  import summary — surfaces the first 5 row failures inline so users
+ *  see what went wrong without hunting through logs. */
+export function buildImportNotification(summary: ImportSummary, opts: { upsert: boolean }): {
+  type:  'success' | 'warning' | 'error'
+  title: string
+  body?: string
+} {
+  const total = summary.created + summary.updated + summary.skipped
+  if (total === 0) {
+    return { type: 'warning', title: 'Import complete — no rows processed' }
+  }
+  const parts: string[] = [`${summary.created} created`]
+  if (opts.upsert) parts.push(`${summary.updated} updated`)
+  if (summary.skipped > 0) parts.push(`${summary.skipped} skipped`)
+  const title = `Import complete — ${parts.join(', ')}`
+  const type: 'success' | 'warning' = summary.errors.length > 0 ? 'warning' : 'success'
+  if (summary.errors.length === 0) return { type, title }
+  const body = summary.errors.slice(0, 5).map(e => `Row ${e.row}: ${e.message}`).join('\n')
+  return { type, title, body }
+}

package/src/actions/index.ts

@@ -0,0 +1,17 @@
+export {
+  Action,
+  type ActionPlacement,
+  type ActionContext,
+  type ActionHandler,
+  type ActionConfirm,
+  type ActionMeta,
+  type ActionColor,
+  type ActionSize,
+  type ActionVisibilityContext,
+  type VisibilityRule,
+} from './Action.js'
+
+export {
+  ActionGroup,
+  type ActionGroupMeta,
+} from './ActionGroup.js'

package/src/applyPageHooks.test.ts

@@ -0,0 +1,298 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { ElementMeta } from './schema/Element.js'
+import { applyPageHooks, pageHooksFor } from './applyPageHooks.js'
+import { Pilotiq } from './Pilotiq.js'
+import { Resource } from './Resource.js'
+import { Form } from './elements/Form.js'
+import { TextField } from './fields/TextField.js'
+import { Heading } from './schema/Heading.js'
+import { Alert } from './schema/Alert.js'
+import { resourceIndexData, resourceCreateData, resourceViewData, customPageData } from './pageData.js'
+import { Page } from './Page.js'
+
+const heading = (content: string): ElementMeta => ({ type: 'heading', content })
+const table   = (rows = 0): ElementMeta => ({ type: 'table', rows })
+const form    = (id = 'f'): ElementMeta => ({ type: 'form', formId: id })
+const tabs    = (children: ElementMeta[] = []): ElementMeta => ({ type: 'listTabs', children })
+
+describe('pageHooksFor()', () => {
+  it('returns universal page bounds for non-resource roles', () => {
+    assert.deepEqual(pageHooksFor('dashboard'), ['panels::page.start', 'panels::page.end'])
+    assert.deepEqual(pageHooksFor('page'),      ['panels::page.start', 'panels::page.end'])
+    assert.deepEqual(pageHooksFor('relation-list'), ['panels::page.start', 'panels::page.end'])
+  })
+
+  it('extends with table.before/.after/.tabs.end for list role', () => {
+    const names = pageHooksFor('list')
+    assert.ok(names.includes('panels::resource.pages.list-records.table.before'))
+    assert.ok(names.includes('panels::resource.pages.list-records.table.after'))
+    assert.ok(names.includes('panels::resource.pages.list-records.tabs.end'))
+  })
+
+  it('extends with form.before/.after for create role', () => {
+    const names = pageHooksFor('create')
+    assert.ok(names.includes('panels::resource.pages.create-record.form.before'))
+    assert.ok(names.includes('panels::resource.pages.create-record.form.after'))
+  })
+})
+
+describe('applyPageHooks()', () => {
+  it('returns input unchanged when hooks are empty', () => {
+    const input: ElementMeta[] = [heading('A')]
+    const out = applyPageHooks(input, {}, 'list')
+    assert.deepEqual(out, input)
+    assert.notEqual(out, input, 'returns a copy')
+  })
+
+  it('wraps with panels::page.start / panels::page.end on every role', () => {
+    const out = applyPageHooks(
+      [heading('content')],
+      {
+        'panels::page.start': [heading('top')],
+        'panels::page.end':   [heading('bottom')],
+      },
+      'dashboard',
+    )
+    assert.equal(out.length, 3)
+    assert.equal(out[0]?.['content'], 'top')
+    assert.equal(out[1]?.['content'], 'content')
+    assert.equal(out[2]?.['content'], 'bottom')
+  })
+
+  it('splices list-records.table.before/.after around the first table', () => {
+    const out = applyPageHooks(
+      [heading('intro'), table(), heading('outro')],
+      {
+        'panels::resource.pages.list-records.table.before': [heading('pre-table')],
+        'panels::resource.pages.list-records.table.after':  [heading('post-table')],
+      },
+      'list',
+    )
+    const types = out.map(m => `${m.type}:${m['content'] ?? ''}`)
+    assert.deepEqual(types, [
+      'heading:intro',
+      'heading:pre-table',
+      'table:',
+      'heading:post-table',
+      'heading:outro',
+    ])
+  })
+
+  it('splices around only the FIRST table, not subsequent ones', () => {
+    const out = applyPageHooks(
+      [table(1), table(2)],
+      { 'panels::resource.pages.list-records.table.before': [heading('once')] },
+      'list',
+    )
+    assert.equal(out.length, 3)
+    assert.equal(out[0]?.['content'], 'once')
+    assert.equal((out[1] as { rows?: number })['rows'], 1)
+    assert.equal((out[2] as { rows?: number })['rows'], 2)
+  })
+
+  it('drops table-around hooks silently when no table is present', () => {
+    const out = applyPageHooks(
+      [heading('only')],
+      { 'panels::resource.pages.list-records.table.before': [heading('lost')] },
+      'list',
+    )
+    assert.equal(out.length, 1)
+    assert.equal(out[0]?.['content'], 'only')
+  })
+
+  it('appends list-records.tabs.end into ListTabs._children', () => {
+    const out = applyPageHooks(
+      [tabs([heading('Tab1')])],
+      { 'panels::resource.pages.list-records.tabs.end': [heading('Trailing')] },
+      'list',
+    )
+    const updated = out[0] as ElementMeta
+    assert.equal(updated.type, 'listTabs')
+    assert.equal(updated.children?.length, 2)
+    assert.equal(updated.children?.[1]?.['content'], 'Trailing')
+  })
+
+  it('splices create-record.form.before/.after around the form', () => {
+    const out = applyPageHooks(
+      [form()],
+      {
+        'panels::resource.pages.create-record.form.before': [heading('pre-form')],
+        'panels::resource.pages.create-record.form.after':  [heading('post-form')],
+      },
+      'create',
+    )
+    assert.equal(out.length, 3)
+    assert.equal(out[0]?.['content'], 'pre-form')
+    assert.equal(out[1]?.type, 'form')
+    assert.equal(out[2]?.['content'], 'post-form')
+  })
+
+  it('splices edit-record.form.before/.after around the form', () => {
+    const out = applyPageHooks(
+      [form()],
+      {
+        'panels::resource.pages.edit-record.form.before': [heading('edit-pre')],
+        'panels::resource.pages.edit-record.form.after':  [heading('edit-post')],
+      },
+      'edit',
+    )
+    assert.equal(out.length, 3)
+    assert.equal(out[0]?.['content'], 'edit-pre')
+    assert.equal(out[2]?.['content'], 'edit-post')
+  })
+
+  it('wraps view-record.start/.end around schemaData', () => {
+    const out = applyPageHooks(
+      [heading('detail')],
+      {
+        'panels::resource.pages.view-record.start': [heading('view-top')],
+        'panels::resource.pages.view-record.end':   [heading('view-bottom')],
+      },
+      'view',
+    )
+    assert.equal(out.length, 3)
+    assert.equal(out[0]?.['content'], 'view-top')
+    assert.equal(out[2]?.['content'], 'view-bottom')
+  })
+
+  it('wraps page.start outside view-record.start (page wins outermost)', () => {
+    const out = applyPageHooks(
+      [heading('detail')],
+      {
+        'panels::page.start':                         [heading('outer-top')],
+        'panels::resource.pages.view-record.start':   [heading('inner-top')],
+        'panels::resource.pages.view-record.end':     [heading('inner-bottom')],
+        'panels::page.end':                           [heading('outer-bottom')],
+      },
+      'view',
+    )
+    const contents = out.map(m => m['content'])
+    assert.deepEqual(contents, ['outer-top', 'inner-top', 'detail', 'inner-bottom', 'outer-bottom'])
+  })
+
+  it('does not splice list-records.* on a non-list role', () => {
+    const out = applyPageHooks(
+      [table()],
+      { 'panels::resource.pages.list-records.table.before': [heading('lost')] },
+      'create',
+    )
+    assert.equal(out.length, 1)
+    assert.equal(out[0]?.type, 'table')
+  })
+
+  it('returns immutable result — input array unchanged', () => {
+    const input: ElementMeta[] = [table()]
+    const before = [...input]
+    applyPageHooks(input, {
+      'panels::resource.pages.list-records.table.before': [heading('x')],
+    }, 'list')
+    assert.deepEqual(input, before)
+  })
+})
+
+class Articles extends Resource {
+  static override label         = 'Articles'
+  static override labelSingular = 'Article'
+  static override slug          = 'articles'
+  static override form(form: Form): Form {
+    return form.schema([TextField.make('title')])
+  }
+}
+
+class HelpPage extends Page {
+  static override slug   = 'help'
+  static override label  = 'Help'
+  static override schema() { return [Heading.make('Help body')] }
+}
+
+describe('Per-builder render-hook integration', () => {
+  it('resourceIndexData splices list-records.table.before above the Table', async () => {
+    const panel = Pilotiq.make('admin')
+      .path('/admin')
+      .resources([Articles])
+      .renderHook(
+        'panels::resource.pages.list-records.table.before',
+        () => [Alert.make('Bulk import note').info()],
+      )
+    const data = await resourceIndexData(panel, 'articles')
+    const schema = data?.['schemaData'] as ElementMeta[]
+    const tableIdx = schema.findIndex(m => m.type === 'table')
+    assert.ok(tableIdx >= 0, 'expected a table')
+    // Alert should appear immediately before the table.
+    assert.equal(schema[tableIdx - 1]?.type, 'alert')
+  })
+
+  it('resourceIndexData fires panels::page.start above breadcrumbs (top-most)', async () => {
+    const panel = Pilotiq.make('admin')
+      .path('/admin')
+      .resources([Articles])
+      .renderHook('panels::page.start', () => [Heading.make('TopBanner')])
+    const data = await resourceIndexData(panel, 'articles')
+    const schema = data?.['schemaData'] as ElementMeta[]
+    assert.equal(schema[0]?.type, 'heading')
+    assert.equal(schema[0]?.['content'], 'TopBanner')
+  })
+
+  it('resourceCreateData splices create-record.form.before above the Form', async () => {
+    const panel = Pilotiq.make('admin')
+      .path('/admin')
+      .resources([Articles])
+      .renderHook(
+        'panels::resource.pages.create-record.form.before',
+        () => [Heading.make('Pre-form notes')],
+      )
+    const data = await resourceCreateData(panel, 'articles')
+    const schema = data?.['schemaData'] as ElementMeta[]
+    const formIdx = schema.findIndex(m => m.type === 'form')
+    assert.ok(formIdx >= 0)
+    assert.equal(schema[formIdx - 1]?.['content'], 'Pre-form notes')
+  })
+
+  it('only matching role fires — list-records hook absent on resourceViewData', async () => {
+    const panel = Pilotiq.make('admin')
+      .path('/admin')
+      .resources([Articles])
+      .renderHook(
+        'panels::resource.pages.list-records.table.before',
+        () => [Heading.make('Lost')],
+      )
+    const data = await resourceViewData(panel, 'articles', 'rec-1')
+    const schema = (data?.['schemaData'] ?? []) as ElementMeta[]
+    const found = schema.find(m => m.type === 'heading' && m['content'] === 'Lost')
+    assert.equal(found, undefined)
+  })
+
+  it('customPageData fires panels::page.start/.end on the page role', async () => {
+    const panel = Pilotiq.make('admin')
+      .path('/admin')
+      .pages([HelpPage])
+      .renderHook('panels::page.start', () => [Heading.make('Page banner')])
+    const data = await customPageData(panel, 'help')
+    const schema = data?.['schemaData'] as ElementMeta[]
+    assert.equal(schema[0]?.['content'], 'Page banner')
+  })
+
+  it('scoped hook only fires when the matching resource is active', async () => {
+    class OtherResource extends Resource {
+      static override label = 'Other'
+      static override slug  = 'other'
+      static override form(form: Form): Form { return form.schema([TextField.make('name')]) }
+    }
+    const panel = Pilotiq.make('admin')
+      .path('/admin')
+      .resources([Articles, OtherResource])
+      .renderHook(
+        'panels::resource.pages.list-records.table.before',
+        () => [Heading.make('ArticlesOnly')],
+        { resource: Articles },
+      )
+    const onArticles = await resourceIndexData(panel, 'articles')
+    const onOther    = await resourceIndexData(panel, 'other')
+    const aSchema = onArticles?.['schemaData'] as ElementMeta[]
+    const oSchema = onOther?.['schemaData']    as ElementMeta[]
+    assert.ok(aSchema.find(m => m.type === 'heading' && m['content'] === 'ArticlesOnly'))
+    assert.equal(oSchema.find(m => m.type === 'heading' && m['content'] === 'ArticlesOnly'), undefined)
+  })
+})