@lightspeed/crane 1.3.3 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.4.0 - 2025-10-06
+
+### Changed
+
+- Update CLI TypeScript type definitions to improve type safety, code organization, and maintainability.
+- Update Local Preview to support external content mocking.
+
+### Fixed
+
+- Fix Local Preview to correctly handle background colours in custom sections.
+
 ## 1.3.3 - 2025-09-23
 
 ### Added

package/dist/app.d.mts

@@ -212,6 +212,9 @@ declare function getReactiveRef(card: Card | undefined, editorType: EditorTypes,
     highResolutionMobileImage: string;
     lowResolutionDesktopImage: string;
     highResolutionDesktopImage: string;
+} | {
+    hasContent: boolean;
+    value: boolean | undefined;
 } | {
     title: string | undefined;
     type: ActionLinkType | undefined;
@@ -224,9 +227,6 @@ declare function getReactiveRef(card: Card | undefined, editorType: EditorTypes,
     hasTitle: boolean;
     hasLink: boolean;
     performAction: (() => void) | undefined;
-} | {
-    hasContent: boolean;
-    value: boolean | undefined;
 } | undefined;
 
 declare function useLogoElementContent<CONTENT>(): {
@@ -384,14 +384,622 @@ interface InstantsiteJSAPI {
 
 declare function useInstantsiteJsApi(): InstantsiteJSAPI | undefined;
 
-interface StorefrontSection {
+// This definition file follows a somewhat unusual format. ESTree allows
+// runtime type checks based on the `type` parameter. In order to explain this
+// to typescript we want to use discriminated union types:
+// https://github.com/Microsoft/TypeScript/pull/9163
+//
+// For ESTree this is a bit tricky because the high level interfaces like
+// Node or Function are pulling double duty. We want to pass common fields down
+// to the interfaces that extend them (like Identifier or
+// ArrowFunctionExpression), but you can't extend a type union or enforce
+// common fields on them. So we've split the high level interfaces into two
+// types, a base type which passes down inherited fields, and a type union of
+// all types which extend the base type. Only the type union is exported, and
+// the union is how other types refer to the collection of inheriting types.
+//
+// This makes the definitions file here somewhat more difficult to maintain,
+// but it has the notable advantage of making ESTree much easier to use as
+// an end user.
+
+interface BaseNodeWithoutComments {
+    // Every leaf interface that extends BaseNode must specify a type property.
+    // The type property should be a string literal. For example, Identifier
+    // has: `type: "Identifier"`
+    type: string;
+    loc?: SourceLocation | null | undefined;
+    range?: [number, number] | undefined;
+}
+
+interface BaseNode extends BaseNodeWithoutComments {
+    leadingComments?: Comment[] | undefined;
+    trailingComments?: Comment[] | undefined;
+}
+
+interface Comment extends BaseNodeWithoutComments {
+    type: "Line" | "Block";
+    value: string;
+}
+
+interface SourceLocation {
+    source?: string | null | undefined;
+    start: Position;
+    end: Position;
+}
+
+interface Position {
+    /** >= 1 */
+    line: number;
+    /** >= 0 */
+    column: number;
+}
+
+interface BaseFunction extends BaseNode {
+    params: Pattern[];
+    generator?: boolean | undefined;
+    async?: boolean | undefined;
+    // The body is either BlockStatement or Expression because arrow functions
+    // can have a body that's either. FunctionDeclarations and
+    // FunctionExpressions have only BlockStatement bodies.
+    body: BlockStatement | Expression;
+}
+
+type Statement =
+    | ExpressionStatement
+    | BlockStatement
+    | StaticBlock
+    | EmptyStatement
+    | DebuggerStatement
+    | WithStatement
+    | ReturnStatement
+    | LabeledStatement
+    | BreakStatement
+    | ContinueStatement
+    | IfStatement
+    | SwitchStatement
+    | ThrowStatement
+    | TryStatement
+    | WhileStatement
+    | DoWhileStatement
+    | ForStatement
+    | ForInStatement
+    | ForOfStatement
+    | Declaration;
+
+interface BaseStatement extends BaseNode {}
+
+interface EmptyStatement extends BaseStatement {
+    type: "EmptyStatement";
+}
+
+interface BlockStatement extends BaseStatement {
+    type: "BlockStatement";
+    body: Statement[];
+    innerComments?: Comment[] | undefined;
+}
+
+interface StaticBlock extends Omit<BlockStatement, "type"> {
+    type: "StaticBlock";
+}
+
+interface ExpressionStatement extends BaseStatement {
+    type: "ExpressionStatement";
+    expression: Expression;
+}
+
+interface IfStatement extends BaseStatement {
+    type: "IfStatement";
+    test: Expression;
+    consequent: Statement;
+    alternate?: Statement | null | undefined;
+}
+
+interface LabeledStatement extends BaseStatement {
+    type: "LabeledStatement";
+    label: Identifier;
+    body: Statement;
+}
+
+interface BreakStatement extends BaseStatement {
+    type: "BreakStatement";
+    label?: Identifier | null | undefined;
+}
+
+interface ContinueStatement extends BaseStatement {
+    type: "ContinueStatement";
+    label?: Identifier | null | undefined;
+}
+
+interface WithStatement extends BaseStatement {
+    type: "WithStatement";
+    object: Expression;
+    body: Statement;
+}
+
+interface SwitchStatement extends BaseStatement {
+    type: "SwitchStatement";
+    discriminant: Expression;
+    cases: SwitchCase[];
+}
+
+interface ReturnStatement extends BaseStatement {
+    type: "ReturnStatement";
+    argument?: Expression | null | undefined;
+}
+
+interface ThrowStatement extends BaseStatement {
+    type: "ThrowStatement";
+    argument: Expression;
+}
+
+interface TryStatement extends BaseStatement {
+    type: "TryStatement";
+    block: BlockStatement;
+    handler?: CatchClause | null | undefined;
+    finalizer?: BlockStatement | null | undefined;
+}
+
+interface WhileStatement extends BaseStatement {
+    type: "WhileStatement";
+    test: Expression;
+    body: Statement;
+}
+
+interface DoWhileStatement extends BaseStatement {
+    type: "DoWhileStatement";
+    body: Statement;
+    test: Expression;
+}
+
+interface ForStatement extends BaseStatement {
+    type: "ForStatement";
+    init?: VariableDeclaration | Expression | null | undefined;
+    test?: Expression | null | undefined;
+    update?: Expression | null | undefined;
+    body: Statement;
+}
+
+interface BaseForXStatement extends BaseStatement {
+    left: VariableDeclaration | Pattern;
+    right: Expression;
+    body: Statement;
+}
+
+interface ForInStatement extends BaseForXStatement {
+    type: "ForInStatement";
+}
+
+interface DebuggerStatement extends BaseStatement {
+    type: "DebuggerStatement";
+}
+
+type Declaration = FunctionDeclaration | VariableDeclaration | ClassDeclaration;
+
+interface BaseDeclaration extends BaseStatement {}
+
+interface MaybeNamedFunctionDeclaration extends BaseFunction, BaseDeclaration {
+    type: "FunctionDeclaration";
+    /** It is null when a function declaration is a part of the `export default function` statement */
+    id: Identifier | null;
+    body: BlockStatement;
+}
+
+interface FunctionDeclaration extends MaybeNamedFunctionDeclaration {
+    id: Identifier;
+}
+
+interface VariableDeclaration extends BaseDeclaration {
+    type: "VariableDeclaration";
+    declarations: VariableDeclarator[];
+    kind: "var" | "let" | "const";
+}
+
+interface VariableDeclarator extends BaseNode {
+    type: "VariableDeclarator";
+    id: Pattern;
+    init?: Expression | null | undefined;
+}
+
+interface ExpressionMap {
+    ArrayExpression: ArrayExpression;
+    ArrowFunctionExpression: ArrowFunctionExpression;
+    AssignmentExpression: AssignmentExpression;
+    AwaitExpression: AwaitExpression;
+    BinaryExpression: BinaryExpression;
+    CallExpression: CallExpression;
+    ChainExpression: ChainExpression;
+    ClassExpression: ClassExpression;
+    ConditionalExpression: ConditionalExpression;
+    FunctionExpression: FunctionExpression;
+    Identifier: Identifier;
+    ImportExpression: ImportExpression;
+    Literal: Literal;
+    LogicalExpression: LogicalExpression;
+    MemberExpression: MemberExpression;
+    MetaProperty: MetaProperty;
+    NewExpression: NewExpression;
+    ObjectExpression: ObjectExpression;
+    SequenceExpression: SequenceExpression;
+    TaggedTemplateExpression: TaggedTemplateExpression;
+    TemplateLiteral: TemplateLiteral;
+    ThisExpression: ThisExpression;
+    UnaryExpression: UnaryExpression;
+    UpdateExpression: UpdateExpression;
+    YieldExpression: YieldExpression;
+}
+
+type Expression = ExpressionMap[keyof ExpressionMap];
+
+interface BaseExpression extends BaseNode {}
+
+type ChainElement = SimpleCallExpression | MemberExpression;
+
+interface ChainExpression extends BaseExpression {
+    type: "ChainExpression";
+    expression: ChainElement;
+}
+
+interface ThisExpression extends BaseExpression {
+    type: "ThisExpression";
+}
+
+interface ArrayExpression extends BaseExpression {
+    type: "ArrayExpression";
+    elements: Array<Expression | SpreadElement | null>;
+}
+
+interface ObjectExpression extends BaseExpression {
+    type: "ObjectExpression";
+    properties: Array<Property | SpreadElement>;
+}
+
+interface PrivateIdentifier extends BaseNode {
+    type: "PrivateIdentifier";
+    name: string;
+}
+
+interface Property extends BaseNode {
+    type: "Property";
+    key: Expression | PrivateIdentifier;
+    value: Expression | Pattern; // Could be an AssignmentProperty
+    kind: "init" | "get" | "set";
+    method: boolean;
+    shorthand: boolean;
+    computed: boolean;
+}
+
+interface PropertyDefinition extends BaseNode {
+    type: "PropertyDefinition";
+    key: Expression | PrivateIdentifier;
+    value?: Expression | null | undefined;
+    computed: boolean;
+    static: boolean;
+}
+
+interface FunctionExpression extends BaseFunction, BaseExpression {
+    id?: Identifier | null | undefined;
+    type: "FunctionExpression";
+    body: BlockStatement;
+}
+
+interface SequenceExpression extends BaseExpression {
+    type: "SequenceExpression";
+    expressions: Expression[];
+}
+
+interface UnaryExpression extends BaseExpression {
+    type: "UnaryExpression";
+    operator: UnaryOperator;
+    prefix: true;
+    argument: Expression;
+}
+
+interface BinaryExpression extends BaseExpression {
+    type: "BinaryExpression";
+    operator: BinaryOperator;
+    left: Expression;
+    right: Expression;
+}
+
+interface AssignmentExpression extends BaseExpression {
+    type: "AssignmentExpression";
+    operator: AssignmentOperator;
+    left: Pattern | MemberExpression;
+    right: Expression;
+}
+
+interface UpdateExpression extends BaseExpression {
+    type: "UpdateExpression";
+    operator: UpdateOperator;
+    argument: Expression;
+    prefix: boolean;
+}
+
+interface LogicalExpression extends BaseExpression {
+    type: "LogicalExpression";
+    operator: LogicalOperator;
+    left: Expression;
+    right: Expression;
+}
+
+interface ConditionalExpression extends BaseExpression {
+    type: "ConditionalExpression";
+    test: Expression;
+    alternate: Expression;
+    consequent: Expression;
+}
+
+interface BaseCallExpression extends BaseExpression {
+    callee: Expression | Super;
+    arguments: Array<Expression | SpreadElement>;
+}
+type CallExpression = SimpleCallExpression | NewExpression;
+
+interface SimpleCallExpression extends BaseCallExpression {
+    type: "CallExpression";
+    optional: boolean;
+}
+
+interface NewExpression extends BaseCallExpression {
+    type: "NewExpression";
+}
+
+interface MemberExpression extends BaseExpression, BasePattern {
+    type: "MemberExpression";
+    object: Expression | Super;
+    property: Expression | PrivateIdentifier;
+    computed: boolean;
+    optional: boolean;
+}
+
+type Pattern = Identifier | ObjectPattern | ArrayPattern | RestElement | AssignmentPattern | MemberExpression;
+
+interface BasePattern extends BaseNode {}
+
+interface SwitchCase extends BaseNode {
+    type: "SwitchCase";
+    test?: Expression | null | undefined;
+    consequent: Statement[];
+}
+
+interface CatchClause extends BaseNode {
+    type: "CatchClause";
+    param: Pattern | null;
+    body: BlockStatement;
+}
+
+interface Identifier extends BaseNode, BaseExpression, BasePattern {
+    type: "Identifier";
+    name: string;
+}
+
+type Literal = SimpleLiteral | RegExpLiteral | BigIntLiteral;
+
+interface SimpleLiteral extends BaseNode, BaseExpression {
+    type: "Literal";
+    value: string | boolean | number | null;
+    raw?: string | undefined;
+}
+
+interface RegExpLiteral extends BaseNode, BaseExpression {
+    type: "Literal";
+    value?: RegExp | null | undefined;
+    regex: {
+        pattern: string;
+        flags: string;
+    };
+    raw?: string | undefined;
+}
+
+interface BigIntLiteral extends BaseNode, BaseExpression {
+    type: "Literal";
+    value?: bigint | null | undefined;
+    bigint: string;
+    raw?: string | undefined;
+}
+
+type UnaryOperator = "-" | "+" | "!" | "~" | "typeof" | "void" | "delete";
+
+type BinaryOperator =
+    | "=="
+    | "!="
+    | "==="
+    | "!=="
+    | "<"
+    | "<="
+    | ">"
+    | ">="
+    | "<<"
+    | ">>"
+    | ">>>"
+    | "+"
+    | "-"
+    | "*"
+    | "/"
+    | "%"
+    | "**"
+    | "|"
+    | "^"
+    | "&"
+    | "in"
+    | "instanceof";
+
+type LogicalOperator = "||" | "&&" | "??";
+
+type AssignmentOperator =
+    | "="
+    | "+="
+    | "-="
+    | "*="
+    | "/="
+    | "%="
+    | "**="
+    | "<<="
+    | ">>="
+    | ">>>="
+    | "|="
+    | "^="
+    | "&="
+    | "||="
+    | "&&="
+    | "??=";
+
+type UpdateOperator = "++" | "--";
+
+interface ForOfStatement extends BaseForXStatement {
+    type: "ForOfStatement";
+    await: boolean;
+}
+
+interface Super extends BaseNode {
+    type: "Super";
+}
+
+interface SpreadElement extends BaseNode {
+    type: "SpreadElement";
+    argument: Expression;
+}
+
+interface ArrowFunctionExpression extends BaseExpression, BaseFunction {
+    type: "ArrowFunctionExpression";
+    expression: boolean;
+    body: BlockStatement | Expression;
+}
+
+interface YieldExpression extends BaseExpression {
+    type: "YieldExpression";
+    argument?: Expression | null | undefined;
+    delegate: boolean;
+}
+
+interface TemplateLiteral extends BaseExpression {
+    type: "TemplateLiteral";
+    quasis: TemplateElement[];
+    expressions: Expression[];
+}
+
+interface TaggedTemplateExpression extends BaseExpression {
+    type: "TaggedTemplateExpression";
+    tag: Expression;
+    quasi: TemplateLiteral;
+}
+
+interface TemplateElement extends BaseNode {
+    type: "TemplateElement";
+    tail: boolean;
+    value: {
+        /** It is null when the template literal is tagged and the text has an invalid escape (e.g. - tag`\unicode and \u{55}`) */
+        cooked?: string | null | undefined;
+        raw: string;
+    };
+}
+
+interface AssignmentProperty extends Property {
+    value: Pattern;
+    kind: "init";
+    method: boolean; // false
+}
+
+interface ObjectPattern extends BasePattern {
+    type: "ObjectPattern";
+    properties: Array<AssignmentProperty | RestElement>;
+}
+
+interface ArrayPattern extends BasePattern {
+    type: "ArrayPattern";
+    elements: Array<Pattern | null>;
+}
+
+interface RestElement extends BasePattern {
+    type: "RestElement";
+    argument: Pattern;
+}
+
+interface AssignmentPattern extends BasePattern {
+    type: "AssignmentPattern";
+    left: Pattern;
+    right: Expression;
+}
+interface BaseClass extends BaseNode {
+    superClass?: Expression | null | undefined;
+    body: ClassBody;
+}
+
+interface ClassBody extends BaseNode {
+    type: "ClassBody";
+    body: Array<MethodDefinition | PropertyDefinition | StaticBlock>;
+}
+
+interface MethodDefinition extends BaseNode {
+    type: "MethodDefinition";
+    key: Expression | PrivateIdentifier;
+    value: FunctionExpression;
+    kind: "constructor" | "method" | "get" | "set";
+    computed: boolean;
+    static: boolean;
+}
+
+interface MaybeNamedClassDeclaration extends BaseClass, BaseDeclaration {
+    type: "ClassDeclaration";
+    /** It is null when a class declaration is a part of the `export default class` statement */
+    id: Identifier | null;
+}
+
+interface ClassDeclaration extends MaybeNamedClassDeclaration {
+    id: Identifier;
+}
+
+interface ClassExpression extends BaseClass, BaseExpression {
+    type: "ClassExpression";
+    id?: Identifier | null | undefined;
+}
+
+interface MetaProperty extends BaseExpression {
+    type: "MetaProperty";
+    meta: Identifier;
+    property: Identifier;
+}
+
+interface ImportExpression extends BaseExpression {
+    type: "ImportExpression";
+    source: Expression;
+}
+
+interface AwaitExpression extends BaseExpression {
+    type: "AwaitExpression";
+    argument: Expression;
+}
+
+declare module 'estree' {
+	export interface Decorator extends BaseNode {
+		type: 'Decorator';
+		expression: Expression;
+	}
+	interface PropertyDefinition {
+		decorators: undefined[];
+	}
+	interface MethodDefinition {
+		decorators: undefined[];
+	}
+	interface BaseClass {
+		decorators: undefined[];
+	}
+}
+
+// declare AbortSignal here for environments without DOM lib or @types/node
+declare global {
+	// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+	interface AbortSignal {}
+}
+
+interface TemplateStorefrontSection {
     /** Section layout identifier. When not provided, the section will use the default layout. */
     readonly id?: string;
     readonly type: 'store';
 }
 
 interface StorePageConfiguration {
-    readonly sections: [StorefrontSection];
+    readonly sections: [TemplateStorefrontSection];
 }
 
 declare const CatalogLayoutSlot: {