@framesquared/component 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Carbone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,350 @@
+import { Base } from '@framesquared/core';
+
+/**
+ * @framesquared/component – Template
+ *
+ * A simple template engine that supports `{token}` replacement.
+ * Used by Component to render content from data.
+ *
+ * ```ts
+ * const tpl = new Template('<div>{name} is {age} years old</div>');
+ * const html = tpl.apply({ name: 'Alice', age: 30 });
+ * // → '<div>Alice is 30 years old</div>'
+ * ```
+ */
+declare class Template {
+    private source;
+    constructor(source: string);
+    /**
+     * Applies data to the template and returns the resulting HTML string.
+     * Replaces `{key}` tokens with values from the data object.
+     * Supports nested keys via dot notation: `{user.name}`.
+     */
+    apply(data: Record<string, unknown>): string;
+    /**
+     * Alias for apply().
+     */
+    render(data: Record<string, unknown>): string;
+    private resolve;
+}
+
+/**
+ * @framesquared/component – Component
+ *
+ * The base for all UI widgets.  Provides a complete lifecycle,
+ * DOM element management, CSS operations, sizing with ResizeObserver,
+ * template rendering, focus management, and deterministic destruction.
+ */
+
+interface ComponentConfig {
+    xtype?: string;
+    cls?: string | string[];
+    style?: Partial<CSSStyleDeclaration> | string;
+    width?: number | string;
+    height?: number | string;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    margin?: number | string;
+    padding?: number | string;
+    hidden?: boolean;
+    disabled?: boolean;
+    html?: string;
+    tpl?: Template;
+    data?: Record<string, unknown>;
+    renderTo?: Element | string;
+    floating?: boolean;
+    listeners?: Record<string, Function>;
+    reference?: string;
+    [key: string]: unknown;
+}
+declare class Component extends Base {
+    static $className: string;
+    el: HTMLElement | null;
+    rendered: boolean;
+    /** The Container that owns this Component (set by Container.add). */
+    ownerCt: Component | null;
+    private _hidden;
+    private _disabled;
+    private _tpl;
+    private _data;
+    private _resizeObserver;
+    private _lastWidth;
+    private _lastHeight;
+    protected _config: ComponentConfig;
+    /** Unique component id */
+    readonly componentId: string;
+    $destroyHooks: (() => void)[];
+    constructor(config?: ComponentConfig);
+    /** Called before initialize(). Override in subclasses. */
+    protected beforeInitialize(): void;
+    /** Main initialization. Override in subclasses. */
+    protected initialize(): void;
+    /** Called after initialize(). Override in subclasses. */
+    protected afterInitialize(): void;
+    /** Called before render(). Override in subclasses. */
+    protected beforeRender(): void;
+    /** Called after render(). Override in subclasses. */
+    protected afterRender(): void;
+    /** Called before destroy(). Override in subclasses. */
+    protected beforeDestroy(): void;
+    /** Called during destroy(). Override in subclasses. */
+    protected onDestroy(): void;
+    /** Called after destroy(). Override in subclasses. */
+    protected afterDestroy(): void;
+    render(container?: Element | string, position?: number | Element): void;
+    private resolveElement;
+    private applyConfigs;
+    isVisible(): boolean;
+    setVisible(visible: boolean): void;
+    show(): void;
+    hide(): void;
+    isDisabled(): boolean;
+    enable(): void;
+    disable(): void;
+    getWidth(): number;
+    getHeight(): number;
+    getSize(): {
+        width: number;
+        height: number;
+    };
+    setWidth(width: number | string): void;
+    setHeight(height: number | string): void;
+    setSize(width: number | string, height: number | string): void;
+    getX(): number;
+    getY(): number;
+    setX(x: number): void;
+    setY(y: number): void;
+    setPosition(x: number, y: number): void;
+    getBox(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    private setupResizeObserver;
+    addCls(...classes: string[]): void;
+    removeCls(...classes: string[]): void;
+    toggleCls(cls: string, state?: boolean): void;
+    hasCls(cls: string): boolean;
+    setStyle(propOrObj: string | Record<string, string>, value?: string): void;
+    getStyle(prop: string): string;
+    update(htmlOrData: string | Record<string, unknown>): void;
+    setHtml(html: string): void;
+    setData(data: Record<string, unknown>): void;
+    getEl(): HTMLElement | null;
+    getElement(): HTMLElement | null;
+    focus(): void;
+    blur(): void;
+    isFocusable(): boolean;
+    /** Returns the element that receives focus. Override for inner focus targets. */
+    protected getFocusEl(): HTMLElement | null;
+    /** Called when added to a Container. */
+    onAdded(_owner: Component, _index: number): void;
+    /** Called when removed from a Container. */
+    onRemoved(_destroying: boolean): void;
+    /**
+     * Walks up the ownerCt chain and returns the first Component whose
+     * xtype matches the given selector string.
+     */
+    up(selector: string): Component | undefined;
+    destroy(): void;
+    protected fire(eventName: string, ...args: unknown[]): boolean;
+}
+
+/**
+ * @framesquared/component – Layout (placeholder)
+ *
+ * Base layout class.  Actual layout managers (HBox, VBox, Border, etc.)
+ * will be implemented in @framesquared/layout.
+ */
+interface LayoutConfig {
+    type?: string;
+    [key: string]: unknown;
+}
+declare class Layout {
+    readonly type: string;
+    constructor(config?: LayoutConfig);
+    /**
+     * Performs layout calculation on the owner container.
+     * Override in subclasses.
+     */
+    doLayout(_owner: any): void;
+}
+/**
+ * Resolves a layout config to a Layout instance.
+ */
+declare function resolveLayout(config: string | LayoutConfig | undefined): Layout;
+
+/**
+ * @framesquared/component – Container
+ *
+ * A Component that manages an ordered collection of child Components.
+ * Provides add/insert/remove, Component Query (CQ) selectors,
+ * layout integration, defaults, reference handling, and destroy cascade.
+ */
+
+interface ContainerConfig extends ComponentConfig {
+    items?: (Component | Record<string, unknown>)[];
+    layout?: string | LayoutConfig;
+    defaults?: Record<string, unknown>;
+}
+declare class Container extends Component {
+    static $className: string;
+    private _items;
+    private _layout;
+    private _bodyEl;
+    constructor(config?: ContainerConfig);
+    protected initialize(): void;
+    protected afterRender(): void;
+    protected onDestroy(): void;
+    /**
+     * Returns the inner element where children are rendered.
+     * Falls back to el if body hasn't been created yet.
+     */
+    getBodyEl(): HTMLElement;
+    add(...items: (Component | Record<string, unknown>)[]): Component[];
+    insert(index: number, item: Component | Record<string, unknown>): Component;
+    remove(item: Component, destroy?: boolean): Component;
+    removeAll(destroy?: boolean): Component[];
+    removeAt(index: number): Component;
+    getItems(): Component[];
+    getAt(index: number): Component | undefined;
+    getComponent(id: string): Component | undefined;
+    indexOf(item: Component): number;
+    contains(item: Component, deep?: boolean): boolean;
+    getCount(): number;
+    getLayout(): Layout;
+    doLayout(): void;
+    query(selector: string): Component[];
+    down(selector: string): Component | undefined;
+    child(selector: string): Component | undefined;
+    queryById(id: string): Component | undefined;
+    queryBy(fn: (item: Component) => boolean): Component[];
+    lookupReference(ref: string): Component | undefined;
+    private resolveItem;
+    private collectAllDescendants;
+    /**
+     * Fires an event and returns false if any listener returned false.
+     */
+    private fireReturning;
+}
+
+/**
+ * @framesquared/component – ComponentQuery
+ *
+ * Backward-compatible wrapper that delegates to the new AST-based CQ engine.
+ */
+
+/**
+ * Tests if a component matches a simple selector. Used by Container.child()
+ * and Component.up().
+ */
+declare function matchesCQ(cmp: Component, selector: string): boolean;
+/**
+ * Legacy ComponentQuery class — delegates to CQMatcher.
+ */
+declare class ComponentQuery {
+    static query(root: any, selector: string): Component[];
+}
+
+interface CompoundSelectorNode {
+    type: 'compound';
+    selectors: any[];
+}
+interface CombinatorNode {
+    type: 'combinator';
+    combinator: string;
+    left: SelectorNode;
+    right: SelectorNode;
+}
+interface SelectorListNode {
+    type: 'list';
+    items: SelectorNode[];
+}
+type SelectorNode = CompoundSelectorNode | CombinatorNode | SelectorListNode;
+declare class CQParser {
+    private tokens;
+    private pos;
+    private constructor();
+    static parse(selector: string): SelectorNode;
+    private peek;
+    private advance;
+    private parseSelectorList;
+    private parseCombinatorExpr;
+    private parseCompound;
+    private parseAttribute;
+    private parsePseudo;
+}
+
+/**
+ * @framesquared/component – CQMatcher
+ *
+ * Evaluates parsed CQ AST nodes against Component instances.
+ * Handles simple selectors, compound selectors, all four combinators,
+ * pseudo-classes, method matchers, and comma-separated OR lists.
+ */
+
+declare class CQMatcher {
+    /**
+     * Returns true if `component` matches the selector string.
+     */
+    static matches(component: Component, selector: string): boolean;
+    /**
+     * Returns all descendants of `root` matching the selector string.
+     */
+    static query(root: Component, selector: string): Component[];
+}
+
+/**
+ * @framesquared/component – CQ (Component Query static API)
+ *
+ * Static convenience API for querying component trees.
+ */
+
+declare class CQ {
+    /**
+     * Finds all components matching the selector under the given root.
+     */
+    static query(selector: string, root?: Component): Component[];
+    /**
+     * Returns true if the component matches the selector.
+     */
+    static is(component: Component, selector: string): boolean;
+}
+
+/**
+ * @framesquared/component – XTemplate
+ *
+ * A powerful template engine inspired by ExtJS's XTemplate.
+ *
+ * Features:
+ *  - `{field}` interpolation with dot paths
+ *  - `{field:format}` built-in format functions
+ *  - `<tpl if="expr">`, `<tpl elseif="expr">`, `<tpl else>`
+ *  - `<tpl for="field">` loops with `{.}`, `{#}`, `{[xindex]}`, `{[xcount]}`, `{parent.x}`
+ *  - `{[expression]}` inline JS expressions (`values` = current scope)
+ *  - `{[this.method(...)]}` template member functions
+ *  - Compiled to a JS function for fast repeat rendering
+ */
+declare class XTemplate {
+    private source;
+    private memberFns;
+    private ast;
+    constructor(source: string, memberFns?: Record<string, Function>);
+    /**
+     * Pre-compiles the template. Called automatically on first apply().
+     */
+    compile(): void;
+    /**
+     * Applies data to the template and returns the resulting HTML string.
+     */
+    apply(data: any): string;
+    /**
+     * Applies data and appends the resulting HTML to an element.
+     */
+    append(el: Element, data: any): void;
+}
+
+export { CQ, CQMatcher, CQParser, type CombinatorNode, Component, type ComponentConfig, ComponentQuery, type CompoundSelectorNode, Container, type ContainerConfig, Layout, type LayoutConfig, type SelectorListNode, type SelectorNode, Template, XTemplate, matchesCQ, resolveLayout };