@stacksjs/defaults 0.75.231 → 0.75.236

package/functions/dashboard-list.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, it } from 'bun:test'
+import { pageControls, useRecordsDashboard } from './dashboard-list'
+
+/** The smallest thing with the two members `pageControls` reads. */
+function pageSignal(initial: number) {
+  let value = initial
+  const signal = (() => value) as { (): number, set: (next: number) => void }
+  signal.set = (next: number) => { value = next }
+  return signal
+}
+
+describe('pageControls', () => {
+  it('moves a page back and forward', () => {
+    const page = pageSignal(2)
+    const { previousPage, nextPage } = pageControls(page, () => 5)
+    previousPage()
+    expect(page()).toBe(1)
+    nextPage()
+    nextPage()
+    expect(page()).toBe(3)
+  })
+
+  it('will not go below the first page', () => {
+    const page = pageSignal(1)
+    const { previousPage } = pageControls(page, () => 5)
+    previousPage()
+    previousPage()
+    expect(page()).toBe(1)
+  })
+
+  it('will not go past the last page', () => {
+    const page = pageSignal(5)
+    const { nextPage } = pageControls(page, () => 5)
+    nextPage()
+    expect(page()).toBe(5)
+  })
+
+  it('reads the last page at click time, not when it was wired up', () => {
+    // A filter that shrinks the result set has to shrink the range too.
+    const page = pageSignal(1)
+    let last = 9
+    const { nextPage } = pageControls(page, () => last)
+    last = 2
+    nextPage()
+    nextPage()
+    nextPage()
+    expect(page()).toBe(2)
+  })
+
+  it('clamps an out-of-range page back into the range', () => {
+    // The guard style the Marketing dashboards used could not do this: a page
+    // already past the end stayed there.
+    const page = pageSignal(40)
+    const { nextPage, previousPage } = pageControls(page, () => 3)
+    nextPage()
+    expect(page()).toBe(3)
+    page.set(40)
+    previousPage()
+    expect(page()).toBe(39)
+  })
+
+  it('survives an empty result set, where the last page is zero', () => {
+    const page = pageSignal(1)
+    const { nextPage } = pageControls(page, () => 0)
+    nextPage()
+    expect(page()).toBe(1)
+  })
+})
+
+interface Row { id: number, name: string }
+
+const byName = (rows: Row[], query: string) => rows.filter(r => r.name.toLowerCase().includes(query))
+
+function seeded(count: number, perPage = 10) {
+  const d = useRecordsDashboard<Row>({ filter: byName, perPage })
+  d.records.set(Array.from({ length: count }, (_, i) => ({ id: i + 1, name: `row ${i + 1}` })))
+  return d
+}
+
+describe('useRecordsDashboard', () => {
+  it('starts loading, empty, on the first page', () => {
+    const d = useRecordsDashboard<Row>({ filter: byName })
+    expect(d.loading()).toBe(true)
+    expect(d.records()).toEqual([])
+    expect(d.page()).toBe(1)
+    expect(d.pageCount()).toBe(1)
+    expect(d.paginatedRecords()).toEqual([])
+  })
+
+  it('pages through the records', () => {
+    const d = seeded(25)
+    expect(d.pageCount()).toBe(3)
+    expect(d.paginatedRecords().map(r => r.id)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    d.nextPage()
+    expect(d.paginatedRecords()[0]!.id).toBe(11)
+    d.page.set(3)
+    expect(d.paginatedRecords()).toHaveLength(5)
+  })
+
+  it('searching returns to the first page, because page 3 of a new result set is meaningless', () => {
+    const d = seeded(25)
+    d.page.set(3)
+    d.handleSearch('row 1')
+    expect(d.page()).toBe(1)
+    // row 1, 10-19
+    expect(d.filteredRecords()).toHaveLength(11)
+  })
+
+  it('an edit replaces in place and does not move the page', () => {
+    const d = seeded(25)
+    d.page.set(2)
+    const target = d.records()[4]!
+    d.upsert({ id: target.id, name: 'renamed' }, target)
+    expect(d.records()[4]!.name).toBe('renamed')
+    expect(d.records()).toHaveLength(25)
+    expect(d.page()).toBe(2)
+  })
+
+  it('a create appends and lands on the page the new row is on', () => {
+    const d = seeded(20)
+    expect(d.pageCount()).toBe(2)
+    d.upsert({ id: 99, name: 'new' }, null)
+    expect(d.records()).toHaveLength(21)
+    expect(d.page()).toBe(3)
+    expect(d.paginatedRecords()).toEqual([{ id: 99, name: 'new' }])
+  })
+
+  it('removing the last row on the last page pulls the page back', () => {
+    const d = seeded(11)
+    d.page.set(2)
+    expect(d.paginatedRecords()).toHaveLength(1)
+    d.remove(d.records()[10]!)
+    expect(d.page()).toBe(1)
+    expect(d.records()).toHaveLength(10)
+  })
+
+  it('removing elsewhere leaves the page alone', () => {
+    const d = seeded(25)
+    d.page.set(2)
+    d.remove(d.records()[0]!)
+    expect(d.page()).toBe(2)
+    expect(d.records()).toHaveLength(24)
+  })
+
+  it('clampPage pulls a page back into range after a filter shrinks the list', () => {
+    const d = seeded(25)
+    d.page.set(3)
+    d.search.set('row 7')
+    d.clampPage()
+    expect(d.page()).toBe(1)
+  })
+
+  it('the editor opens for a create and for an edit, and remembers which', () => {
+    const d = seeded(3)
+    d.openCreate()
+    expect(d.editorOpen()).toBe(true)
+    expect(d.editorMode()).toBe('create')
+    expect(d.editing()).toBeNull()
+
+    const row = d.records()[1]!
+    d.openEdit(row)
+    expect(d.editorMode()).toBe('edit')
+    expect(d.editing()).toBe(row)
+  })
+
+  it('will not close the editor mid-save', () => {
+    // Otherwise a slow PATCH can land on a dialog the user already dismissed.
+    const d = seeded(3)
+    d.openEdit(d.records()[0]!)
+    d.editorError.set('something went wrong')
+    d.saving.set(true)
+    d.closeEditor()
+    expect(d.editorOpen()).toBe(true)
+    expect(d.editorError()).toBe('something went wrong')
+
+    d.saving.set(false)
+    d.closeEditor()
+    expect(d.editorOpen()).toBe(false)
+    expect(d.editing()).toBeNull()
+    expect(d.editorError()).toBe('')
+  })
+
+  it('will not close the delete confirmation mid-delete', () => {
+    const d = seeded(3)
+    d.requestDelete(d.records()[0]!)
+    d.deleteBusy.set(true)
+    d.closeDelete()
+    expect(d.deleting()).not.toBeNull()
+
+    d.deleteBusy.set(false)
+    d.closeDelete()
+    expect(d.deleting()).toBeNull()
+  })
+
+  it('honours a custom identity instead of id', () => {
+    const d = useRecordsDashboard<{ sku: string }>({
+      filter: rows => rows,
+      sameRecord: (a, b) => a.sku === b.sku,
+    })
+    d.records.set([{ sku: 'a' }, { sku: 'b' }])
+    d.remove({ sku: 'a' })
+    expect(d.records()).toEqual([{ sku: 'b' }])
+  })
+})
+
+describe('useRecordsDashboard goToPage', () => {
+  it('jumps to a page', () => {
+    const d = seeded(25)
+    d.goToPage(3)
+    expect(d.page()).toBe(3)
+  })
+
+  it('clamps a page that does not exist', () => {
+    const d = seeded(25)
+    d.goToPage(99)
+    expect(d.page()).toBe(3)
+    d.goToPage(0)
+    expect(d.page()).toBe(1)
+    d.goToPage(-4)
+    expect(d.page()).toBe(1)
+  })
+
+  it('survives a non-number from a component that emitted one', () => {
+    const d = seeded(25)
+    d.goToPage(Number.NaN)
+    expect(d.page()).toBe(1)
+  })
+})

package/functions/dashboard-list.ts

@@ -0,0 +1,257 @@
+import type { Signal } from '@stacksjs/stx'
+import { state } from '@stacksjs/stx'
+
+/**
+ * Shared pieces of the dashboard's list screens.
+ *
+ * Seventeen list dashboards each wrote their own `previousPage` and
+ * `nextPage` (stacksjs/stacks#2918), in four different styles. Twelve of them
+ * mean the same thing - move a page number, keep it between one and the last
+ * page - and this is that, once.
+ */
+
+/** The shape `state()` returns, narrowed to what paging needs. */
+interface PageSignal {
+  (): number
+  set: (value: number) => void
+}
+
+export interface PageControls {
+  /** Back one page, never past the first. */
+  previousPage: () => void
+  /** Forward one page, never past the last. */
+  nextPage: () => void
+}
+
+/**
+ * Previous and next for a page number bounded by a last page.
+ *
+ * `lastPage` is an accessor rather than a number because every call site
+ * derives it, and reading it at click time is what keeps the clamp correct
+ * when a filter shrinks the result set under the reader's feet.
+ *
+ * Clamps rather than guards. The twelve call sites split between
+ * `page.set(Math.max(1, page() - 1))` and `if (page() > 1) page.set(page() - 1)`,
+ * which do the same thing from a user's point of view; clamping is the one
+ * that stays correct if a page number is ever set out of range by something
+ * other than these two functions.
+ *
+ * Not for the dashboards that page server-side. `Jobs/JobHistory` reloads
+ * inside its `nextPage`, and a navigation that triggers a fetch is a
+ * different thing wearing the same name.
+ */
+export function pageControls(page: PageSignal, lastPage: () => number): PageControls {
+  return {
+    previousPage: () => page.set(Math.max(1, page() - 1)),
+    nextPage: () => page.set(Math.min(Math.max(1, lastPage()), page() + 1)),
+  }
+}
+
+/** How a list screen decides what the current search matches. */
+export interface RecordsDashboardOptions<T> {
+  /**
+   * Rows matching `query`, which arrives trimmed and lowercased.
+   *
+   * The caller's, because the fields worth searching are the only part of a
+   * list dashboard that is genuinely about its own records.
+   */
+  filter: (records: T[], query: string) => T[]
+  /** Rows per page. Default 10, which is what all five callers used. */
+  perPage?: number
+  /**
+   * Whether two rows are the same row. Defaults to matching `id`, which is
+   * what every current caller means.
+   */
+  sameRecord?: (a: T, b: T) => boolean
+}
+
+export interface RecordsDashboard<T> {
+  records: Signal<T[]>
+  loading: Signal<boolean>
+  loadError: Signal<string>
+  search: Signal<string>
+  page: Signal<number>
+  perPage: Signal<number>
+  editorOpen: Signal<boolean>
+  editorMode: Signal<'create' | 'edit'>
+  editing: Signal<T | null>
+  saving: Signal<boolean>
+  editorError: Signal<string>
+  deleting: Signal<T | null>
+  deleteBusy: Signal<boolean>
+  deleteError: Signal<string>
+  filteredRecords: () => T[]
+  paginatedRecords: () => T[]
+  pageCount: () => number
+  previousPage: () => void
+  nextPage: () => void
+  /**
+   * Jump to a page, clamped into range.
+   *
+   * The five callers each wrote a bare `page.set(value)` and trusted the
+   * pagination component to emit only pages that exist. Clamping costs
+   * nothing when that is true and keeps the list rendering when it is not.
+   */
+  goToPage: (value: number) => void
+  /** Set the search and return to the first page, which is the only sane page to land on. */
+  handleSearch: (value: string) => void
+  openCreate: () => void
+  openEdit: (record: T) => void
+  /** Refuses while a save is in flight, so a half-written row cannot be abandoned by accident. */
+  closeEditor: () => void
+  requestDelete: (record: T) => void
+  closeDelete: () => void
+  /**
+   * Put a saved row into the list.
+   *
+   * `replacing` is the row the editor was opened on, or null for a create.
+   * Passed rather than inferred so the behaviour matches what the five
+   * callers did: an edit replaces in place and a create appends and jumps to
+   * the page the new row landed on.
+   */
+  upsert: (record: T, replacing: T | null) => void
+  /** Drop a row and pull the page back if that emptied the last one. */
+  remove: (record: T) => void
+  /** Pull `page` back into range after the row count changes under it. */
+  clampPage: () => void
+}
+
+/**
+ * The state and lifecycle every list screen in the dashboard repeats.
+ *
+ * Five Delivery dashboards carried byte-identical copies of fourteen signals,
+ * `handleSearch`, `openCreate`, `openEdit`, `closeEditor`, `requestDelete`,
+ * `closeDelete`, and the page arithmetic around saving and deleting
+ * (stacksjs/stacks#2918). Five copies of an off-by-one is four chances to be
+ * right in four places and wrong in the fifth.
+ *
+ * Deliberately not here: fetching, toasts, and the search predicate. Those
+ * differ per screen, and a composable that owned them would be a framework
+ * each caller had to fight. The caller writes its own `load`, `save` and
+ * `delete`, and calls `upsert`, `remove` and `clampPage` from inside them.
+ */
+export function useRecordsDashboard<T>(options: RecordsDashboardOptions<T>): RecordsDashboard<T> {
+  const sameRecord = options.sameRecord
+    ?? ((a: T, b: T) => (a as { id?: unknown }).id === (b as { id?: unknown }).id)
+
+  const records = state<T[]>([])
+  const loading = state(true)
+  const loadError = state('')
+  const search = state('')
+  const page = state(1)
+  const perPage = state(options.perPage ?? 10)
+  const editorOpen = state(false)
+  const editorMode = state<'create' | 'edit'>('create')
+  const editing = state<T | null>(null)
+  const saving = state(false)
+  const editorError = state('')
+  const deleting = state<T | null>(null)
+  const deleteBusy = state(false)
+  const deleteError = state('')
+
+  const filteredRecords = (): T[] => {
+    const query = search().trim().toLowerCase()
+    return query ? options.filter(records(), query) : records()
+  }
+
+  const pageCount = (): number => Math.max(1, Math.ceil(filteredRecords().length / perPage()))
+
+  const paginatedRecords = (): T[] => {
+    const start = (page() - 1) * perPage()
+    return filteredRecords().slice(start, start + perPage())
+  }
+
+  const clampPage = (): void => {
+    const lastPage = pageCount()
+    if (page() > lastPage)
+      page.set(lastPage)
+  }
+
+  const { previousPage, nextPage } = pageControls(page, pageCount)
+
+  const goToPage = (value: number): void => {
+    page.set(Math.min(Math.max(1, Math.trunc(value) || 1), pageCount()))
+  }
+
+  return {
+    records,
+    loading,
+    loadError,
+    search,
+    page,
+    perPage,
+    editorOpen,
+    editorMode,
+    editing,
+    saving,
+    editorError,
+    deleting,
+    deleteBusy,
+    deleteError,
+    filteredRecords,
+    paginatedRecords,
+    pageCount,
+    previousPage,
+    nextPage,
+    goToPage,
+
+    handleSearch(value: string): void {
+      search.set(value)
+      page.set(1)
+    },
+
+    openCreate(): void {
+      editing.set(null)
+      editorMode.set('create')
+      editorError.set('')
+      editorOpen.set(true)
+    },
+
+    openEdit(record: T): void {
+      editing.set(record)
+      editorMode.set('edit')
+      editorError.set('')
+      editorOpen.set(true)
+    },
+
+    closeEditor(): void {
+      if (saving())
+        return
+      editorOpen.set(false)
+      editing.set(null)
+      editorError.set('')
+    },
+
+    requestDelete(record: T): void {
+      deleting.set(record)
+      deleteError.set('')
+    },
+
+    closeDelete(): void {
+      if (deleteBusy())
+        return
+      deleting.set(null)
+      deleteError.set('')
+    },
+
+    upsert(record: T, replacing: T | null): void {
+      if (replacing) {
+        records.set(records().map(existing => sameRecord(existing, replacing) ? record : existing))
+        return
+      }
+      const next = [...records(), record]
+      records.set(next)
+      // Land on the page the new row is actually on, not the last page of the
+      // filtered view: a create while a search is active would otherwise jump
+      // somewhere the row is not.
+      page.set(Math.max(1, Math.ceil(next.length / perPage())))
+    },
+
+    remove(record: T): void {
+      records.set(records().filter(existing => !sameRecord(existing, record)))
+      clampPage()
+    },
+
+    clampPage,
+  }
+}

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.231",
+  "version": "0.75.236",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.231",
+  "version": "0.75.236",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "0.75.231",
+    "@stacksjs/mobile": "0.75.236",
     "@stacksjs/sanitizer": "^0.2.534",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/project/storage/framework/types/browser-composables.d.ts

@@ -0,0 +1,56 @@
+// Hand-written, like `request-context.d.ts` beside it, and handed to
+// `stx typecheck` with `--lib` by the `typecheck:views` script.
+//
+// What a `<script client>` block can reach from stx's DEMAND-INLINE
+// composables (stacksjs/stacks#2918 follow-up). These are not ordinary
+// auto-imports: stx scans a client script for the names it calls and inlines
+// the implementation of just those, so they exist at runtime without an
+// import and are invisible to any checker that is only given the module
+// declarations. `node_modules/@stacksjs/stx/dist/composables/*.d.ts` declares
+// them as module exports, which is the wrong shape for a global, so nothing
+// typed them here.
+//
+// That is how `MembershipCard.stx` turned `typecheck:views` red while working
+// correctly in a browser: it calls `useMouse({ target, resetOnLeave })` and
+// subscribes, which is exactly the demand-inlined API, while the only
+// `useMouse` a checker could see was the unrelated no-argument one in
+// `browser-composables.d.ts`.
+//
+// Mirrors `dist/composables/use-mouse.d.ts` rather than inventing a shape. If
+// stx changes it, this drifts, and the symptom is a type error on code that
+// runs - so correct it here against that file rather than loosening it.
+
+export {}
+
+declare global {
+  interface StxMouseState {
+    x: number
+    y: number
+    pageX: number
+    pageY: number
+    clientX: number
+    clientY: number
+    movementX: number
+    movementY: number
+    buttons: number
+    isPressed: boolean
+    isInside: boolean
+  }
+
+  interface StxMouseOptions {
+    target?: Window | HTMLElement | null
+    touch?: boolean
+    resetOnLeave?: boolean
+    type?: 'page' | 'client' | 'screen' | 'movement'
+  }
+
+  interface StxMouseRef {
+    get: () => StxMouseState
+    /** Returns its own unsubscribe, which is what callers store. */
+    subscribe: (fn: (state: StxMouseState) => void) => () => void
+    stop: () => void
+  }
+
+  /** Reactive mouse or pointer position, globally or within a target. */
+  function useMouse(options?: StxMouseOptions): StxMouseRef
+}

package/resources/components/Dashboard/Auth/AuthCard.stx

@@ -0,0 +1,29 @@
+<script client>
+/**
+ * The centred card the signed-out auth pages sit in.
+ *
+ * Login, Register, ForgotPassword and ResetPassword each carried this
+ * markup (stacksjs/stacks#2917): the same full-height centring, the same
+ * 24rem column, the same logo tile, and the same heading pair. They differ
+ * only in what goes below it, which is the slot.
+ *
+ * Four pages the user moves between in one flow is the worst place for a
+ * shell to drift, because the drift is visible as a jump between steps.
+ */
+const title = useReactiveProp('title', '')
+const subtitle = useReactiveProp('subtitle', '')
+</script>
+
+<div class="flex items-center justify-center px-4 py-12 min-h-screen">
+  <div class="max-w-sm w-full">
+    <div class="mb-8 text-center">
+      <div class="inline-flex items-center justify-center mb-4 h-12 w-12 bg-gradient-to-br from-blue-500 to-blue-600 rounded-xl shadow-blue-500/25 shadow-lg">
+        <span class="h-7 w-7 text-white i-hugeicons-cube"></span>
+      </div>
+      <h1 class="font-semibold text-2xl text-neutral-900 dark:text-white">{{ title() }}</h1>
+      <p class="mt-2 text-neutral-500 text-sm dark:text-neutral-400">{{ subtitle() }}</p>
+    </div>
+
+    <slot />
+  </div>
+</div>