341 lines
14 KiB
TypeScript
341 lines
14 KiB
TypeScript
/**
|
|
* The "flower branch" geometry for the sidebar tree.
|
|
*
|
|
* Reproduces the RewampUI *Flower Sidebar* mechanism: a single curly branch runs
|
|
* down the left of the nav list, drawn as SVG so it can be *grown* — a faded
|
|
* dashed ghost shows the whole route, and a solid stroke is drawn only as far as
|
|
* the row you are on. Each row gets a dot sitting exactly on the curve, and the
|
|
* active row's dot blooms.
|
|
*
|
|
* How it maps onto OUR tree (three levels: 分组 folder → 项目 folder → 会话 row):
|
|
*
|
|
* - The branch is **one continuous path** through every visible row, not one
|
|
* rail per folder. That is what makes it read as a plant rather than as the
|
|
* per-folder rail it replaces.
|
|
* - The stem runs at `STEM_X`; at each **group boundary** it kinks outward to
|
|
* `BULGE_X` and back — a half-pitch out plus a half-pitch back, which is
|
|
* exactly the reference's 32px rhythm.
|
|
* - Rows that are not group boundaries sit on a straight run, one row pitch
|
|
* apart, each carrying a dot at its own y.
|
|
*
|
|
* Runtime-free on purpose (same discipline as `tabs.ts` / `store-core.ts`): the
|
|
* component measures the DOM and hands plain numbers here, so the geometry is
|
|
* unit-testable without a browser.
|
|
*/
|
|
|
|
/** Horizontal position of the stem's straight runs. */
|
|
/**
|
|
* Default x for a row's anchor, in SVG coordinates.
|
|
*
|
|
* A fallback only: rows carry their OWN measured `x`, because the tree indents
|
|
* with per-row padding rather than one shared origin. A folder's chevron and a
|
|
* session's text sit at different x, and no single constant lands on both.
|
|
*/
|
|
export const STEM_X = 30
|
|
|
|
/** Default vertical pitch between two rows. */
|
|
export const ROW_PITCH = 32
|
|
|
|
/**
|
|
* One row the branch must pass through.
|
|
*
|
|
* Both coordinates are MEASURED, not derived:
|
|
* - `y` because the tree mixes row heights and inter-row gaps (deriving one
|
|
* pitch from a single gap drifted the dots up to 15px off their rows);
|
|
* - `x` because the tree indents per row via padding, so a folder's chevron and
|
|
* a session's text are at different x.
|
|
*/
|
|
export interface BranchRow {
|
|
/** Stable key, used to match a row to its dot. */
|
|
readonly key: string
|
|
/** Row centre y, in the SVG's coordinate space. */
|
|
readonly y: number
|
|
/**
|
|
* Row anchor x, in the SVG's coordinate space.
|
|
*
|
|
* A folder row's anchor is its CHEVRON centre — the triangle the user already
|
|
* reads as "this row opens" — so the stem visually hangs off the marker rather
|
|
* than floating beside it. A session row's anchor is the indent its text sits
|
|
* on.
|
|
*/
|
|
readonly x: number
|
|
/**
|
|
* Row kind. A `'group'` row starts a new group and makes the stem kink;
|
|
* an `'item'` row runs straight (or curves back in right after a group).
|
|
*/
|
|
readonly kind: 'group' | 'item'
|
|
/** Whether this is the row the user is currently on (the bloomed dot). */
|
|
readonly active: boolean
|
|
}
|
|
|
|
/** A dot on the branch: one per row, positioned on the curve. */
|
|
export interface BranchDot {
|
|
/** The row this dot belongs to. */
|
|
readonly key: string
|
|
readonly cx: number
|
|
readonly cy: number
|
|
readonly active: boolean
|
|
}
|
|
|
|
/**
|
|
* The bloom that flowers at the branch's endpoint.
|
|
*
|
|
* The endpoint is where the GROWN stroke stops — the row the user is on — not
|
|
* the last visible row: the stem is drawn to the active row, so that is where
|
|
* the plant has visibly reached, whether the tree is folded above it or not.
|
|
*
|
|
* This is deliberately the ONE row an active marker names, so the flower can
|
|
* never disagree with the stem about where the branch ends.
|
|
*/
|
|
export interface BranchFlower {
|
|
/** Row whose endpoint carries the bloom (the active row's key). */
|
|
readonly key: string
|
|
/** Endpoint x: the last dot's centre, i.e. exactly where the grown path stops. */
|
|
readonly cx: number
|
|
/** Endpoint y, on the measured row centre. */
|
|
readonly cy: number
|
|
}
|
|
|
|
/** The branch: one path for the ghost, its total length, and the dots. */
|
|
export interface Branch {
|
|
/** Full route, drawn as the faded dashed ghost. */
|
|
readonly ghostPath: string
|
|
/** Path up to and including the active row (the "grown" part). */
|
|
readonly grownPath: string
|
|
/** Drawn length of the full route. */
|
|
readonly ghostLength: number
|
|
/** Drawn length of the grown part. */
|
|
readonly grownLength: number
|
|
/** Dots, in row order. */
|
|
readonly dots: readonly BranchDot[]
|
|
/**
|
|
* Bloom at the grown path's endpoint, or NULL when no row carries the active
|
|
* marker.
|
|
*
|
|
* Deliberately stricter than `grownPath`: the stem has to be *some* path even
|
|
* when nothing is active (it collapses to the bare origin, drawing nothing),
|
|
* but a bloom with no active row has nothing to be the flower OF. Falling back
|
|
* to the first dot — the earlier rule — put the blossom on a folder row at the
|
|
* top of the tree as soon as the open session's folder was collapsed, because
|
|
* folding removes the only row carrying the marker. No active row means no
|
|
* flower.
|
|
*/
|
|
readonly flower: BranchFlower | null
|
|
/** Total vertical extent, so the SVG box can be sized. */
|
|
readonly height: number
|
|
}
|
|
|
|
/**
|
|
* Internal: one move of the route, kept as STRUCTURE rather than only as a path
|
|
* string. The endpoint trim below has to shorten the final move along its own
|
|
* direction, which is only sound if the segment still knows where it goes.
|
|
*/
|
|
interface Segment {
|
|
/** SVG path command for the full move. */
|
|
readonly d: string
|
|
/** Length the move contributes to the run. */
|
|
readonly length: number
|
|
/** Where the move starts. */
|
|
readonly from: { readonly x: number; readonly y: number }
|
|
/** Where the move ends. */
|
|
readonly to: { readonly x: number; readonly y: number }
|
|
/** Bulge x for a curved move (the curve is vertical-tangent at both ends). */
|
|
readonly controlX?: number
|
|
}
|
|
|
|
/**
|
|
* Plan the route: one segment per row after the first, plus the dot positions.
|
|
*
|
|
* Kept separate from the string assembly so the length walk and the SVG `d`
|
|
* always describe the same geometry — measuring one path against another is how
|
|
* a grown/ghost pair drifts out of sync.
|
|
*
|
|
* The stem lands on each row's OWN anchor (x) and centre (y), so uneven row
|
|
* heights and the tree's per-row indents both stay exact. A group row's anchor
|
|
* is pushed out by `BULGE_OFFSET`, which is what creates the kink.
|
|
*
|
|
* @param rows - visible rows in render order, carrying measured anchors.
|
|
* @returns the per-row segments and dot x positions.
|
|
*/
|
|
function plan(rows: readonly BranchRow[]): { segments: Segment[]; dotX: number[] } {
|
|
const segments: Segment[] = []
|
|
const first = rows[0] as BranchRow
|
|
const dotX: number[] = [first.x]
|
|
let x = first.x
|
|
|
|
for (let i = 1; i < rows.length; i += 1) {
|
|
const row = rows[i] as BranchRow
|
|
const prev = rows[i - 1] as BranchRow
|
|
const startY = prev.y
|
|
const endY = row.y
|
|
const midY = startY + (endY - startY) / 2
|
|
|
|
// Every dot lands on its OWN anchor; the stem simply travels between them.
|
|
// When two consecutive rows share an anchor (sessions under one project) the
|
|
// travel is a straight run; when it changes (a folder's chevron sits left of
|
|
// its children's dots) the stem swings out through an S-curve, which is what
|
|
// reads as the branch stepping around the folder marker.
|
|
const target = row.x
|
|
|
|
if (target === x) {
|
|
segments.push({
|
|
d: `L ${x} ${endY}`,
|
|
length: Math.abs(endY - startY),
|
|
from: { x, y: startY },
|
|
to: { x, y: endY },
|
|
})
|
|
} else {
|
|
// Two halves so the tangent is vertical at both ends, matching the
|
|
// reference's curve rhythm.
|
|
segments.push({
|
|
d: `C ${x} ${midY}, ${target} ${midY}, ${target} ${endY}`,
|
|
length: Math.hypot(target - x, endY - midY),
|
|
from: { x, y: startY },
|
|
to: { x: target, y: endY },
|
|
controlX: x,
|
|
})
|
|
x = target
|
|
}
|
|
dotX.push(x)
|
|
}
|
|
|
|
return { segments, dotX }
|
|
}
|
|
|
|
/**
|
|
* How far short of the flower's centre the stem stops, in SVG user units.
|
|
*
|
|
* The bloom is drawn ON the endpoint, so a stem that runs all the way to the
|
|
* centre is visible through the petal notches and reads as a line crossing the
|
|
* flower. Stopping the stroke at (a little over) the bloom's radius keeps the
|
|
* stem ending cleanly at the flower's edge, where it reads as a stalk holding
|
|
* the bloom.
|
|
*
|
|
* 7 units ≈ the 6.2-unit flower radius plus a hair, so the stroke's round cap
|
|
* tucks just under the outer petals without a visible gap.
|
|
*/
|
|
export const STEM_END_CLEARANCE = 7
|
|
|
|
/**
|
|
* Shorten a move so it stops `clearance` short of its end point.
|
|
*
|
|
* Used only on the LAST move of the grown run, which is what hides the stroke
|
|
* behind the bloom. A straight move is trimmed along its axis; a curved move is
|
|
* trimmed by moving its end and its control point together, which shortens the
|
|
* curve while keeping its vertical tangents (so the kink's shape is preserved
|
|
* rather than being flattened into a line).
|
|
*
|
|
* Returns the move unchanged when it is too short to trim (the stem would
|
|
* invert), so a cramped layout degrades to "line meets flower" rather than
|
|
* producing a backwards path.
|
|
*
|
|
* @param segment - the move to shorten.
|
|
* @param clearance - distance to stop short of the end.
|
|
* @returns the shortened move.
|
|
*/
|
|
function trimEnd(segment: Segment, clearance: number): Segment {
|
|
const { from, to } = segment
|
|
const span = Math.hypot(to.x - from.x, to.y - from.y)
|
|
if (span <= clearance) return segment
|
|
|
|
if (segment.controlX === undefined) {
|
|
// Straight: retreat along the axis by the clearance.
|
|
const ratio = (span - clearance) / span
|
|
const endX = from.x + (to.x - from.x) * ratio
|
|
const endY = from.y + (to.y - from.y) * ratio
|
|
return { ...segment, d: `L ${endX} ${endY}`, to: { x: endX, y: endY }, length: span - clearance }
|
|
}
|
|
|
|
// Curved: the move is two mirrored halves, so retreating the END by half the
|
|
// clearance and the control point by the full one shortens it symmetrically
|
|
// while keeping both tangents vertical.
|
|
const endY = to.y - clearance
|
|
const controlY = from.y + (to.y - from.y) / 2 - clearance
|
|
const endX = to.x
|
|
return {
|
|
...segment,
|
|
d: `C ${segment.controlX} ${controlY}, ${endX} ${controlY}, ${endX} ${endY}`,
|
|
to: { x: endX, y: endY },
|
|
length: Math.max(0, segment.length - clearance),
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Build the branch for a list of rows.
|
|
*
|
|
* @param rows - visible rows in render order, each carrying its MEASURED centre.
|
|
* @returns the branch geometry; empty strings when there are no rows.
|
|
*/
|
|
export function buildBranch(rows: readonly BranchRow[]): Branch {
|
|
const first = rows[0]
|
|
if (first === undefined) {
|
|
return { ghostPath: '', grownPath: '', ghostLength: 0, grownLength: 0, dots: [], flower: null, height: 0 }
|
|
}
|
|
|
|
const { segments, dotX } = plan(rows)
|
|
const head = `M ${first.x} ${first.y}`
|
|
|
|
const dots: BranchDot[] = rows.map((row, index) => ({
|
|
key: row.key,
|
|
cx: dotX[index] ?? row.x,
|
|
cy: row.y,
|
|
active: row.active,
|
|
}))
|
|
|
|
// The grown stroke stops AT the active row, so its path contains every
|
|
// segment before that row and none after. An active first row grows nothing
|
|
// beyond the origin, which is correct (the dot sits on the stem origin).
|
|
//
|
|
// `activeIndex < 0` is the NO-ACTIVE-ROW case: the open session's folder was
|
|
// collapsed, or the catalog has not resolved yet. The stem then collapses to
|
|
// the bare origin (drawing nothing), and — crucially — `hasActive` stays false
|
|
// so no flower is produced. Conflating this with "the first row is active" is
|
|
// what used to sprout the blossom on a top-level folder row.
|
|
const activeIndex = rows.findIndex(row => row.active)
|
|
const hasActive = activeIndex >= 0
|
|
const grownTo = hasActive ? activeIndex : 0
|
|
|
|
// The bloom sits on the endpoint of `grownPath`, which `join` puts at the
|
|
// active row. It therefore uses the SAME index as the grown stroke, so the
|
|
// flower and the stem can never disagree about where the branch ends — and it
|
|
// exists ONLY when a row actually claimed the marker.
|
|
const flowerAt = dots[grownTo] as BranchDot | undefined
|
|
const flower: BranchFlower | null = hasActive && flowerAt !== undefined
|
|
? { key: flowerAt.key, cx: flowerAt.cx, cy: flowerAt.cy }
|
|
: null
|
|
|
|
const join = (list: readonly Segment[]): string =>
|
|
list.length === 0 ? head : [head, ...list.map(s => s.d)].join(' ')
|
|
|
|
// The grown run: every move before the active row, plus the move INTO it —
|
|
// which is the one trimmed so the stroke stops at the bloom's edge instead of
|
|
// crossing the flower. The GHOST keeps its full length: it is a faint dashed
|
|
// route at 28% opacity, and shortening it too would leave the last row's
|
|
// guide visibly detached from that row.
|
|
const grownSegments = segments.slice(0, grownTo)
|
|
const lastGrown = grownSegments[grownSegments.length - 1]
|
|
const grownStroke = lastGrown === undefined
|
|
? grownSegments
|
|
: [...grownSegments.slice(0, -1), trimEnd(lastGrown, STEM_END_CLEARANCE)]
|
|
|
|
const lengthOf = (count: number): number =>
|
|
segments.slice(0, count).reduce((sum, s) => sum + s.length, 0)
|
|
|
|
const last = rows[rows.length - 1] as BranchRow
|
|
// Half a row height of breathing room below the last dot, so the stem does not
|
|
// stop dead on the final row.
|
|
const tail = rows.length > 1 ? Math.abs(last.y - (rows[rows.length - 2] as BranchRow).y) / 2 : 0
|
|
|
|
return {
|
|
ghostPath: join(segments),
|
|
grownPath: join(grownStroke),
|
|
ghostLength: lengthOf(segments.length),
|
|
// The grown length follows the TRIMMED run, so a consumer measuring the
|
|
// stroke (a dash animation, say) stays consistent with what is drawn.
|
|
grownLength: Math.max(0, lengthOf(grownTo) - (lastGrown === undefined ? 0 : STEM_END_CLEARANCE)),
|
|
dots,
|
|
flower,
|
|
height: last.y + tail,
|
|
}
|
|
}
|