@pilotiq/pilotiq 0.1.0

package/src/theme/types.ts

@@ -0,0 +1,125 @@
+import { BASE_COLOR_NAMES, HUE_NAMES } from './colors.js'
+
+// ─── Style Presets ─────────────────────────────────────────
+
+/** Built-in style presets — each defines a complete set of OKLCH CSS variables.
+ *  `vega` is the Pilotiq brand (terracotta on cream, Satoshi). The other six are
+ *  placeholder neutrals awaiting visual differentiation. */
+export type StylePreset = 'vega' | 'nova' | 'maia' | 'lyra' | 'mira' | 'luma' | 'sera'
+
+// ─── Base Colors (gray/neutral scales) ─────────────────────
+
+/** Base color scale — controls the neutral/gray tones across the UI. */
+export type BaseColor = typeof BASE_COLOR_NAMES[number]
+
+// ─── Theme + Chart Colors ──────────────────────────────────
+
+/** Hue tokens shared by both the Theme color and Chart color pickers. */
+export type HueColor = typeof HUE_NAMES[number]
+
+/** Theme (primary) color — drives buttons, links, active states, ring.
+ *  `'base'` means "use the current base color's hue". Strings outside the
+ *  union are treated as raw hex/oklch seeds (custom color escape hatch). */
+export type ThemeColor = 'base' | HueColor | (string & {})
+
+/** Chart palette color — drives `--chart-1..5` as a single-hue ramp.
+ *  Same shape as `ThemeColor`. */
+export type ChartColor = ThemeColor
+
+// ─── Radius ────────────────────────────────────────────────
+
+/** Border radius preset. */
+export type RadiusPreset = 'none' | 'small' | 'default' | 'medium' | 'large' | 'xlarge'
+
+// ─── Spacing (UI density) ──────────────────────────────────
+
+/** Spacing density preset — drives Tailwind's `--spacing` multiplier so every
+ *  `p-*`, `gap-*`, `m-*` utility scales uniformly across the panel. */
+export type SpacingPreset = 'default' | 'compact' | 'comfortable'
+
+// ─── Icon Library ──────────────────────────────────────────
+
+/** Icon library identifier — controls which icon set is resolved. */
+export type IconLibrary = 'lucide' | 'tabler' | 'remix' | 'phosphor'
+
+// ─── Fonts ─────────────────────────────────────────────────
+
+export interface ThemeFonts {
+  /** Google Fonts family name for headings, e.g. 'Space Grotesk'. */
+  heading?: string
+  /** Google Fonts family name for body text, e.g. 'Inter'. */
+  body?: string
+}
+
+// ─── Theme Config (user-facing) ────────────────────────────
+
+/**
+ * Theme configuration — passed to `Pilotiq.theme()`.
+ *
+ * @example
+ * ```ts
+ * Pilotiq.make('admin').theme({
+ *   preset: 'vega',
+ *   baseColor: 'taupe',
+ *   themeColor: 'orange',
+ *   chartColor: 'base',
+ *   radius: 'medium',
+ *   fonts: { heading: 'Space Grotesk', body: 'Inter' },
+ * })
+ * ```
+ */
+export interface ThemeConfig {
+  /** Style preset — sets all CSS variables at once. Defaults to `'vega'`. */
+  preset?:      StylePreset
+  /** Base color scale — overrides neutral/gray tones from the preset. */
+  baseColor?:   BaseColor
+  /** Theme (primary) color. `'base'` = derive from current base color. */
+  themeColor?:  ThemeColor
+  /** Chart color. `'base'` = derive ramp from current base color. */
+  chartColor?:  ChartColor
+  /** Border radius preset. Defaults to `'medium'` (Pilotiq brand). */
+  radius?:      RadiusPreset
+  /** Spacing density preset. `'default'` falls through to the per-style value
+   *  in `PRESET_SPACING` (e.g. Mira → compact, Vega → comfortable). */
+  spacing?:     SpacingPreset
+  /** Font families (loaded from Google Fonts / Fontshare). */
+  fonts?:       ThemeFonts
+  /** Icon library. */
+  iconLibrary?: IconLibrary
+  /** Escape hatch: raw CSS variable overrides in OKLCH. Applied last, highest priority. */
+  cssVariables?: {
+    light?: Record<string, string>
+    dark?:  Record<string, string>
+  }
+}
+
+// ─── Theme Meta (serialized, server → client) ──────────────
+
+/** Resolved theme data sent from server to client via viewProps. */
+export interface ThemeMeta {
+  /** CSS variable map for :root (light mode). Keys are CSS custom property names. */
+  light: Record<string, string>
+  /** CSS variable map for .dark (dark mode). */
+  dark:  Record<string, string>
+  /** Border radius value (e.g. '0.625rem'). */
+  radius: string
+  /** Spacing multiplier for Tailwind's `--spacing` token (e.g. '0.25rem'). */
+  spacing: string
+  /** Google Fonts families to load via <link> tag. */
+  fonts?: ThemeFonts
+  /** Font family CSS values with fallbacks (e.g. "'Inter', sans-serif"). */
+  fontFamily?: {
+    heading?: string
+    body?:    string
+  }
+  /** Icon library identifier for frontend icon resolution. */
+  iconLibrary: IconLibrary
+}
+
+// ─── Preset Definition ─────────────────────────────────────
+
+/** A complete set of CSS variable values for light and dark modes (OKLCH strings). */
+export interface PresetDefinition {
+  light: Record<string, string>
+  dark:  Record<string, string>
+}

package/src/uploads/UploadAdapter.ts

@@ -0,0 +1,35 @@
+/**
+ * Pilotiq's upload contract. Apps register an adapter via
+ * `Pilotiq.uploads({ adapter })`; the `_uploads` route hands every
+ * incoming file to it. Pilotiq stays storage-agnostic — disk, S3,
+ * R2, GCS, or a custom storage backend all implement the same shape.
+ */
+export interface UploadAdapter {
+  /**
+   * Persist the file. Receive `{ file, directory? }`; return the
+   * URL the field should store. Throw to fail the upload — the
+   * route handler converts thrown errors into a 500 + toast.
+   */
+  put(req: UploadRequest): Promise<UploadResult>
+}
+
+export interface UploadRequest {
+  /** The browser-supplied File. Has `.name`, `.size`, `.type`, `.arrayBuffer()`. */
+  file:       File
+  /** Optional sub-directory hint set by `FileUpload.directory(...)`. */
+  directory?: string
+  /** The source field name — useful for adapter routing or audit logs. */
+  fieldName:  string
+}
+
+export interface UploadResult {
+  /** The public URL the field stores in the form value. */
+  url: string
+  /**
+   * Optional metadata to round-trip alongside the URL — file size,
+   * content type, etc. Renderers that show previews may use this.
+   * Not part of the form value; can be used by `afterStateUpdated`
+   * hooks server-side.
+   */
+  meta?: Record<string, unknown>
+}

package/src/uploads/index.ts

@@ -0,0 +1,2 @@
+export type { UploadAdapter, UploadRequest, UploadResult } from './UploadAdapter.js'
+export { localUpload, type LocalUploadConfig } from './localUpload.js'

package/src/uploads/localUpload.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, existsSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { localUpload } from './localUpload.js'
+
+describe('localUpload adapter', () => {
+  let dir: string
+
+  before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'pilotiq-uploads-'))
+  })
+
+  after(() => {
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('writes the file under root + returns a URL', async () => {
+    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
+    const file = new File([new Uint8Array([1, 2, 3, 4])], 'photo.png', { type: 'image/png' })
+    const result = await adapter.put({ file, fieldName: 'cover' })
+
+    assert.match(result.url, /^\/uploads\/[a-f0-9]{32}\.png$/)
+    assert.deepEqual(result.meta, { name: 'photo.png', size: 4, type: 'image/png' })
+
+    const filename = result.url.replace('/uploads/', '')
+    const fullPath = join(dir, filename)
+    assert.ok(existsSync(fullPath), 'file was written to disk')
+    const written = readFileSync(fullPath)
+    assert.deepEqual(Array.from(written), [1, 2, 3, 4])
+  })
+
+  it('honors the directory option', async () => {
+    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
+    const file = new File([new Uint8Array([0])], 'img.jpg', { type: 'image/jpeg' })
+    const result = await adapter.put({ file, fieldName: 'avatar', directory: 'avatars/2026' })
+    assert.match(result.url, /^\/uploads\/avatars\/2026\/[a-f0-9]{32}\.jpg$/)
+  })
+
+  it('strips path-traversal segments from directory', async () => {
+    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
+    const file = new File([new Uint8Array([0])], 'x.png', { type: 'image/png' })
+    const result = await adapter.put({ file, fieldName: 'x', directory: '../../../etc/passwd' })
+    assert.match(result.url, /^\/uploads\/etc\/passwd\/[a-f0-9]{32}\.png$/)
+  })
+
+  it('drops over-long extensions (anti-traversal)', async () => {
+    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
+    const file = new File([new Uint8Array([0])], 'note.thisisaverylongext', { type: 'text/plain' })
+    const result = await adapter.put({ file, fieldName: 'x' })
+    // Disallowed ext (>10 chars) → file written without extension
+    assert.match(result.url, /^\/uploads\/[a-f0-9]{32}$/)
+  })
+
+  it('drops extensions with non-alphanumeric chars', async () => {
+    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
+    const file = new File([new Uint8Array([0])], 'note.png; rm -rf', { type: 'text/plain' })
+    const result = await adapter.put({ file, fieldName: 'x' })
+    assert.match(result.url, /^\/uploads\/[a-f0-9]{32}$/)
+  })
+
+  it('strips trailing slash from urlPrefix', async () => {
+    const adapter = localUpload({ root: dir, urlPrefix: '/uploads/' })
+    const file = new File([new Uint8Array([0])], 'x.png', { type: 'image/png' })
+    const result = await adapter.put({ file, fieldName: 'x' })
+    assert.match(result.url, /^\/uploads\/[a-f0-9]{32}\.png$/)
+  })
+})

package/src/uploads/localUpload.ts

@@ -0,0 +1,84 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join, extname } from 'node:path'
+import { randomBytes } from 'node:crypto'
+
+import type { UploadAdapter, UploadRequest, UploadResult } from './UploadAdapter.js'
+
+export interface LocalUploadConfig {
+  /**
+   * Filesystem directory where files are written. Resolved relative to
+   * `process.cwd()` if not absolute. The app's static-file middleware
+   * must serve this directory at `urlPrefix`.
+   *
+   * Example: `{ root: 'public/uploads', urlPrefix: '/uploads' }` writes
+   * to `<cwd>/public/uploads/<dir>/<id>.<ext>` and returns
+   * `/uploads/<dir>/<id>.<ext>`.
+   */
+  root:      string
+  /** URL prefix the file is served from. Without trailing slash. */
+  urlPrefix: string
+}
+
+/**
+ * Disk-backed upload adapter. Writes incoming files under
+ * `config.root/<directory>/<random-id>.<ext>` and returns the public
+ * URL `<urlPrefix>/<directory>/<random-id>.<ext>`.
+ *
+ * v1: synchronous-ish (single `writeFile` per upload). No chunking,
+ * no resumable uploads, no image processing.
+ */
+export function localUpload(config: LocalUploadConfig): UploadAdapter {
+  return {
+    async put(req: UploadRequest): Promise<UploadResult> {
+      const { file, directory } = req
+      const ext     = sanitizeExt(extname(file.name))
+      const id      = randomId()
+      const subDir  = sanitizeDir(directory)
+      const fullDir = subDir
+        ? join(config.root, subDir)
+        : config.root
+
+      await mkdir(fullDir, { recursive: true })
+
+      const filename = `${id}${ext}`
+      const fullPath = join(fullDir, filename)
+      const buffer   = Buffer.from(await file.arrayBuffer())
+      await writeFile(fullPath, buffer)
+
+      const urlParts = [config.urlPrefix.replace(/\/$/, '')]
+      if (subDir) urlParts.push(subDir)
+      urlParts.push(filename)
+      return {
+        url: urlParts.join('/'),
+        meta: {
+          name: file.name,
+          size: file.size,
+          type: file.type,
+        },
+      }
+    },
+  }
+}
+
+function sanitizeDir(d: string | undefined): string {
+  if (!d) return ''
+  // Strip leading/trailing slashes and any ../ segments to avoid path
+  // traversal. Adapters are responsible for their own input validation.
+  return d
+    .replace(/^[/\\]+/, '')
+    .replace(/[/\\]+$/, '')
+    .split(/[/\\]/)
+    .filter(s => s !== '' && s !== '..' && s !== '.')
+    .join('/')
+}
+
+function sanitizeExt(ext: string): string {
+  // Extension comes from a user-uploaded filename — keep it conservative.
+  if (!ext || ext.length > 10) return ''
+  if (!/^\.[A-Za-z0-9]+$/.test(ext)) return ''
+  return ext.toLowerCase()
+}
+
+function randomId(): string {
+  return randomBytes(16).toString('hex')
+}

package/src/validation/Validator.ts

@@ -0,0 +1,49 @@
+/**
+ * Validation primitives.
+ *
+ * A `Validator` is a function: `(value, ctx?) => string | null | Promise<string | null>`.
+ * It returns an error message when invalid, or `null` when the value
+ * passes. Validators may carry an optional `serialized` descriptor — a
+ * JSON-safe shape mirrored to the client via `Field.toMeta()` so the
+ * browser can run the same rule for live UX before submit.
+ *
+ * The runtime is server-of-truth: client-side mirroring is best-effort.
+ * If `serialized` is omitted, the validator runs only on the server.
+ *
+ * Async validators (e.g. `unique()` probing the DB) return a `Promise`;
+ * the pipeline awaits each result before collecting the next field's
+ * errors. They are NOT mirrored to the client — the descriptor is omitted
+ * or marks itself `async: true` so the client skips the live check.
+ */
+
+/** JSON-safe descriptor of a built-in rule. Mirrored to the client. */
+export interface SerializedRule {
+  rule: string
+  message?: string
+  [key: string]: unknown
+}
+
+/**
+ * Optional context passed to a validator. `values` is the full submit
+ * payload — useful for cross-field rules (e.g. confirm-password). `record`
+ * is the persisted record under edit, when present.
+ */
+export interface ValidatorContext {
+  values?: Record<string, unknown>
+  record?: unknown
+}
+
+export type ValidatorFn = (
+  value: unknown,
+  ctx?:  ValidatorContext,
+) => string | null | Promise<string | null>
+
+/** A validator function, optionally tagged with a serialized descriptor. */
+export type Validator = ValidatorFn & { serialized?: SerializedRule }
+
+/** Wrap a `ValidatorFn` and attach an optional serialized descriptor. */
+export function makeValidator(fn: ValidatorFn, serialized?: SerializedRule): Validator {
+  const v = fn as Validator
+  if (serialized) v.serialized = serialized
+  return v
+}

package/src/validation/index.ts

@@ -0,0 +1,28 @@
+export {
+  makeValidator,
+  type Validator,
+  type ValidatorFn,
+  type ValidatorContext,
+  type SerializedRule,
+} from './Validator.js'
+
+export {
+  required,
+  email,
+  minLength,
+  maxLength,
+  min,
+  max,
+  pattern,
+} from './rules.js'
+
+export {
+  validateSchema,
+  isValid,
+  type ValidationErrors,
+} from './runValidators.js'
+
+export {
+  unique,
+  type UniqueOptions,
+} from './uniqueValidator.js'

package/src/validation/rules.ts

@@ -0,0 +1,78 @@
+import { makeValidator, type Validator } from './Validator.js'
+
+const isEmpty = (v: unknown): boolean => v === undefined || v === null || v === ''
+
+export function required(message = 'This field is required'): Validator {
+  return makeValidator(
+    v => (isEmpty(v) ? message : null),
+    { rule: 'required', message },
+  )
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+export function email(message = 'Must be a valid email'): Validator {
+  return makeValidator(
+    v => {
+      if (isEmpty(v)) return null
+      if (typeof v !== 'string' || !EMAIL_RE.test(v)) return message
+      return null
+    },
+    { rule: 'email', message },
+  )
+}
+
+export function minLength(n: number, message = `Must be at least ${n} characters`): Validator {
+  return makeValidator(
+    v => {
+      if (isEmpty(v)) return null
+      if (typeof v !== 'string') return null
+      return v.length < n ? message : null
+    },
+    { rule: 'minLength', value: n, message },
+  )
+}
+
+export function maxLength(n: number, message = `Must be at most ${n} characters`): Validator {
+  return makeValidator(
+    v => {
+      if (isEmpty(v)) return null
+      if (typeof v !== 'string') return null
+      return v.length > n ? message : null
+    },
+    { rule: 'maxLength', value: n, message },
+  )
+}
+
+export function min(n: number, message = `Must be at least ${n}`): Validator {
+  return makeValidator(
+    v => {
+      if (isEmpty(v)) return null
+      if (typeof v !== 'number') return null
+      return v < n ? message : null
+    },
+    { rule: 'min', value: n, message },
+  )
+}
+
+export function max(n: number, message = `Must be at most ${n}`): Validator {
+  return makeValidator(
+    v => {
+      if (isEmpty(v)) return null
+      if (typeof v !== 'number') return null
+      return v > n ? message : null
+    },
+    { rule: 'max', value: n, message },
+  )
+}
+
+export function pattern(regex: RegExp, message = 'Invalid format'): Validator {
+  return makeValidator(
+    v => {
+      if (isEmpty(v)) return null
+      if (typeof v !== 'string') return null
+      return regex.test(v) ? null : message
+    },
+    { rule: 'pattern', source: regex.source, flags: regex.flags, message },
+  )
+}