@pilotiq/pilotiq 0.6.2 → 0.7.0

package/src/schema/Wizard.ts

@@ -1,4 +1,19 @@
 import { Element } from './Element.js'
+import type { Action } from '../actions/Action.js'
+
+/**
+ * Customizer for the wizard's built-in nav buttons (`submitAction`,
+ * `nextAction`, `previousAction`). Pass an `Action` to replace the
+ * default outright, or a function that receives the framework-built
+ * default and returns a customized clone.
+ *
+ * Only chrome carries through to the renderer (label / icon / color /
+ * size / outlined / iconOnly / tooltip / disabled rules). The button's
+ * click behavior stays hardwired to advance / recede / submit-form —
+ * dispatch overrides (`.handler()`, `.action()`, `.href()`) are
+ * intentionally ignored so the wizard chrome never breaks navigation.
+ */
+export type WizardActionCustomizer = Action | ((defaultAction: Action) => Action)
 
 /**
  * Context handed to `Step.beforeValidation` / `afterValidation` hooks.
@@ -108,6 +123,10 @@ export class Wizard extends Element {
   private _skippable = false
   private _startOnStep = 0
   private _persist = true
+  private _persistStepInQueryString: string | undefined = undefined
+  private _submitAction?:   WizardActionCustomizer
+  private _nextAction?:     WizardActionCustomizer
+  private _previousAction?: WizardActionCustomizer
 
   private constructor() { super() }
 
@@ -140,6 +159,51 @@ export class Wizard extends Element {
    */
   persist(v: boolean): this { this._persist = v; return this }
 
+  /**
+   * Sync the active step index to the URL as `?<key>=N` (1-based for
+   * human-friendly URLs). When set, the URL value wins over localStorage
+   * on initial mount, so deep-linking to a specific step works. Bare
+   * `persistStepInQueryString()` uses the default key `'step'`; pass a
+   * string to override (multi-wizard pages should use distinct keys to
+   * avoid collisions). Pass `false` to disable.
+   */
+  persistStepInQueryString(key: string | boolean = true): this {
+    if (key === false) { this._persistStepInQueryString = undefined; return this }
+    this._persistStepInQueryString = key === true ? 'step' : key
+    return this
+  }
+
+  /**
+   * Customize the chrome of the built-in Submit button shown on the
+   * wizard's final step. By default the wizard renders a hint pointing
+   * at the surrounding form's Save button — calling this method instead
+   * mounts a real `<button type="submit">` inside the wizard chrome so
+   * the wizard becomes self-contained. Pair with `CreatePage.getFormActions(R)`
+   * returning `[]` to suppress the page-level Save when you don't want
+   * two submits on the same page.
+   */
+  submitAction(action: WizardActionCustomizer): this {
+    this._submitAction = action
+    return this
+  }
+
+  /** Customize the chrome of the built-in Next button. */
+  nextAction(action: WizardActionCustomizer): this {
+    this._nextAction = action
+    return this
+  }
+
+  /** Customize the chrome of the built-in Back / Previous button. */
+  previousAction(action: WizardActionCustomizer): this {
+    this._previousAction = action
+    return this
+  }
+
+  getPersistStepInQueryString(): string | undefined { return this._persistStepInQueryString }
+  getSubmitAction():             WizardActionCustomizer | undefined { return this._submitAction }
+  getNextAction():               WizardActionCustomizer | undefined { return this._nextAction }
+  getPreviousAction():           WizardActionCustomizer | undefined { return this._previousAction }
+
   getType(): string { return 'wizard' }
 
   toMeta(): Record<string, unknown> {
@@ -148,6 +212,9 @@ export class Wizard extends Element {
       skippable:   this._skippable,
       startOnStep: this._startOnStep,
       persist:     this._persist,
+      ...(this._persistStepInQueryString
+        ? { persistStepInQueryString: this._persistStepInQueryString }
+        : {}),
     }
   }
 }

package/src/schema/containers.test.ts

@@ -427,6 +427,96 @@ describe('Wizard / Step (Plan #8)', () => {
     })
   })
 
+  describe('persistStepInQueryString', () => {
+    it('omits the meta key by default', async () => {
+      const tree = [Wizard.make().steps([Step.make('a').schema([])])]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!['persistStepInQueryString'], undefined)
+    })
+
+    it('bare call defaults to "step"', async () => {
+      const tree = [
+        Wizard.make().persistStepInQueryString().steps([Step.make('a').schema([])]),
+      ]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!['persistStepInQueryString'], 'step')
+    })
+
+    it('explicit string overrides the key', async () => {
+      const tree = [
+        Wizard.make().persistStepInQueryString('checkout').steps([Step.make('a').schema([])]),
+      ]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!['persistStepInQueryString'], 'checkout')
+    })
+
+    it('false clears a previously-set key', async () => {
+      const tree = [
+        Wizard.make().persistStepInQueryString('foo').persistStepInQueryString(false)
+          .steps([Step.make('a').schema([])]),
+      ]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!['persistStepInQueryString'], undefined)
+    })
+  })
+
+  describe('submitAction / nextAction / previousAction customizers', () => {
+    it('omits the meta keys when no customizer is set', async () => {
+      const tree = [Wizard.make().steps([Step.make('a').schema([])])]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!['submitAction'],   undefined)
+      assert.equal(result[0]!['nextAction'],     undefined)
+      assert.equal(result[0]!['previousAction'], undefined)
+    })
+
+    it('customizer receives a default Action with sensible chrome', async () => {
+      let receivedSubmit:   string | undefined
+      let receivedNext:     string | undefined
+      let receivedPrevious: string | undefined
+      const tree = [
+        Wizard.make()
+          .submitAction(a => { receivedSubmit = a.getLabel(); return a })
+          .nextAction(a => { receivedNext = a.getLabel(); return a })
+          .previousAction(a => { receivedPrevious = a.getLabel(); return a })
+          .steps([Step.make('a').schema([])]),
+      ]
+      await resolveSchema(tree)
+      assert.equal(receivedSubmit,   'Submit')
+      assert.equal(receivedNext,     'Next')
+      assert.equal(receivedPrevious, 'Back')
+    })
+
+    it('customizer chrome flows through to the resolved meta', async () => {
+      const tree = [
+        Wizard.make()
+          .submitAction(a => a.label('Create campaign').size('lg'))
+          .nextAction(a => a.label('Continue').icon('arrow-right'))
+          .previousAction(Action.make('back').label('Go back').color('ghost'))
+          .steps([Step.make('a').schema([])]),
+      ]
+      const result = await resolveSchema(tree)
+      const submit   = result[0]!['submitAction']   as Record<string, unknown>
+      const next     = result[0]!['nextAction']     as Record<string, unknown>
+      const previous = result[0]!['previousAction'] as Record<string, unknown>
+      assert.equal(submit['label'], 'Create campaign')
+      assert.equal(submit['size'],  'lg')
+      assert.equal(next['label'],   'Continue')
+      assert.equal(next['icon'],    'arrow-right')
+      assert.equal(previous['label'], 'Go back')
+      assert.equal(previous['color'], 'ghost')
+    })
+
+    it('customizer that hides the action drops the slot from meta', async () => {
+      const tree = [
+        Wizard.make()
+          .nextAction(a => a.visible(false))
+          .steps([Step.make('a').schema([])]),
+      ]
+      const result = await resolveSchema(tree)
+      assert.equal(result[0]!['nextAction'], undefined)
+    })
+  })
+
   it('all step children resolve so cross-step $get works', async () => {
     // Step 2 has a Section that hides based on a value entered in Step 0;
     // both steps must be resolved on every cycle for the predicate to fire.

package/src/schema/resolveSchema.test.ts

@@ -10,6 +10,9 @@ import {
 import { Text } from './Text.js'
 import { Heading } from './Heading.js'
 import { Card } from './Card.js'
+import { Section } from './Section.js'
+import { Form } from '../elements/Form.js'
+import { TextField } from '../fields/TextField.js'
 
 beforeEach(() => _resetResolverRegistry())
 
@@ -326,4 +329,51 @@ describe('resolveSchema', () => {
       assert.equal(result[0]!._layout, undefined)
     })
   })
+
+  describe('inlineLabel cascade (Form / Section)', () => {
+    it('Form.inlineLabel(true) cascades to descendant fields', async () => {
+      const tree = [Form.make().inlineLabel().schema([TextField.make('a'), TextField.make('b')])]
+      const [form] = await resolveSchema(tree)
+      const [a, b] = form!.children! as ElementMeta[]
+      assert.equal((a as { inlineLabel?: boolean }).inlineLabel, true)
+      assert.equal((b as { inlineLabel?: boolean }).inlineLabel, true)
+    })
+
+    it('Field.inlineLabel(false) overrides the Form cascade', async () => {
+      const tree = [Form.make().inlineLabel().schema([
+        TextField.make('a'),
+        TextField.make('b').inlineLabel(false),
+      ])]
+      const [form] = await resolveSchema(tree)
+      const [a, b] = form!.children! as ElementMeta[]
+      assert.equal((a as { inlineLabel?: boolean }).inlineLabel, true)
+      assert.equal('inlineLabel' in (b as object), false)
+    })
+
+    it('nested Section.inlineLabel(false) overrides the Form cascade for its subtree', async () => {
+      const tree = [Form.make().inlineLabel().schema([
+        TextField.make('above'),
+        Section.make('inner').inlineLabel(false).schema([TextField.make('inside')]),
+      ])]
+      const [form] = await resolveSchema(tree)
+      const [above, section] = form!.children! as ElementMeta[]
+      const [inside] = (section as ElementMeta).children! as ElementMeta[]
+      assert.equal((above as { inlineLabel?: boolean }).inlineLabel, true)
+      assert.equal('inlineLabel' in (inside as object), false)
+    })
+
+    it('Section.inlineLabel(true) cascades without an outer Form', async () => {
+      const tree = [Section.make('s').inlineLabel().schema([TextField.make('a')])]
+      const [section] = await resolveSchema(tree)
+      const [a] = section!.children! as ElementMeta[]
+      assert.equal((a as { inlineLabel?: boolean }).inlineLabel, true)
+    })
+
+    it('default (no setter calls) emits no inlineLabel anywhere', async () => {
+      const tree = [Form.make().schema([TextField.make('a')])]
+      const [form] = await resolveSchema(tree)
+      const [a] = form!.children! as ElementMeta[]
+      assert.equal('inlineLabel' in (a as object), false)
+    })
+  })
 })

package/src/schema/resolveSchema.ts

@@ -22,7 +22,9 @@ import {
   type RepeatableEntryRowMeta,
 } from '../entries/RepeatableEntry.js'
 import { Section } from './Section.js'
+import { Wizard, type WizardActionCustomizer } from './Wizard.js'
 import { TextField } from '../fields/TextField.js'
+import { Form } from '../elements/Form.js'
 
 export interface SchemaContext {
   user?: { name?: string; email?: string; [key: string]: unknown }
@@ -113,6 +115,14 @@ export interface RenderContext extends SchemaContext {
      */
     blockType?: string
   }
+  /**
+   * Cascading `inlineLabel` default set by an ancestor `Form` or
+   * `Section` via `.inlineLabel(true)`. Read by `Field.buildMeta` when the
+   * field hasn't called `inlineLabel()` itself; explicit field-level
+   * setting always wins. A nested container's `.inlineLabel(false)`
+   * overrides an outer container's `.inlineLabel(true)` for its subtree.
+   */
+  inlineLabelDefault?: boolean
 }
 
 export type SchemaDefinition =
@@ -305,9 +315,15 @@ async function resolveOne(el: Element, ctx: RenderContext): Promise<ElementMeta
     return meta
   }
 
+  // Push `inlineLabelDefault` into the child ctx when this element is a
+  // `Form` or `Section` whose `.inlineLabel(...)` was set. Children inherit
+  // until another container resets the flag. Field-level `inlineLabel(...)`
+  // calls always win on read (see `Field.buildMeta`).
+  const childCtx = deriveChildContext(el, ctx)
+
   const children = el.getChildren()
   if (children && children.length > 0) {
-    meta.children = await resolveAll(children, ctx)
+    meta.children = await resolveAll(children, childCtx)
   }
 
   // Filament v5 — `Section.afterHeader([Action…])` resolves through the
@@ -335,6 +351,30 @@ async function resolveOne(el: Element, ctx: RenderContext): Promise<ElementMeta
     }
   }
 
+  // `Wizard.submitAction() / nextAction() / previousAction()` — build a
+  // framework default Action for each slot, run the user's customizer
+  // (or take the explicit Action), then resolve through the standard
+  // walker so `.visible() / .disabled()` rules evaluate the same way
+  // as anywhere else. Stamped under `meta.submitAction / nextAction /
+  // previousAction`; sparse — absent when the user hasn't customized.
+  if (el instanceof Wizard) {
+    const submitC   = el.getSubmitAction()
+    const nextC     = el.getNextAction()
+    const previousC = el.getPreviousAction()
+    if (submitC) {
+      const [resolved] = await resolveAll([resolveWizardAction(submitC, 'submit')], ctx)
+      if (resolved) meta['submitAction'] = resolved
+    }
+    if (nextC) {
+      const [resolved] = await resolveAll([resolveWizardAction(nextC, 'next')], ctx)
+      if (resolved) meta['nextAction'] = resolved
+    }
+    if (previousC) {
+      const [resolved] = await resolveAll([resolveWizardAction(previousC, 'previous')], ctx)
+      if (resolved) meta['previousAction'] = resolved
+    }
+  }
+
   // `TextField.prefixAction(Action) / suffixAction(Action)` — resolve the
   // bound Actions through `resolveAll` so visibility / disabled rules
   // evaluate the same way as anywhere else. Hidden Actions are dropped
@@ -827,6 +867,23 @@ async function evalItemCan(
  * Mirrors the `Field.buildConditionContext` shape so layout `visible(fn)`
  * callbacks can destructure the same way as `Field.showWhen` callbacks.
  */
+/**
+ * Resolve a `WizardActionCustomizer` against the framework default for
+ * the given slot. The default carries a stable `name` (`wizardSubmit /
+ * wizardNext / wizardPrevious`) and sensible chrome — the customizer
+ * may pass through verbatim, mutate, or replace entirely. Returned
+ * `Action` is then resolved through the standard walker so visibility
+ * and disabled rules evaluate the same way as any other Action.
+ */
+function resolveWizardAction(customizer: WizardActionCustomizer, slot: 'submit' | 'next' | 'previous'): Action {
+  const def = slot === 'submit'
+    ? Action.make('wizardSubmit').label('Submit').color('primary')
+    : slot === 'next'
+      ? Action.make('wizardNext').label('Next').color('primary')
+      : Action.make('wizardPrevious').label('Back').color('ghost')
+  return typeof customizer === 'function' ? customizer(def) : customizer
+}
+
 function buildLayoutContext(ctx: RenderContext): LayoutContext {
   const out: LayoutContext = {}
   if (ctx.record !== undefined) out.record = ctx.record
@@ -837,3 +894,24 @@ function buildLayoutContext(ctx: RenderContext): LayoutContext {
   if (ctx.row   !== undefined) out.row   = ctx.row
   return out
 }
+
+/**
+ * Derive the render context that this element's children should see.
+ * Currently only handles the `inlineLabelDefault` cascade — `Form` /
+ * `Section` with `.inlineLabel(true|false)` push the value into the
+ * descendant context so every nested `Field.buildMeta` can read it.
+ * A nested container that re-sets the flag overrides the outer value
+ * for its subtree (the current ctx's value is replaced, not merged).
+ *
+ * Returns the same `ctx` reference when nothing needs to change so
+ * call sites that pass it down skip a fresh object allocation.
+ */
+function deriveChildContext(el: Element, ctx: RenderContext): RenderContext {
+  if (el instanceof Form || el instanceof Section) {
+    const v = (el as Form | Section).getInlineLabel?.()
+    if (v !== undefined && v !== ctx.inlineLabelDefault) {
+      return { ...ctx, inlineLabelDefault: v }
+    }
+  }
+  return ctx
+}

package/src/sessionFilters.test.ts

@@ -104,6 +104,29 @@ describe('writePersistedListQuery', () => {
     assert.deepEqual(session.data[key], { orders_status: 'draft' })
   })
 
+  it('skips groupKey (drill-in is page-state, not filter-state)', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, {
+      status:   'draft',
+      groupKey: 'archive-2025',
+    })
+    assert.deepEqual(session.data[key], { status: 'draft' })
+  })
+
+  it('skips Tier-3 prefixed groupKey keys', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, {
+      orders_status:   'draft',
+      orders_groupKey: 'old',
+      groupKey:        'older',  // bare also dropped
+    })
+    assert.deepEqual(session.data[key], { orders_status: 'draft' })
+  })
+
   it('preserves empty-string values (explicit-clear marker)', () => {
     const session = makeSession()
     const req = { session }

package/src/sessionFilters.ts

@@ -4,7 +4,7 @@
 
 const PREFIX = 'pilotiq:filters:'
 
-const EXCLUDED_KEYS = new Set(['page', 'tab'])
+const EXCLUDED_KEYS = new Set(['page', 'tab', 'groupKey'])
 
 // Heuristic also catches `<prefix>_page` from `Table.queryStringIdentifier`.
 // A filter literally named `something_page` would be dropped too, but
@@ -14,6 +14,15 @@ function isPageKey(key: string): boolean {
   return key.endsWith('_page')
 }
 
+// Sibling heuristic for `<prefix>_groupKey`. Group drill-in is page-
+// state (click-to-drill, × to clear), not filter-state — restoring it
+// on a bare visit would land the user on the bucket they last drilled
+// into instead of the banded list they probably expect.
+function isGroupKeyKey(key: string): boolean {
+  if (key === 'groupKey') return true
+  return key.endsWith('_groupKey')
+}
+
 interface StorableSession {
   get<T>(key: string, fallback?: T): T | undefined
   put(key: string, value: unknown): void
@@ -73,6 +82,7 @@ export function writePersistedListQuery(
   for (const [k, v] of Object.entries(query)) {
     if (EXCLUDED_KEYS.has(k)) continue
     if (isPageKey(k))         continue
+    if (isGroupKeyKey(k))     continue
     if (typeof v !== 'string') continue
     slice[k] = v
   }

package/src/styles/file-upload.css

@@ -0,0 +1,13 @@
+/* Stylesheet for `FileUploadField`'s image-cropping affordance.
+ *
+ * `react-image-crop` is a declared dep of `@pilotiq/pilotiq` and its
+ * CSS is required for the crop UI to render correctly. Consumers
+ * pull in the styles by importing this subpath from their app's CSS
+ * (Tailwind / global stylesheet):
+ *
+ *   @import "@pilotiq/pilotiq/styles/file-upload.css";
+ *
+ * Importing through this subpath means consumers don't need to
+ * declare `react-image-crop` as a direct dep — the CSS @import below
+ * resolves through pilotiq's own node_modules. */
+@import "react-image-crop/dist/ReactCrop.css";

package/src/vite.ts

@@ -632,6 +632,7 @@ export function clusterOffset(parts: string[]): number {
   lines.push('const _all: Record<string, unknown> = {}')
   lines.push('const _clusters: Record<string, string[]> = {}')
   lines.push('const _rightPanels: Record<string, unknown> = {}')
+  lines.push('const _layoutProviders: unknown[] = []')
   lines.push('function _add(c: any) { if (typeof c === \'function\' && c.name) _all[c.name] = c }')
   lines.push('function _walk(p: any) {')
   lines.push('  const cfg = p?.getConfig?.()')
@@ -643,6 +644,11 @@ export function clusterOffset(parts: string[]): number {
   lines.push('      if (_c && typeof _c.id === \'string\' && _c.render) _rightPanels[_c.id] = _c.render')
   lines.push('    }')
   lines.push('  }')
+  lines.push('  if (Array.isArray(cfg?.layoutProviders)) {')
+  lines.push('    for (const _C of cfg.layoutProviders) {')
+  lines.push('      if (typeof _C === \'function\') _layoutProviders.push(_C)')
+  lines.push('    }')
+  lines.push('  }')
   lines.push('  if (cfg?.path && Array.isArray(cfg?.clusters)) {')
   lines.push('    const slugs = cfg.clusters.map((C: any) => (typeof C?.getSlug === \'function\' ? C.getSlug() : \'\')).filter(Boolean)')
   lines.push('    if (slugs.length > 0) _clusters[cfg.path] = slugs')
@@ -653,6 +659,7 @@ export function clusterOffset(parts: string[]): number {
   lines.push('export const componentRegistry: Record<string, unknown> = _all')
   lines.push('export const clusterSlugsByBasePath: Record<string, string[]> = _clusters')
   lines.push('export const rightPanelRegistry: Record<string, unknown> = _rightPanels')
+  lines.push('export const layoutProviderRegistry: unknown[] = _layoutProviders')
   lines.push('')
 
   writeIfChanged(path.join(outDir, '_components.ts'), lines.join('\n'))
@@ -668,7 +675,7 @@ function writeLayoutWithManifest(pagesRoot: string): void {
 import { usePageContext } from 'vike-react/usePageContext'
 import { AppShell, ThemeProvider, generateThemeCSS, NavigateProvider } from '@pilotiq/pilotiq/react'
 import { navigate as vikeNavigate } from 'vike/client/router'
-import { componentRegistry, rightPanelRegistry } from './_components.js'
+import { componentRegistry, rightPanelRegistry, layoutProviderRegistry } from './_components.js'
 import type { ReactNode } from 'react'
 
 // Wrap vike's async navigate so the NavigateProvider's fire-and-forget
@@ -691,7 +698,7 @@ export default function PilotiqLayout({ children }: { children: ReactNode }) {
     <NavigateProvider navigate={navigate}>
       <ThemeProvider theme={panel.theme}>
         {themeCss && <style dangerouslySetInnerHTML={{ __html: themeCss }} />}
-        <AppShell panel={panel} basePath={basePath} layout={layout} notifications={notifications} currentPath={currentPath} componentRegistry={componentRegistry as any} rightPanelRegistry={rightPanelRegistry as any}>
+        <AppShell panel={panel} basePath={basePath} layout={layout} notifications={notifications} currentPath={currentPath} componentRegistry={componentRegistry as any} rightPanelRegistry={rightPanelRegistry as any} layoutProviderRegistry={layoutProviderRegistry as any}>
           {children}
         </AppShell>
       </ThemeProvider>