Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

33.2 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Typed fields: the schema, the defaults, and reading a page's values.
//
// AN ISSUE IS A PAGE. Its fields are `prop` BLOCKS on that page; the schema
// they draw on is `doc.fields`. docs/DECISIONS.md (2026-08-05) carries the
// reasoning; the parts that matter when reading this file:
//
//  · VALUES ARE BLOCKS because everything in spaces that matters iterates
//    `page.blocks` — search, find-and-replace, undo, the block registry, the
//    static preview, markdown export. A page-level key is invisible to all of
//    them and renders as nothing on a build that predates it. And under
//    collaboration each block property is its own last-writer-wins register, so
//    two people setting status and assignee at the same moment both win; one
//    object on the page would have been ONE register and would have lost an
//    edit silently.
//
//  · THE SCHEMA IS NOT A VALUE. Putting the status list on every issue would
//    copy it into every page and let two pages disagree about what "Todo"
//    means. It is document-level, and additive: a build that predates it
//    ignores `doc.fields` and still renders each prop block's `html`.
//
//  · EVERY PROP BLOCK CARRIES A READABLE `html`. That is what makes the format
//    degrade instead of vanish — an older build, a thumbnailer, a grep and a
//    markdown export all see "Status: In progress" without knowing what a field
//    is. Keeping it in step with `value` is this file's job.

import type { SpacesDoc, Page, Block } from './model'
// .ts extension: the model rig loads this file under node, whose resolver will
// not follow an extensionless import. Vite is unaffected — the same fix main
// already carries for i18n/packed.
import { t } from './i18n.ts'
import { buildTagIndex, pageHasTag } from './tags.ts'
import { passesClauses, clauseCount, type Clause } from './query.ts'

/** What a field holds. Deliberately few: every one costs an editor and a
 *  permanent commitment, and a tracker needs exactly these. */
export type FieldType = 'select' | 'person' | 'number' | 'date' | 'text' | 'labels'

/**
 * What each type is called to somebody choosing one. Keys are the model's
 * words and never translated; the labels are English source strings that t()
 * looks up at render time — never here, where they would freeze at import.
 */
/**
 * What each type is called to somebody choosing one.
 *
 * A FUNCTION with literal t() calls, not a map of English read back through
 * `t(MAP[key])`. The extractor sweeps LITERALS, so the map version compiled,
 * ran, and put five of these six words in no catalog at all — measured: Select,
 * Number, Date, Person and Labels were absent from packed.ts while eight locales
 * reported 100%, because the packer counts what it swept. `t()` at call time,
 * never in a module-level const, which would freeze at import.
 */
export function fieldTypeLabel(vt: FieldType): string {
  switch (vt) {
    case 'select': return t('Select')
    case 'number': return t('Number')
    case 'date': return t('Date')
    case 'person': return t('Person')
    case 'labels': return t('Labels')
    default: return t('Text')
  }
}

/** The types a new field can be, in the order the picker offers them. */
export const FIELD_TYPES: FieldType[] = ['text', 'select', 'number', 'date', 'person', 'labels']

export interface FieldOption {
  id: string
  label: string
  color?: string
  /**
   * Which end of the board this sits at.
   *
   * Linear's insight, and the reason a board is useful rather than pretty: a
   * status is not just a name, it belongs to a PHASE. "Done" and "Cancelled"
   * are both finished; "In review" and "In progress" are both started. Grouping
   * by phase is what lets "show me what is open" mean something without anyone
   * configuring a filter.
   */
  group?: 'unstarted' | 'started' | 'done' | 'cancelled'
}

export interface FieldSpec {
  key: string
  label: string
  vt: FieldType
  options?: FieldOption[]
  /** shown on a new issue when nothing is chosen */
  def?: string
}

/**
 * The fields a fresh tracker starts with.
 *
 * Linear-shaped on purpose: Status, Assignee, Priority, Estimate, Labels,
 * Cycle, Project. Opinionated beats configurable here — a tracker you have to
 * design before you can use it is the thing everybody hates about the
 * alternatives, and every one of these is permanent, so the list is short.
 */
export const DEFAULT_FIELDS: FieldSpec[] = [
  {
    key: 'status', label: 'Status', vt: 'select', def: 'todo',
    options: [
      { id: 'backlog', label: 'Backlog', color: '#8B95A5', group: 'unstarted' },
      { id: 'todo', label: 'Todo', color: '#5B8DEF', group: 'unstarted' },
      { id: 'doing', label: 'In progress', color: '#F7A600', group: 'started' },
      { id: 'review', label: 'In review', color: '#A97BE0', group: 'started' },
      { id: 'done', label: 'Done', color: '#2FA37C', group: 'done' },
      { id: 'cancelled', label: 'Cancelled', color: '#98A2B3', group: 'cancelled' },
    ],
  },
  {
    key: 'priority', label: 'Priority', vt: 'select', def: 'none',
    options: [
      { id: 'urgent', label: 'Urgent', color: '#E5484D' },
      { id: 'high', label: 'High', color: '#F7A600' },
      { id: 'medium', label: 'Medium', color: '#5B8DEF' },
      { id: 'low', label: 'Low', color: '#8B95A5' },
      { id: 'none', label: 'No priority', color: '#C4CBD6' },
    ],
  },
  { key: 'assignee', label: 'Assignee', vt: 'person' },
  { key: 'estimate', label: 'Estimate', vt: 'number' },
  { key: 'labels', label: 'Labels', vt: 'labels' },
  /**
   * START and DUE, in that order, because a schedule has two ends.
   *
   * `start` is NEW — the tracker shipped with `due` and nothing else, which is
   * enough for a deadline and not enough for a bar. Adding it is additive in
   * the ordinary way (a page that has never carried one has no `prop` block for
   * it, and absent still means unset), but it has one consequence worth naming
   * out loud rather than discovering:
   *
   *   EVERY ISSUE IN EVERY FILE ALREADY WRITTEN HAS A DUE DATE AND NO START.
   *
   * So "absent start" is not an edge case, it is the entire installed base, and
   * a Gantt that drew it as a zero-width bar would render every existing
   * tracker as a column of hairlines. It draws a MILESTONE DIAMOND at the due
   * date instead — a date with no duration, which is what the file actually
   * says. gantt.ts carries the rule at the site that implements it.
   *
   * Not in ISSUE_FIELDS: a new issue is seeded with status, priority, assignee
   * and estimate, and dates appear when somebody sets one — the same as `due`
   * has always behaved, and the same as `labels` and `project`.
   */
  { key: 'start', label: 'Start', vt: 'date' },
  { key: 'due', label: 'Due', vt: 'date' },
  { key: 'project', label: 'Project', vt: 'text' },
]

/**
 * The fields a NEW issue starts with.
 *
 * ONE list, because there are now two ways to make an issue — ⌘⇧I in the
 * editor and `bento.newIssue()` from an agent — and a field seeded by one but
 * not the other is a field a human then cannot set: `prop` is unlisted in the
 * / menu (blocks.ts), so the only way a value gets onto a page is that the page
 * was seeded with it. An agent-made issue missing `assignee` would be an issue
 * nobody can assign without hand-editing the JSON.
 *
 * The rest of the schema (labels, due, project) is set on demand and appears
 * when it is set — absent means unset, which is what the format already says.
 */
export const ISSUE_FIELDS = ['status', 'priority', 'assignee', 'estimate']

/** The schema in force: what the document declares, else the defaults. */
export function fieldsOf(doc: SpacesDoc): FieldSpec[] {
  const declared = (doc as { fields?: unknown }).fields
  return Array.isArray(declared) && declared.length ? (declared as FieldSpec[]) : DEFAULT_FIELDS
}

export const fieldByKey = (doc: SpacesDoc, key: string): FieldSpec | undefined =>
  fieldsOf(doc).find((f) => f.key === key)

export const optionOf = (f: FieldSpec | undefined, id: unknown): FieldOption | undefined =>
  f?.options?.find((o) => o.id === String(id))

/**
 * The readable form of a value — what goes in the block's `html`.
 *
 * Not decoration. This is the only thing an older build, a thumbnailer, a grep
 * or a markdown export can see, so it has to say what the field is as well as
 * what it holds.
 */
export function propHtml(f: FieldSpec, value: unknown): string {
  // COERCE, never assume. The schema comes out of a file someone sent you, so
  // `label` can be absent or a number — and this used to throw a TypeError
  // straight out of the public API (setField and newIssue), on exactly the
  // untrusted-file class the rest of the code is hardened against. A malformed
  // schema entry is something validate() reports; it is not something a write
  // verb should crash on. Falling back to the KEY keeps the readable form
  // readable, which is the whole job.
  const esc = (v: unknown) =>
    String(v ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
  const label = typeof f?.label === 'string' && f.label ? f.label : String(f?.key ?? 'field')
  const shown =
    f.vt === 'select' ? (optionOf(f, value)?.label ?? String(value ?? ''))
      : f.vt === 'labels' ? (Array.isArray(value) ? value.join(', ') : String(value ?? ''))
        : String(value ?? '')
  return `${esc(label)}: ${esc(shown) || '—'}`
}

/** A page's field values, by key. Only `prop` blocks carry them. */
export function valuesOf(page: Page): Map<string, unknown> {
  const out = new Map<string, unknown>()
  for (const b of page.blocks) {
    if (b.type !== 'prop') continue
    const key = (b as { key?: unknown }).key
    if (typeof key === 'string' && key) out.set(key, (b as { value?: unknown }).value)
  }
  return out
}

/**
 * Is this page an ISSUE?
 *
 * It carries a status. Not a flag on the page and not a separate page type:
 * making "issue" a mode would mean a page could be the wrong kind, and would
 * put a second concept in a format whose whole shape is "a page with blocks".
 * A page with a status is an issue; remove the status and it is a document
 * again, with everything else about it intact.
 */
export const isIssue = (page: Page): boolean =>
  page.blocks.some((b) => b.type === 'prop' && (b as { key?: unknown }).key === 'status')

/** Where a page's prop blocks stop and its body begins. */
export function headerLength(page: Page): number {
  let n = 0
  while (n < page.blocks.length && page.blocks[n].type === 'prop') n++
  return n
}

/**
 * What NARROWS a view. Stored on the `view` block, so it is permanent.
 *
 * ABSENT MEANS EVERYTHING, and so does an absent key inside it. That is not a
 * default, it is the compatibility rule: every view block written before
 * filters existed carries no `filter`, and must keep showing every issue
 * forever. The same rule makes the editor DELETE the key rather than store an
 * empty object, so a view someone filtered and then unfiltered is byte-identical
 * to one that was never filtered.
 *
 * It began as two keys, and that was the right size for a board: "show me this
 * label" and "show me what is still open". It was also the whole of what a view
 * could ask, on five layouts — so "books published after 2020", "tasks due this
 * week", "pages not tagged draft" and "title contains X" were all unexpressible.
 * `where` is the third key and the answer; its language, its operators and the
 * reasoning behind the shape live in query.ts, which is where a filter language
 * that grows should live rather than in the middle of the schema.
 *
 * The first two keys are UNCHANGED, in meaning and in combination: a file
 * written before `where` existed evaluates through exactly the code it always
 * did, and `any` narrows nothing but the new list.
 */
export interface ViewFilter {
  /**
   * field key → the values that pass. A value THIS BUILD DOES NOT KNOW is
   * compared literally, so a filter written by a newer build still selects the
   * issues it meant instead of matching nothing.
   */
  is?: Record<string, string[]>
  /** only issues whose phase is neither done nor cancelled */
  open?: boolean
  /** typed conditions — ranges, dates, text, absence. See query.ts. */
  where?: Clause[]
  /** the `where` list is ORed rather than ANDed. Reaches no other key. */
  any?: boolean
}

/** Filter keys this build can evaluate. */
const FILTER_KEYS = new Set(['is', 'open', 'where', 'any'])

/**
 * Filter keys from a NEWER build.
 *
 * They round-trip untouched, but this build cannot apply them, so the view
 * shows MORE than it should — and a count that is silently too high is exactly
 * the failure the format's additivity rule trades for. The view says so out
 * loud instead.
 */
export const unknownFilterKeys = (f: unknown): string[] =>
  f && typeof f === 'object' ? Object.keys(f).filter((k) => !FILTER_KEYS.has(k)) : []

/**
 * The field whose options declare PHASES — the one "open" is a question about.
 *
 * DERIVED FROM THE SCHEMA, never hardcoded to `status`: a document that
 * declares its own fields names its own phase field, and one that declares none
 * has no notion of open at all, in which case `open` passes everything rather
 * than emptying the board.
 */
export const phaseField = (doc: SpacesDoc): FieldSpec | undefined =>
  fieldsOf(doc).find((f) => f.options?.some((o) => o.group))

/**
 * Is this value a phase that is still going?
 *
 * An UNKNOWN value counts as open. A newer build's status must never be hidden
 * by "open only" — hiding work because this build cannot read its status is a
 * silent loss, and showing one issue too many is not.
 */
export const isOpenPhase = (f: FieldSpec | undefined, value: unknown): boolean => {
  const g = optionOf(f, value)?.group
  return g !== 'done' && g !== 'cancelled'
}

/**
 * Does one issue pass a view's filter?
 *
 * `page` and `today` are OPTIONAL and additive, in the same way the format is:
 * every existing call site keeps working and keeps answering what it answered.
 * `page` is what lets a condition ask about the title, which is not a prop
 * block and so is reachable through no field key; `today` is injected so a rig
 * is not at the mercy of a clock.
 */
export function passesFilter(
  doc: SpacesDoc, values: Map<string, unknown>, filter: unknown, page?: Page, today?: string,
): boolean {
  if (!filter || typeof filter !== 'object') return true
  const f = filter as ViewFilter
  if (f.open) {
    const pf = phaseField(doc)
    if (!isOpenPhase(pf, values.get(pf?.key ?? ''))) return false
  }
  const is = f.is
  if (is && typeof is === 'object') {
    for (const key of Object.keys(is)) {
      const want = is[key]
      // an empty list is NO CONSTRAINT, not "nothing passes" — a stored empty
      // would empty the board for a reason nobody could see
      if (!Array.isArray(want) || !want.length) continue
      const v = values.get(key)
      const mine = Array.isArray(v) ? v.map(String) : [String(v ?? '')]
      if (!want.some((w) => mine.includes(String(w)))) return false
    }
  }
  // The typed conditions are ANDed with everything above, whatever `any` says:
  // `any` was added with `where` and reaches only `where`. Making it reach `is`
  // or `open` would change what a file already on somebody's disk means.
  return passesClauses(doc, values, filter, page, today)
}

/** How many things a filter narrows by — what the Filter button counts. */
export const filterCount = (filter: unknown): number => {
  const f = (filter ?? {}) as ViewFilter
  const is = f.is && typeof f.is === 'object' ? f.is : {}
  return (f.open ? 1 : 0)
    + Object.keys(is).filter((k) => (is[k] ?? []).length).length
    // a half-built condition counts for nothing, exactly as an empty `is` list
    // does — the chip says how much the view is narrowed, not how many rows the
    // popover happens to be showing
    + clauseCount(filter)
}

/**
 * What ORDERS a view. Stored on the `view` block, so it is permanent.
 *
 * ABSENT MEANS MANUAL ORDER — the page order, which is the board's own order
 * and what every view written before this key carries. That is the
 * compatibility rule, not a preference: a stored sort must never appear on a
 * board somebody arranged by hand.
 *
 * AN ARRAY, though the editor only ever writes one entry. The shape was
 * published in the format sketch as a list, and a second key can be added later
 * without touching a file — where widening a scalar to an array afterwards
 * could not be done at all. One entry is what a board is actually asked for;
 * the array is what keeps the other answer available.
 */
export interface ViewSort {
  key: string
  /** absent = ascending, which is the direction a reader assumes */
  dir?: 'asc' | 'desc'
}

/** Sort keys this build can evaluate — a field the schema declares. */
export const unknownSortKeys = (doc: SpacesDoc, sort: unknown): string[] =>
  (Array.isArray(sort) ? sort : [])
    .map((s) => String((s as ViewSort)?.key ?? ''))
    .filter((k) => k && !fieldByKey(doc, k))

/**
 * One value's place in its field's order.
 *
 * A select sorts by its DECLARED position, never alphabetically: "Backlog,
 * Todo, In progress, Done" is a direction, and sorting it into "Backlog, Done,
 * In progress, Todo" throws away the one thing the list was telling you. A
 * number sorts numerically. Everything else compares as text.
 */
interface Rank { empty?: boolean; n?: number; s?: string }

function rank(f: FieldSpec | undefined, v: unknown): Rank {
  if (v === undefined || v === null || v === '' || (Array.isArray(v) && !v.length)) return { empty: true }
  if (f?.vt === 'select') {
    const at = f.options?.findIndex((o) => o.id === String(v)) ?? -1
    // a value from a NEWER build has no declared place. It sorts after
    // everything this build knows rather than at the top, because guessing it
    // belongs first is how a status nobody here can read ends up leading the
    // board.
    return { n: at < 0 ? Number.MAX_SAFE_INTEGER : at }
  }
  if (f?.vt === 'number') {
    const n = Number(v)
    return Number.isFinite(n) ? { n } : { s: String(v) }
  }
  return { s: Array.isArray(v) ? v.map(String).join(', ') : String(v) }
}

/**
 * Order rows by a view's `sort`. Returns the SAME array when there is nothing
 * to do, so an unsorted view keeps the page order it already had.
 *
 * AN UNSET VALUE IS ALWAYS LAST, in both directions. It is not the smallest
 * value, it is the absence of one — an issue with no estimate is not the
 * cheapest issue, and reversing the sort must not promote every blank to the
 * top of the board.
 */
export function sortRows(doc: SpacesDoc, rows: IssueRow[], sort: unknown): IssueRow[] {
  const keys: Array<{ f: FieldSpec; dir?: 'asc' | 'desc' }> = []
  for (const s of Array.isArray(sort) ? sort : []) {
    const f = fieldByKey(doc, String((s as ViewSort)?.key ?? ''))
    // a key this build does not know is skipped, never guessed at — the view
    // then shows the order it had, which is the honest fallback
    if (f) keys.push({ f, dir: (s as ViewSort)?.dir })
  }
  if (!keys.length) return rows

  // decorate-sort-undecorate: `rank` is called once per row per key rather than
  // once per comparison, which on a 500-issue board is the difference between
  // 500 lookups and ~4,500
  const decorated = rows.map((r, i) => ({ r, i, ranks: keys.map((k) => rank(k.f, r.values.get(k.f.key))) }))
  decorated.sort((a, bq) => {
    for (let j = 0; j < keys.length; j++) {
      const x = a.ranks[j], y = bq.ranks[j]
      if (x.empty || y.empty) {
        if (x.empty && y.empty) continue
        return x.empty ? 1 : -1
      }
      const d = x.n !== undefined && y.n !== undefined
        ? x.n - y.n
        : String(x.s ?? x.n).localeCompare(String(y.s ?? y.n), undefined, { numeric: true, sensitivity: 'base' })
      if (d) return keys[j].dir === 'desc' ? -d : d
    }
    // STABLE on ties: equal rows keep the page order, so a board sorted by
    // priority still reads in the order someone arranged it within each band.
    return a.i - bq.i
  })
  return decorated.map((d) => d.r)
}

export interface IssueRow {
  page: Page
  values: Map<string, unknown>
}

/** Every issue in the space, in page order, archived pages excluded. */
export function issuesOf(doc: SpacesDoc): IssueRow[] {
  const out: IssueRow[] = []
  for (const page of doc.pages) {
    if (page.archived || !isIssue(page)) continue
    out.push({ page, values: valuesOf(page) })
  }
  return out
}

/**
 * WHICH PAGES A VIEW IS ABOUT.
 *
 * A view used to mean one thing: every page carrying a `status`. That made the
 * tracker work and made everything else impossible — a space could hold a
 * backlog and never a reading list, because there was no way to say "the pages
 * with an Author" or "the pages under Books".
 *
 * ABSENT MEANS ISSUES, and that is the compatibility rule rather than a
 * default: every `view` block written before this existed carries no `source`
 * and must keep showing the backlog forever. The editor DELETES the key rather
 * than storing an empty object, so a view whose source was set and cleared is
 * byte-identical to one that never had it.
 *
 * Two selectors, and deliberately only two. `has` is the one that pairs with a
 * property somebody just invented — the vocabulary is flat and a page carries
 * only the fields it uses, so "has an Author" IS "is a book". `under` is the
 * one people reach for anyway, because nesting is how a space is already
 * organised. A selector language grows without limit and can never shrink:
 * every operator ships permanently into files on other people's disks.
 */
export interface ViewSource {
  /** pages carrying this field */
  has?: string
  /** pages nested anywhere under this page */
  under?: string
  /**
   * pages whose PROSE carries this `#tag` (or anything nested under it)
   *
   * The third selector, and it earns its place on the same test the other two
   * pass: it says something about a page that nothing else in this format can
   * say. `has` asks about a declared field, `under` about the tree — both are
   * structure somebody set up in advance. A tag is written mid-sentence, in
   * the middle of writing something else, which is the only kind of
   * classification most notes ever get.
   *
   * The KEY is stored, lower-cased — a filter that matched casing would break
   * the moment somebody wrote `#Recipe` once. Nested tags include their
   * children: `tag: 'project'` selects `#project/bento` too.
   */
  tag?: string
}

export const unknownSourceKeys = (src: unknown): string[] =>
  !src || typeof src !== 'object' ? []
    : Object.keys(src as Record<string, unknown>).filter((k) => k !== 'has' && k !== 'under' && k !== 'tag')

/** Is this page anywhere below `root`? Cycle-safe, like the tree walk. */
function isUnder(doc: SpacesDoc, page: Page, root: string): boolean {
  const seen = new Set<string>()
  let cur: string | undefined = page.parent
  while (cur && !seen.has(cur)) {
    if (cur === root) return true
    seen.add(cur)
    cur = doc.pages.find((p) => p.id === cur)?.parent
  }
  return false
}

/**
 * The rows a view holds.
 *
 * Derived every render from the pages themselves — never stored — for the same
 * reason the board's order is `doc.pages`: a database that keeps its own copy
 * of the rows is a database that disagrees with the document.
 */
export function viewRows(doc: SpacesDoc, source?: unknown): IssueRow[] {
  const src = (source && typeof source === 'object' ? source : {}) as ViewSource
  const has = typeof src.has === 'string' ? src.has : ''
  const under = typeof src.under === 'string' ? src.under : ''
  const tag = typeof src.tag === 'string' ? src.tag : ''
  if (!has && !under && !tag) return issuesOf(doc)

  // Derived here rather than passed in, so `viewRows` keeps the one-argument
  // shape every caller already has — including the node rigs, which have no
  // store to take an index from. Built ONLY when a tag is actually asked for.
  const tix = tag ? buildTagIndex(doc) : null

  const out: IssueRow[] = []
  for (const page of doc.pages) {
    if (page.archived) continue
    if (under && !isUnder(doc, page, under)) continue
    if (tix && !pageHasTag(tix, page.id, tag)) continue
    const values = valuesOf(page)
    if (has && !values.has(has)) continue
    out.push({ page, values })
  }
  return out
}

/** Where a dropped card lands: before a card, or after the last one. */
export interface DropAim { before?: string; after?: string }

/**
 * The page order after a card is dropped — or NULL when the drop changes
 * nothing.
 *
 * THE BOARD'S ORDER IS `doc.pages`. There is no per-view order field, and there
 * must not be one invented by a drag handler: a stored order is permanent, it
 * has to answer what happens to an issue no view has ever seen, and it can
 * disagree with the pages themselves. Reordering the pages cannot.
 *
 * Pure, and separate from the editor, because this is the arithmetic that is
 * easy to get wrong: the anchor is a page ID rather than an index precisely
 * because the index moves under the splice that removes the dragged page. The
 * null return is what keeps a drag that went nowhere out of the undo stack.
 */
export function reorderPages(pages: Page[], pageId: string, aim: DropAim): Page[] | null {
  const from = pages.findIndex((p) => p.id === pageId)
  const anchor = aim.before ?? aim.after
  if (from < 0 || !anchor) return null
  // already exactly there
  if (aim.before ? pages[from + 1]?.id === aim.before : pages[from - 1]?.id === aim.after) return null
  const next = pages.slice()
  const [moved] = next.splice(from, 1)
  // The anchor is looked up AFTER the removal, so the index is the one the
  // insert needs. It also covers dropping a card on itself: the anchor is the
  // page just removed, so it is not found and nothing moves.
  const at = next.findIndex((p) => p.id === anchor)
  if (at < 0) return null
  next.splice(aim.before ? at : at + 1, 0, moved)
  return next
}

/** One page's value block for a field, if it has one. */
export const propBlockOf = (page: Page, key: string): Block | undefined =>
  page.blocks.find((b) => b.type === 'prop' && (b as { key?: unknown }).key === key)

/** Build a prop block, with its readable form already in step. */
/**
 * The document's field vocabulary with one more field in it.
 *
 * SEEDS FROM THE DEFAULTS ON FIRST WRITE, and that is the whole reason this is
 * a function rather than a push. `fieldsOf` falls back to DEFAULT_FIELDS only
 * while `doc.fields` is absent or empty — so a document that has never declared
 * a schema and then gains ONE field would, if the field were simply pushed into
 * an empty array, lose Status, Priority, Assignee and Estimate in the same
 * stroke. Every issue in the space would keep its `prop` blocks (they carry
 * their own readable html) but the board grouping them by status would have no
 * status field to group by.
 *
 * So the first custom field writes the defaults down beside itself, which is
 * also the honest thing: once you have edited the schema it stops being
 * implicit.
 */
export function withField(doc: SpacesDoc, spec: FieldSpec): FieldSpec[] {
  const current = fieldsOf(doc)
  if (current.some((f) => f.key === spec.key)) {
    return current.map((f) => (f.key === spec.key ? spec : f))
  }
  return [...current, spec]
}

/**
 * A key for a field somebody just named.
 *
 * Keys are what `prop` blocks store and what views group by, so they outlive
 * every rename of the label and must never collide. Derived from the label,
 * then suffixed until it is free.
 */
export function freeFieldKey(doc: SpacesDoc, label: string): string {
  const base = label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'field'
  const taken = new Set(fieldsOf(doc).map((f) => f.key))
  if (!taken.has(base)) return base
  for (let n = 2; ; n++) if (!taken.has(`${base}-${n}`)) return `${base}-${n}`
}

export function propBlock(f: FieldSpec, value: unknown, id: string): Block {
  return { id, type: 'prop', key: f.key, value, html: propHtml(f, value) } as Block
}

/**
 * Would this drop change the order the user can actually SEE?
 *
 * `reorderPages` compares adjacency in `doc.pages`, and page order is not
 * column order: a board with two columns interleaves them, so a card dropped
 * back into its own slot is NOT adjacent to itself in the page array. Measured:
 * pages [board,i1,i2,i3,i4,i5] with i1,i3,i5 in one column — dropping i1 where
 * it already sat returned a reordered array, so a gesture that visibly did
 * nothing wrote to the document, took an undo entry, set the dirty flag, and
 * visibly reshuffled the SIDEBAR, because board order is sidebar order.
 *
 * The rig missed it because its fixture had one column, which is the only
 * shape where the two orders coincide.
 *
 * `cards` is the column's card ids in the order they are drawn, INCLUDING the
 * dragged one. The answer is about the column, because the column is the only
 * order the gesture was about.
 */
export function columnMoves(cards: string[], moved: string, aim: DropAim): boolean {
  const at = cards.indexOf(moved)
  if (at < 0) return true                       // it is arriving from elsewhere
  const rest = cards.filter((id) => id !== moved)
  const target = aim.before
    ? rest.indexOf(aim.before)
    : aim.after ? rest.indexOf(aim.after) + 1 : rest.length
  if (target < 0) return true
  const next = [...rest.slice(0, target), moved, ...rest.slice(target)]
  return next.join('\u001f') !== cards.join('\u001f')
}

/**
 * Which direction a view is sorted in BY THIS FIELD, if it is.
 *
 * Reads the same `sort` the format already carries — there is no second place
 * a table header's arrow could come from, and inventing one would let the arrow
 * and the order disagree. `undefined` means this column is not the sort key;
 * an entry with no `dir` is ascending, which is what absence has always meant.
 */
export const sortDirOf = (sort: unknown, key: string): 'asc' | 'desc' | undefined => {
  const cur = (Array.isArray(sort) ? sort : [])[0] as ViewSort | undefined
  if (!cur || String(cur.key ?? '') !== key) return undefined
  return cur.dir === 'desc' ? 'desc' : 'asc'
}

/**
 * The sort a CLICK ON A COLUMN HEADER produces: ascending → descending → none.
 *
 * The third state is the one that matters. A header that only flips between two
 * directions can never give a hand-arranged board its order back, and "manual
 * order" is not a sort called manual — it is the ABSENCE of the key. So this
 * returns `undefined` there, and the caller deletes the key rather than storing
 * an empty array: a view sorted and unsorted is byte-identical to one nobody
 * ever touched.
 */
export function cycleSort(sort: unknown, key: string): ViewSort[] | undefined {
  const dir = sortDirOf(sort, key)
  if (dir === undefined) return [{ key }]
  if (dir === 'asc') return [{ key, dir: 'desc' }]
  return undefined
}

/**
 * THE SHAPES A VIEW CAN TAKE, and the order the one button cycles them in.
 *
 * Written down ONCE. It used to live twice — a `NEXT` map in render.ts for the
 * button's label and a `next` map in editor.ts for what the click stores — and
 * the two drifted the way two copies of one fact always do. When the
 * prototype-lookup bug below was found, the fix was applied to the editor's
 * copy and not the renderer's, and the editor's comment then asserted the whole
 * thing was safe while the label it named was still being rendered from the
 * unguarded copy.
 *
 * `board` is the ABSENT key, never a stored 'board': a view cycled all the way
 * round is byte-identical to one nobody ever touched, which is the rule filter
 * and source already follow. `nextLayout` returns the word; the caller that
 * WRITES is the one that turns 'board' back into a deletion.
 */
/**
 * `gantt` and `workload` join the cycle rather than becoming a second block
 * type. The argument is in gantt.ts, at length, because every chart this app
 * grows after them inherits it. The half that belongs HERE is the one this
 * function already guarantees: `layoutOf` maps a word it does not know to
 * `board`, so a build that predates these two meets `layout:"gantt"`, draws a
 * board of the same pages, and writes the key back untouched.
 *
 * SEVEN IS THE CEILING FOR A CYCLE BUTTON. One control and one word beats a
 * menu at three or four; this branch argued six was already the limit, and the
 * maintainer ruled seven (calendar landed first, then these two). An EIGHTH
 * shape converts this control into a picker rather than extending the ring.
 * Written down here because the next person to add a layout will read this
 * line and not the changelog.
 */
export const VIEW_LAYOUTS = ['board', 'list', 'table', 'gallery', 'calendar', 'gantt', 'workload'] as const
export type ViewLayout = (typeof VIEW_LAYOUTS)[number]

/**
 * The layout a view is ACTUALLY in, whatever its block claims.
 *
 * `Object.hasOwn`, never a truthiness test or a bare `in`: a view block is
 * plain JSON in a file someone sent you, and `LAYOUT['toString']` on an object
 * literal is a native function — truthy, and stringifying to
 * `function toString() { [native code] }`, which is what the layout button
 * rendered as its own label. A key from a NEWER build lands on `board` rather
 * than nowhere, so the control is never a button that does nothing.
 */
export function layoutOf(raw: unknown): ViewLayout {
  const s = String(raw ?? 'board')
  return (VIEW_LAYOUTS as readonly string[]).includes(s) ? (s as ViewLayout) : 'board'
}

/** The next shape: board → list → table → gallery → calendar → gantt → workload → board. */
export function nextLayout(raw: unknown): ViewLayout {
  const here = layoutOf(raw)
  return VIEW_LAYOUTS[(VIEW_LAYOUTS.indexOf(here) + 1) % VIEW_LAYOUTS.length]
}