rzen/lanework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

A reserved key comes to life — the card window's sidebar grows a Labels section, and labels stops being somebody else's

Browse Source 
`labels` has been a reserved tracker key since the rewrite: preserved verbatim, never
interpreted, drawn only as an anonymous row in the Details section beside `assignees` and
`due`. The owner's cards claim it for first-party use, so it joins the schema — read
leniently (a list of names, a bare scalar coercing to one, a mapping malformed and
preserved), written canonically (a quoted flow list in the order the user arranged, no
auto-sort), and removed outright when the last label goes, the way an expanded lane drops
`collapsed`.

Identity is case-insensitive and display is case-preserving, so a card carries `bug` once
however many ways the board spells it, and entries the reading cannot name ride through the
write untouched at the tail.

The section sits second, above Details — which is the point rather than a layout preference:
Details is where keys the app does *not* own are shown, and this key just stopped being one.
Rows rather than chips, because the sidebar is twenty-six characters wide. The add field
autocompletes against the board's own used-labels universe, derived from every live and
trashed card with no store beside the files, and says out loud when Return would mint a word
the board has never used.

Writes ride a `.relabel` operation of their own, because the commit composer has said
"Relabel card 'X'" since long before there was a control to press — and now the undo row says
it too.

Claude-Session: https://claude.ai/code/session_014PtZdPwqZuqEDLc6wZMtEy
This commit is contained in:
rzen
2026-08-09 12:06:01 -04:00
parent fd31ed24f4
commit da37ed61bf
24 changed files with 1928 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Kanban/LiveStore/LabelIndex.swift
+205
View File
@@ -0,0 +1,205 @@
import Foundation
// MARK: - One label's standing on a board
/// One label the board actually uses, and how many cards use it.
public struct LabelTally: Sendable, Equatable {
/// The label as it is **spelled on the board** — the first spelling the derivation met, in board
/// order (lanes left to right, each lane's cards top to bottom, then the trash).
///
/// Case-insensitive uniqueness is a per-*card* rule (`CardLabels`), so two cards may perfectly
/// legally spell one label two ways. The universe has to pick one to offer, and the first is the
/// only choice that does not depend on how many cards happen to carry each variant — a count-based
/// pick would make a menu row's capitalisation flicker as cards are tagged.
public let name: String
/// How many **cards** carry it — never how many times it appears, which is the same number: a
/// card's own list is deduplicated by the reading.
public let count: Int
public init(name: String, count: Int) {
self.name = name
self.count = count
}
}
// MARK: - The universe
/// **Every label the board uses, with its frequency** — the "used labels" universe both label
/// surfaces draw from (the sidebar's autocomplete and the context menu's twelve rows plus its More…
/// dialog).
///
/// ### Derived from the snapshot, and there is no other store
///
/// The owner's ruling, and the format's own posture: the files *are* the board, so the set of labels
/// in use is a fact about the cards rather than a list the app maintains beside them. A label exists
/// because a card carries it and stops existing when the last card drops it — there is no rename, no
/// palette, no orphan to garbage-collect, and an agent that hand-writes `labels: [spike]` into an
/// `index.md` has created a label as fully as the menu can.
///
/// **The trash counts.** `BoardModel.trash` is walked beside `lanes` because a trashed card is "an
/// ordinary card in a special place" (03-board-ui.md § Trash) and, more to the point, because the
/// alternative is worse: deleting the only card carrying `spike` would silently evict the label from
/// the autocomplete, and restoring the card would bring it back — a vocabulary that flickers with the
/// trash is not a vocabulary. `trashedLanes` is deliberately *not* walked: a trashed lane is an opaque
/// unit whose cards the snapshot never loads (`TrashedLane`), so there is nothing there to count.
///
/// ### Cost
///
/// One pass over every live and trashed card, reading a field the loader already parsed — the same
/// cost class as any other whole-board derivation, and paid **once per snapshot** (`BoardStore`
/// caches it, equality-gated) rather than once per view body. That is what keeps the context menu's
/// builder free of O(board) work: everything a card face reads is this value, already built.
public struct LabelIndex: Sendable, Equatable {
/// Every used label, **ordered by frequency descending, then case-insensitively alphabetically**
/// — a total, snapshot-only order, so two runs over the same board produce the identical array.
///
/// The alphabetical tie-break is here rather than left to the ranking because this ordering has to
/// be deterministic on its own: it is what `universe` shows and what the ranking starts from, and
/// a derivation whose ties fell out of dictionary iteration order would make the More… dialog
/// reshuffle itself between reloads that changed nothing.
public let tallies: [LabelTally]
public init(tallies: [LabelTally]) {
self.tallies = tallies
}
/// The empty board's index — no cards, or no card carrying a label.
public static let empty = LabelIndex(tallies: [])
/// Every used label's display name, in `tallies`' order.
public var names: [String] { tallies.map(\.name) }
public var isEmpty: Bool { tallies.isEmpty }
/// The universe as the More… dialog lists it: **alphabetically, case-insensitively**, because a
/// dialog whose whole job is "find the one you mean among all of them" is a lookup, and a
/// frequency order is a lookup you cannot do.
public var alphabetical: [String] {
tallies.map(\.name).sorted { Self.precedesAlphabetically($0, $1) }
}
/// Whether the board already uses a case-insensitively equal name — the create field's "this is
/// not new" test.
public func contains(_ name: String) -> Bool {
CardLabels.contains(name, in: names)
}
/// The board's own spelling of a name, when it has one — so a user who types `BUG` into the create
/// field adds the `bug` the rest of the board already says, rather than minting a second variant.
public func canonicalSpelling(of name: String) -> String? {
guard let name = CardLabels.normalized(name) else { return nil }
let key = CardLabels.canonical(name)
return tallies.first { CardLabels.canonical($0.name) == key }?.name
}
// MARK: Derivation
/// The universe of `snapshot`, live cards and trash alike.
public static func derive(from snapshot: BoardModel) -> LabelIndex {
var order: [String] = []
var counts: [String: Int] = [:]
var spellings: [String: String] = [:]
func absorb(_ card: Card) {
for name in card.labels.value ?? [] {
let key = CardLabels.canonical(name)
if spellings[key] == nil {
spellings[key] = name
order.append(key)
}
counts[key, default: 0] += 1
}
}
for lane in snapshot.lanes {
for card in lane.cards { absorb(card) }
}
for card in snapshot.trash { absorb(card) }
let tallies = order.map { key in
LabelTally(name: spellings[key] ?? key, count: counts[key] ?? 0)
}
return LabelIndex(tallies: tallies.sorted(by: precedes))
}
/// Frequency descending, then case-insensitively alphabetical, then by raw spelling — a **total**
/// order, which is what makes the derivation reproducible.
private static func precedes(_ lhs: LabelTally, _ rhs: LabelTally) -> Bool {
if lhs.count != rhs.count { return lhs.count > rhs.count }
return precedesAlphabetically(lhs.name, rhs.name)
}
/// Case-insensitive alphabetical, with the raw spelling as the last resort so `Bug` and `bug`
/// never compare equal and the sort stays total.
static func precedesAlphabetically(_ lhs: String, _ rhs: String) -> Bool {
let folded = CardLabels.canonical(lhs).compare(CardLabels.canonical(rhs))
if folded != .orderedSame { return folded == .orderedAscending }
return lhs < rhs
}
}
// MARK: - The menu's twelve
/// **"The most frequently and recently used labels"** — the owner's phrase for the card context
/// menu's twelve rows, turned into arithmetic.
///
/// ### The ranking, exactly
///
/// 1. **Frequency, descending** — how many of the board's cards (live and trashed) carry the label
/// (`LabelIndex`).
/// 2. **Recency, as the tie-break** — among labels used by the same number of cards, the one this
/// user applied most recently comes first (`LabelRecents`, an app-side MRU updated on every apply).
/// A label the MRU has never seen sorts behind every label it has.
/// 3. **Case-insensitively alphabetical**, then raw spelling — so the order is *total* and a menu
/// never reshuffles between two openings that changed nothing.
///
/// Then the first twelve.
///
/// ### Why frequency leads and recency follows, and what that costs
///
/// This is the ruling as given, implemented as given. It is worth being explicit about the
/// consequence, because it is visible: on a board with more than twelve labels in heavy use, a label
/// **invented today** will not appear in these rows until enough cards carry it to beat the
/// twelfth-most-common one — even though it is by far the most *recently* used. The recency half only
/// separates labels that are already tied on frequency, which on a board with an even spread of usage
/// is often most of them, and on a lopsided board is almost none.
///
/// The alternative — a blended score, or reserving a slot or two for pure recency — would surface a
/// fresh label immediately at the cost of a menu whose contents move under the user's hand. Neither
/// is obviously right, so the literal reading of the ruling is what shipped, and the observation is
/// journaled for the owner rather than quietly designed around. **More…** is the escape hatch either
/// way: every used label is one row further in, and the create field is beside it.
public enum LabelRanking {
/// How many rows the context menu's `labels` submenu shows before its separator — the owner's
/// "up to 12".
public static let menuLimit = 12
/// The top `limit` of `index`, ranked as the type comment describes.
///
/// - Parameter recents: most-recent-first, `LabelRecents.labels`' own order. Entries naming labels
/// the board no longer uses are simply never matched — the MRU is app-wide and a board is not
/// obliged to know about labels from another one.
public static func ranked(_ index: LabelIndex, recents: [String], limit: Int = menuLimit) -> [String] {
guard limit > 0 else { return [] }
// Position in the MRU, by canonical name — built once rather than searched per comparison, so
// the sort stays O(n log n) instead of O(n² ) in the number of distinct labels.
var recency: [String: Int] = [:]
for (position, name) in recents.enumerated() {
let key = CardLabels.canonical(name)
if recency[key] == nil { recency[key] = position }
}
let ordered = index.tallies.sorted { lhs, rhs in
if lhs.count != rhs.count { return lhs.count > rhs.count }
let left = recency[CardLabels.canonical(lhs.name)] ?? Int.max
let right = recency[CardLabels.canonical(rhs.name)] ?? Int.max
if left != right { return left < right }
return LabelIndex.precedesAlphabetically(lhs.name, rhs.name)
}
return ordered.prefix(limit).map(\.name)
}
}