@framesquared/layout 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,496 @@
+import { Component } from '@framesquared/component';
+
+/**
+ * @framesquared/layout – LayoutContext
+ *
+ * Holds layout state during a layout run.  Caches element measurements
+ * to avoid layout thrashing (repeated reads/writes to the DOM).
+ */
+declare class LayoutContext {
+    /** Generic property cache (layout-level state). */
+    private props;
+    /** Per-element DOM measurement cache: element → (propName → value). */
+    private domCache;
+    /**
+     * Gets a layout-level property value.
+     */
+    getProp(name: string): number | undefined;
+    /**
+     * Sets a layout-level property value.
+     */
+    setProp(name: string, value: number): void;
+    /**
+     * Gets a cached DOM measurement, or reads it via `readFn` and caches the result.
+     * This prevents repeated layout-triggering reads on the same element.
+     */
+    getDomProp(name: string, element: Element, readFn: () => number): number;
+    /**
+     * Returns true if a DOM measurement has been cached for the given element+prop.
+     */
+    hasDomProp(name: string, element: Element): boolean;
+    /**
+     * Clears all cached data.  Called at the start of a new layout run.
+     */
+    flush(): void;
+}
+
+/**
+ * @framesquared/layout – Layout (base class)
+ *
+ * Abstract base for all layout managers.  Manages the lifecycle
+ * (beginLayout → calculate → completeLayout → afterLayout), size
+ * policy determination, and item rendering into a target element.
+ */
+
+interface SizePolicy {
+    width: 'shrinkWrap' | 'configured' | 'natural';
+    height: 'shrinkWrap' | 'configured' | 'natural';
+}
+interface LayoutConfig {
+    type?: string;
+    [key: string]: unknown;
+}
+declare class Layout {
+    readonly type: string;
+    owner: Component | null;
+    isRunning: boolean;
+    needsLayout: boolean;
+    constructor(config?: LayoutConfig);
+    /**
+     * Sets the Container that owns this layout.
+     */
+    setOwner(owner: Component): void;
+    /**
+     * Called at the start of a layout run.  Sets isRunning flag.
+     * Override to gather initial measurements.
+     */
+    beginLayout(_context: LayoutContext): void;
+    /**
+     * Main calculation phase.  Override in subclasses to compute
+     * child sizes and positions.
+     */
+    calculate(_context: LayoutContext): void;
+    /**
+     * Called after calculation is complete.  Clears flags.
+     * Override to finalize DOM writes.
+     */
+    completeLayout(_context: LayoutContext): void;
+    /**
+     * Called after the entire layout pass is done.
+     * Override for post-layout work (e.g., firing events).
+     */
+    afterLayout(): void;
+    /**
+     * Returns the size policy for a child item.
+     * 'configured' = the item has an explicit width/height config.
+     * 'natural' = the item uses its natural content size.
+     * 'shrinkWrap' = the item wraps its content.
+     */
+    getItemSizePolicy(item: Component): SizePolicy;
+    /**
+     * Renders child components into the target element.
+     * Base implementation renders each item sequentially.
+     */
+    renderItems(items: Component[], target: Element): void;
+}
+
+/**
+ * @framesquared/layout – AutoLayout
+ *
+ * The default layout.  Renders items in DOM order with no special
+ * positioning — items use their natural or configured sizes and
+ * rely on normal CSS flow.
+ *
+ * Alias: 'auto'
+ */
+
+declare class AutoLayout extends Layout {
+    constructor(config?: LayoutConfig);
+    /**
+     * Auto layout: no calculation needed — items use natural CSS flow.
+     */
+    calculate(_context: LayoutContext): void;
+    /**
+     * All items use natural sizing in auto layout.
+     */
+    getItemSizePolicy(_item: Component): SizePolicy;
+}
+
+/**
+ * @framesquared/layout – LayoutRunner
+ *
+ * Singleton that orchestrates layout runs.  Collects invalidation
+ * requests and processes them in batch.  Detects and breaks layout
+ * cycles to prevent infinite loops.
+ *
+ * Integrates with ResizeObserver to automatically invalidate
+ * components when their container elements resize.
+ */
+
+declare class LayoutRunner {
+    private static instance;
+    /** Set of components that need a layout pass. */
+    private pending;
+    /** Whether a run is currently scheduled. */
+    private scheduled;
+    /** Map of element → { observer, component } for ResizeObserver tracking. */
+    private observed;
+    /** Component → ResizeObserver for cleanup. */
+    private componentObservers;
+    private constructor();
+    static getInstance(): LayoutRunner;
+    /**
+     * Marks a component for re-layout.
+     */
+    invalidate(component: Component): void;
+    /**
+     * Returns true if the component is in the pending queue.
+     */
+    isPending(component: Component): boolean;
+    /**
+     * Performs a complete layout pass on all pending components.
+     * Uses iterative processing with cycle detection.
+     */
+    run(): void;
+    /**
+     * Schedules a layout run on the next animation frame.
+     * Multiple calls before the frame coalesce into a single run.
+     */
+    scheduleRun(): void;
+    /**
+     * Clears all pending items without running them.
+     */
+    clear(): void;
+    /**
+     * Starts watching an element for size changes.
+     * When the element resizes, the associated component is invalidated.
+     */
+    observe(component: Component, element: Element): void;
+    /**
+     * Stops watching an element for size changes.
+     */
+    unobserve(component: Component, element: Element): void;
+    private getLayout;
+}
+
+/**
+ * @framesquared/layout – BoxLayout (abstract base)
+ *
+ * Abstract base for HBox and VBox layouts.  Uses CSS Flexbox under
+ * the hood: sets display:flex on the container and translates
+ * align/pack/gap/reverse/overflow to flex properties.  Child items
+ * with `flex` config get flex-grow; fixed-size items get flex-shrink:0.
+ */
+
+type BoxAlign = 'start' | 'center' | 'end' | 'stretch' | 'stretchmax';
+type BoxPack = 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+type BoxOverflow = 'visible' | 'hidden' | 'scroll' | 'wrap';
+interface BoxLayoutConfig extends LayoutConfig {
+    align?: BoxAlign;
+    pack?: BoxPack;
+    gap?: number;
+    overflow?: BoxOverflow;
+    reverse?: boolean;
+}
+declare abstract class BoxLayout extends Layout {
+    protected align: BoxAlign;
+    protected pack: BoxPack;
+    protected gap: number;
+    protected overflow: BoxOverflow;
+    protected reverse: boolean;
+    constructor(config?: BoxLayoutConfig);
+    /**
+     * The CSS flex-direction value.  'row' for HBox, 'column' for VBox.
+     * Subclasses must implement this.
+     */
+    protected abstract getDirection(): string;
+    /**
+     * Returns the primary axis config name for checking fixed size.
+     * 'width' for HBox, 'height' for VBox.
+     */
+    protected abstract getPrimaryAxisProp(): string;
+    /**
+     * Applies CSS Flexbox properties to the container element.
+     */
+    configureContainer(el: HTMLElement): void;
+    /**
+     * Applies flex CSS properties to each child item based on its config.
+     */
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+    calculate(_context: LayoutContext): void;
+    getItemSizePolicy(item: Component): SizePolicy;
+}
+
+/**
+ * @framesquared/layout – HBoxLayout
+ *
+ * Horizontal box layout.  Children are arranged left-to-right
+ * (or right-to-left when reverse=true).  Uses CSS Flexbox with
+ * flex-direction: row.
+ *
+ * Alias: 'hbox'
+ */
+
+declare class HBoxLayout extends BoxLayout {
+    constructor(config?: BoxLayoutConfig);
+    protected getDirection(): string;
+    protected getPrimaryAxisProp(): string;
+}
+
+/**
+ * @framesquared/layout – VBoxLayout
+ *
+ * Vertical box layout.  Children are arranged top-to-bottom
+ * (or bottom-to-top when reverse=true).  Uses CSS Flexbox with
+ * flex-direction: column.
+ *
+ * Alias: 'vbox'
+ */
+
+declare class VBoxLayout extends BoxLayout {
+    constructor(config?: BoxLayoutConfig);
+    protected getDirection(): string;
+    protected getPrimaryAxisProp(): string;
+}
+
+/**
+ * @framesquared/layout – FitLayout
+ *
+ * Single child fills the entire container.  If multiple children
+ * are present, only the first is visible.
+ *
+ * Alias: 'fit'
+ */
+
+declare class FitLayout extends Layout {
+    constructor(config?: LayoutConfig);
+    configureContainer(el: HTMLElement): void;
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+}
+
+/**
+ * @framesquared/layout – CardLayout
+ *
+ * Like FitLayout but supports multiple children — only one is visible
+ * at a time.  Provides next/prev navigation and fires activate/deactivate.
+ *
+ * Alias: 'card'
+ */
+
+interface CardLayoutConfig extends LayoutConfig {
+    activeItem?: number;
+}
+declare class CardLayout extends Layout {
+    private activeIndex;
+    private listeners;
+    constructor(config?: CardLayoutConfig);
+    /** Subscribe to events. */
+    on(event: string, fn: Function): void;
+    /** Unsubscribe. */
+    un(event: string, fn: Function): void;
+    private fire;
+    configureContainer(el: HTMLElement): void;
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+    getActiveItem(): Component | undefined;
+    setActiveItem(item: number | Component): void;
+    next(): Component;
+    prev(): Component;
+    private getOwnerItems;
+}
+
+/**
+ * @framesquared/layout – AnchorLayout
+ *
+ * Children sized relative to container using anchor strings:
+ *   '100% 50%' → 100% width, 50% height
+ *   '-50 -100'  → calc(100% - 50px), calc(100% - 100px)
+ *   '-50'       → width offset only
+ *
+ * Alias: 'anchor'
+ */
+
+declare class AnchorLayout extends Layout {
+    constructor(config?: LayoutConfig);
+    configureContainer(el: HTMLElement): void;
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+}
+
+/**
+ * @framesquared/layout – BorderLayout
+ *
+ * Classic border layout with 5 regions: north, south, east, west, center.
+ * Uses CSS Grid under the hood.  Center is required and fills remaining space.
+ *
+ * Alias: 'border'
+ */
+
+interface BorderLayoutConfig extends LayoutConfig {
+    split?: boolean;
+}
+declare class BorderLayout extends Layout {
+    constructor(config?: BorderLayoutConfig);
+    configureContainer(el: HTMLElement): void;
+    applyItemStyles(items: Component[], target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+}
+
+/**
+ * @framesquared/layout – ColumnLayout
+ *
+ * Arranges children in columns.  Items with `columnWidth` (0–1)
+ * get a percentage of the container width.  Fixed-width items
+ * keep their configured width.  Uses CSS Flexbox with wrap.
+ *
+ * Alias: 'column'
+ */
+
+declare class ColumnLayout extends Layout {
+    constructor(config?: LayoutConfig);
+    configureContainer(el: HTMLElement): void;
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+}
+
+/**
+ * @framesquared/layout – TableLayout
+ *
+ * Renders children in a grid structure using CSS Grid.
+ * Supports `columns`, `colspan`, and `rowspan` on items.
+ *
+ * Alias: 'table'
+ */
+
+interface TableLayoutConfig extends LayoutConfig {
+    columns?: number;
+}
+declare class TableLayout extends Layout {
+    private columns;
+    constructor(config?: TableLayoutConfig);
+    configureContainer(el: HTMLElement): void;
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+}
+
+/**
+ * @framesquared/layout – AbsoluteLayout
+ *
+ * Positions children absolutely within the container using x/y configs.
+ *
+ * Alias: 'absolute'
+ */
+
+declare class AbsoluteLayout extends Layout {
+    constructor(config?: LayoutConfig);
+    configureContainer(el: HTMLElement): void;
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+}
+
+/**
+ * @framesquared/layout – AccordionLayout
+ *
+ * Vertical stack where only one item is expanded at a time
+ * (or multiple with multi:true).  Expanded items get flex:1
+ * when fill:true.  Collapsed items show only their header.
+ *
+ * Alias: 'accordion'
+ */
+
+interface AccordionLayoutConfig extends LayoutConfig {
+    multi?: boolean;
+    fill?: boolean;
+    animate?: boolean;
+}
+declare class AccordionLayout extends Layout {
+    private multi;
+    private fill;
+    private expandedSet;
+    constructor(config?: AccordionLayoutConfig);
+    configureContainer(el: HTMLElement): void;
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+    isExpanded(item: Component): boolean;
+    expand(item: Component): void;
+    collapse(item: Component): void;
+    toggle(item: Component): void;
+    private applyExpansionState;
+    private getOwnerItems;
+}
+
+/**
+ * @framesquared/layout – ResponsivePlugin
+ *
+ * Monitors viewport size using window.matchMedia() and applies
+ * different component configs at different breakpoints.
+ *
+ * Supports both standard media queries and shorthand expressions:
+ *   '(max-width: 599px)'              → standard CSS media query
+ *   'width < 600'                      → parsed to (max-width: 599px)
+ *   'width >= 600 && width < 1024'    → parsed to (min-width: 600px) and (max-width: 1023px)
+ *   'width >= 1024'                   → parsed to (min-width: 1024px)
+ */
+
+interface ResponsiveConfig {
+    responsiveConfig: Record<string, Record<string, unknown>>;
+}
+declare class ResponsivePlugin {
+    private config;
+    private owner;
+    private entries;
+    private activeConfigs;
+    constructor(config: ResponsiveConfig);
+    getOwner(): Component | null;
+    /**
+     * Initialise the plugin with its owner component.
+     * Sets up matchMedia listeners and applies initial state.
+     */
+    init(owner: Component): void;
+    /**
+     * Clean up all media query listeners.
+     */
+    destroy(): void;
+}
+
+/**
+ * @framesquared/layout – ResponsiveColumnLayout
+ *
+ * Columns that automatically reflow based on container width.
+ * Uses CSS Grid with auto-fill and minmax() for responsive columns
+ * without JavaScript resize calculation.
+ *
+ * Config:
+ *   minColumnWidth — minimum width of each column
+ *   gap            — spacing between items
+ *   maxColumns     — optional maximum number of columns
+ *
+ * Items with `columnSpan: N` span multiple grid columns.
+ *
+ * Alias: 'responsivecolumn'
+ */
+
+interface ResponsiveColumnLayoutConfig extends LayoutConfig {
+    minColumnWidth: number;
+    gap?: number;
+    maxColumns?: number;
+}
+declare class ResponsiveColumnLayout extends Layout {
+    private minColumnWidth;
+    private gap;
+    private maxColumns;
+    constructor(config: ResponsiveColumnLayoutConfig);
+    /**
+     * Configures the container element with CSS Grid responsive columns.
+     */
+    configureContainer(el: HTMLElement): void;
+    /**
+     * Applies columnSpan to items that need to span multiple columns.
+     */
+    applyItemStyles(items: Component[], _target: Element): void;
+    renderItems(items: Component[], target: Element): void;
+}
+
+export { AbsoluteLayout, AccordionLayout, type AccordionLayoutConfig, AnchorLayout, AutoLayout, BorderLayout, type BorderLayoutConfig, type BoxAlign, BoxLayout, type BoxLayoutConfig, type BoxOverflow, type BoxPack, CardLayout, type CardLayoutConfig, ColumnLayout, FitLayout, HBoxLayout, Layout, type LayoutConfig, LayoutContext, LayoutRunner, ResponsiveColumnLayout, type ResponsiveColumnLayoutConfig, type ResponsiveConfig, ResponsivePlugin, type SizePolicy, TableLayout, type TableLayoutConfig, VBoxLayout };