packages/engine/palette
Pages editor block palette read model.
Engine, v0.9. Source: packages/engine/palette.mjs.
Functions#
buildPalette()#
buildPalette(
root,feature): {components:any[];expressions:any[];feature:string;ok:true;providers:any[]; } | {error:string;ok:false; }
Defined in: packages/engine/palette.mjs:103
The three groups a feature's pages can actually reach: Providers (hook layer, Provider-named +
defineProvider-built only), Expressions (expression layer) and Components (component layer) --
this feature's own, plus any other feature's re-exported through its public index.
Parameters#
root
string
Project root.
feature
string
Feature name (as under features/, or the configured features root).
Returns#
{ components: any[]; expressions: any[]; feature: string; ok: true; providers: any[]; } | { error: string; ok: false; }
buildWrapSuggestions()#
buildWrapSuggestions(
root,source,range,palette):object
Defined in: packages/engine/palette.mjs:323
The Wrap-with suggestion for one JSX selection on a page: the flagged hit it falls inside (or
null, meaning nothing here is PAGE-008-flagged — the Palette tab shows no Wrap affordance), and
every Expression in palette.expressions (Slice 1's own buildPalette output — same reachability
rule, nothing new invented) annotated with its fit against that hit.
Parameters#
root
string
Project root.
source
string
The page file's current full source (same string the selection's own
[start, end] range was computed from).
range
[number, number]
The selected JSX node's own [start, end] source offsets.
palette
A fresh buildPalette(...) result for this feature.
expressions
any[]
Returns#
object
hit
hit:
any
suggestions
suggestions:
any[]
describeWrapHit()#
describeWrapHit(
source,hit):object
Defined in: packages/engine/palette.mjs:234
Human-readable description of one flagged hit, for the Palette tab's selection callout (design's
"3 elements from a .map() over cartItems... flagged PAGE-008" -- the real subject and line,
never illustrative copy). Only ever called on a page file (the Palette tab is Pages-editor-only),
so the flagged rule is always PAGE-008 (COMPONENT-005 is the same shape's component-layer name).
Parameters#
source
string
The page file's current full source (the same string hit was found in).
hit
A hit from findWrapHit.
kind
"loop" | "conditional"
node
any
Returns#
object
kind
kind:
string
line
line:
number
range
range: [
number,number]
rule
rule:
string
subject
subject:
string
summary
summary:
string
expressionShape()#
expressionShape(
root,relPath,name):"unknown"|"loop"|"conditional"
Defined in: packages/engine/palette.mjs:257
Best-effort structural shape of an Expression's own Props interface -- 'loop' (an array-typed
field besides children), 'conditional' (a boolean-typed field), or 'unknown' (neither
found, e.g. a hand-written Expression whose prop is some other type). Mirrors
extractExpression.mjs's own two generated Props shapes exactly (propName: T[] / propName: boolean), so any Expression the codemod itself created is always classified correctly; anything
else is a best-effort proxy for sorting/dimming suggestions, never a hard architecture rule (no
EXPR-* check depends on this).
Parameters#
root
string
Project root.
relPath
string
The Expression file's project-root-relative path.
name
string
The Expression's own exported name (its Props interface is ${name}Props).
Returns#
"unknown" | "loop" | "conditional"
findWrapHit()#
findWrapHit(
source,range?):object
Defined in: packages/engine/palette.mjs:196
The flagged PAGE-008 conditional/loop (packages/ast/jsxComplexity.mjs's own
collectInlineJsxLogic) that encloses range (a [start, end] source-offset pair, e.g. a
selected JSX element's own range from the same parse) -- the smallest one that contains it, since
a loop can nest a conditional or vice versa. range omitted returns the first flagged hit overall
(mirrors extractExpression.mjs's own "no --range" default).
Parameters#
source
string
A page/component file's current full source.
range?
[number, number]
The selection's own [start, end] source offsets.
Returns#
object
The smallest enclosing flagged hit, or
null when nothing flagged encloses the selection (including when the file has no flagged
logic at all) -- callers treat that as "nothing to suggest wrapping here", not an error.
kind
kind:
"loop"|"conditional"
node
node:
any
wrapFit()#
wrapFit(
hitKind,shape):object
Defined in: packages/engine/palette.mjs:297
Does an existing Expression of shape shape structurally fit a flagged hit of kind hitKind --
'fits' (same shape), 'unknown' (can't tell, never dimmed: "never show something the
architecture wouldn't allow" cuts both ways -- an unproven guess doesn't get labelled wrong
either), or 'not-a-fit' (concretely the other shape) with a plain-language reason, per
block-palette.md section 3 step 2's "stays visible but dimmed with an explicit reason" rule.
Parameters#
hitKind
"loop" | "conditional"
The flagged hit's own kind (findWrapHit's kind).
shape
"unknown" | "loop" | "conditional"
An Expression's own shape (expressionShape).
Returns#
object
fit
fit:
"unknown"|"fits"|"not-a-fit"
reason
reason:
string