optikos 0.0.0-stage → 0.2.0

package/dist/types/components/form/form/form.d.ts

@@ -0,0 +1,68 @@
+import { Container, type ContainerConfig } from '../../../core/container.js';
+import { Field } from '../../../core/field.js';
+import type { Model } from '../../../data/model.js';
+import type { Component } from '../../../core/component.js';
+import type { LayoutSpec } from '../../../layout/layout.js';
+export interface FormTab {
+    title: string;
+    icon?: string;
+    items: ContainerConfig['items'];
+    /** Default: two columns (one on a phone). */
+    layout?: LayoutSpec;
+}
+export interface FormConfig extends ContainerConfig {
+    /** Shortcut: the fields in tabs, still one form (one `getValues`, one `validate`, one dirty). */
+    tabs?: FormTab[];
+    /** Default `labelPos` for fields that do not set their own. */
+    labelPos?: 'top' | 'left';
+    /** Width of the labels on the left (`labelPos: 'left'`), so they line up in a column. Number = px. */
+    labelWidth?: number | string;
+    /** Shortcut for a responsive grid layout (one column on narrow screens); items take `colspan` (a number or `'full'`). */
+    columns?: number;
+    readonly?: boolean;
+}
+export declare class Form extends Container<FormConfig> {
+    protected baseCls: string;
+    protected tag: 'form';
+    /** Components hidden by their `showIf` rule: their fields do not count (no validation, not in `getValues`). */
+    private ruledOut;
+    private dirty;
+    constructor(config?: FormConfig);
+    protected build(): HTMLElement;
+    protected onRender(): void;
+    getFields(): Field<any>[];
+    getField(name: string): Field<any> | undefined;
+    /** Nested object built from field names (`address.city` → `{ address: { city } }`). Fields hidden by `showIf` are left out. */
+    getValues(opts?: {
+        dirtyOnly?: boolean;
+    }): Record<string, any>;
+    /** The fields that count: not inside something its `showIf` rule hid. */
+    private counted;
+    /** A field changed: rerun the `showIf`/`enableIf` rules and say when the form as a whole became (un)changed. */
+    private changed;
+    /** Shows/hides and enables/disables every item that has a rule, from the current values (hidden fields included). */
+    applyRules(): void;
+    /** Brings a field into view (opening its tab or step) and focuses it. */
+    focusField(field: Field<any>): void;
+    /** Sets the fields present in `values` (silently). */
+    setValues(values: Record<string, any>): void;
+    /** Fills the form from a plain object or a Model, and makes it the "clean" state. */
+    load(record: Record<string, any> | Model): void;
+    /** Brings a field into view: asks every ancestor that shows one child at a time (Tabs, a card layout) to show the branch. */
+    protected reveal(field: Component): void;
+    /** Error counts and "changed" dots on the headers of every Tabs inside the form. */
+    protected syncTabs(): void;
+    /** Writes the changed fields back into a Model. */
+    updateRecord(model: Model): void;
+    markClean(): void;
+    reset(): void;
+    isDirty(): boolean;
+    isValid(): boolean;
+    clearErrors(): void;
+    /** Validates every field that counts (marks errors) and focuses the first invalid one. */
+    validate(): boolean;
+    submit(): boolean;
+    /** Width of the labels on the left (number = px); they line up in a column. */
+    setLabelWidth(width: number | string): void;
+    setReadonly(readonly: boolean): void;
+}

package/dist/types/components/form/formactions/formactions.d.ts

@@ -0,0 +1,34 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+import { type ButtonConfig } from '../../base/button/button.js';
+import type { Form } from '../form/form.js';
+export interface FormActionsConfig extends ComponentConfig {
+    submitText?: string;
+    /** `false` hides Cancel. */
+    cancelText?: string | false;
+    /** Extra buttons, before Cancel. */
+    buttons?: ButtonConfig[];
+    /** Sticks to the bottom of the scrolling area. */
+    sticky?: boolean;
+    /** Save is disabled until the form has changes. */
+    requireChanges?: boolean;
+    /** The "Unsaved changes" line. Default true. */
+    status?: boolean;
+}
+/** The form's action bar: Cancel (resets), Save (submits) and an "Unsaved changes" status. */
+export declare class FormActions extends Component<FormActionsConfig> {
+    protected baseCls: string;
+    private statusEl;
+    private buttonsEl;
+    private form?;
+    private save;
+    private cancel?;
+    private extra;
+    protected build(): HTMLDivElement;
+    protected onRender(): void;
+    private paint;
+    getForm(): Form | undefined;
+    setSubmitText(text: string): void;
+    /** The Cancel button's text, or `false` to hide it. Cancel emits `cancel` (return false to keep the changes), then resets. */
+    setCancelText(text: string | false): void;
+    setSticky(sticky: boolean): void;
+}

package/dist/types/components/form/formerrors/formerrors.d.ts

@@ -0,0 +1,23 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+import { Field } from '../../../core/field.js';
+export interface FormErrorsConfig extends ComponentConfig {
+    /** The heading: a function of the number of problems, or a fixed text. */
+    title?: string | ((n: number) => string);
+    /** Take the focus after a failed submit (instead of the first invalid field). */
+    focus?: boolean;
+}
+/** An error summary: after a failed validation, every problem as a button that takes you to its field. */
+export declare class FormErrors extends Component<FormErrorsConfig> {
+    protected baseCls: string;
+    private titleEl;
+    private listEl;
+    private form?;
+    /** Shown only once the form was validated with errors (not while the user is still filling it in). */
+    private active;
+    protected build(): HTMLDivElement;
+    protected onRender(): void;
+    /** The form fields that have an error, in order. */
+    getErrors(): Field<any>[];
+    /** Redraws the list from the current errors (hides when there are none). */
+    refresh(): void;
+}

package/dist/types/components/form/formsection/formsection.d.ts

@@ -0,0 +1,26 @@
+import { Container, type ContainerConfig } from '../../../core/container.js';
+export interface FormSectionConfig extends ContainerConfig {
+    title?: string;
+    description?: string;
+    /** Title and description in a column beside the fields (default); `false` stacks them above. */
+    aside?: boolean;
+    /** Shortcut for a responsive grid layout of the fields; items take `colspan` (a number or `'full'`). */
+    columns?: number;
+    /** A rule between consecutive sections. Default true. */
+    divider?: boolean;
+}
+/** A titled part of a long form, "settings page" style: title and description on the left, fields on the right. */
+export declare class FormSection extends Container<FormSectionConfig> {
+    protected baseCls: string;
+    protected tag: 'section';
+    private titleEl;
+    private descEl;
+    private bodyEl;
+    getBody(): HTMLElement;
+    protected build(): HTMLElement;
+    protected onRender(): void;
+    setTitle(title: string): void;
+    setDescription(text: string): void;
+    /** Title beside the fields (true) or always above them (false). */
+    setAside(aside: boolean): void;
+}

package/dist/types/components/form/inputgroup/inputgroup.d.ts

@@ -0,0 +1,28 @@
+import { Container, type ContainerConfig } from '../../../core/container.js';
+import { Field } from '../../../core/field.js';
+/** Text joined to the input (`'R$'`, `'.com'`), or a button. */
+export type InputAffix = string | {
+    icon?: string;
+    text?: string;
+    ariaLabel?: string;
+    handler?: (field: Field<any>) => void;
+};
+export interface InputGroupConfig extends ContainerConfig {
+    prefix?: InputAffix;
+    suffix?: InputAffix;
+}
+/** Joins text or buttons to a field's input box. The field keeps its label, help, error, name and value. */
+export declare class InputGroup extends Container<InputGroupConfig> {
+    protected baseCls: string;
+    private affixes;
+    /** The field inside. */
+    getField(): Field<any> | undefined;
+    protected onRender(): void;
+    /** Text affixes describe the input, after the field's own help and error. */
+    private describe;
+    /** `[prefix][the field's input box][suffix]` inside the field's control. */
+    private paint;
+    private track;
+    setPrefix(prefix: InputAffix | undefined): void;
+    setSuffix(suffix: InputAffix | undefined): void;
+}

package/dist/types/components/form/stepform/stepform.d.ts

@@ -0,0 +1,64 @@
+import { Form, type FormConfig } from '../form/form.js';
+import { type ContainerConfig } from '../../../core/container.js';
+import type { LayoutSpec } from '../../../layout/layout.js';
+import { Stepper } from '../../navigation/stepper/stepper.js';
+import '../../layout/container/container.js';
+export interface FormStep {
+    title: string;
+    description?: string;
+    icon?: string;
+    /** May be left alone: the stepper says "optional" (its fields are still validated if filled wrongly). */
+    optional?: boolean;
+    items: ContainerConfig['items'];
+    /** Default: two columns (one on a phone). */
+    layout?: LayoutSpec;
+}
+export interface StepFormConfig extends FormConfig {
+    steps: FormStep[];
+    /** Moving forward validates the steps on the way. `false` lets the user click any step. Default true. */
+    linear?: boolean;
+    /** Adds a last "Review" step with a summary of the values; a function renders the summary yourself. */
+    review?: boolean | ((values: Record<string, any>, form: StepForm) => string | Node);
+    reviewTitle?: string;
+    backText?: string;
+    nextText?: string;
+    finishText?: string;
+    /** Shows a Cancel button (fires `cancel`). */
+    cancelText?: string;
+    /** On a new step, focus its first field (a phone keyboard pops up). Default false: the step panel gets the focus. */
+    autoFocus?: boolean;
+}
+/** One form, several steps: a Stepper on top, one step at a time, Back / Next / Finish, validation per step and an optional review. */
+export declare class StepForm extends Form {
+    protected baseCls: string;
+    private stepper;
+    private body;
+    private pane?;
+    private backBtn;
+    private nextBtn;
+    private finishBtn;
+    private index;
+    constructor(config: StepFormConfig);
+    private cfg;
+    private count;
+    private real;
+    getStep(): number;
+    getStepCount(): number;
+    getStepper(): Stepper;
+    private stepFields;
+    /** Validates one step's fields (marks the errors, sets its state on the stepper). */
+    validateStep(i: number): boolean;
+    /** Moves to a step. Forward with `linear` validates the steps on the way and stops at the first invalid one. Returns whether it got there. */
+    goTo(j: number): boolean;
+    next(): boolean;
+    back(): boolean;
+    /** The card layout changed the visible step (by `goTo`, or because `validate` brought an invalid field into view). */
+    private onActivate;
+    private refreshReview;
+    /** What the user sees for a field (its display text; ticks for booleans, dots for passwords). */
+    private show_;
+    /** Enter and the Finish button: Next on every step but the last; on the last, validate everything and `finish`. */
+    submit(): boolean;
+    /** Clears the values and goes back to the first step. */
+    reset(): void;
+}

package/dist/types/components/form.d.ts

@@ -0,0 +1 @@
+export * from '../components/form/form/form.js';

package/dist/types/components/formactions.d.ts

@@ -0,0 +1 @@
+export * from '../components/form/formactions/formactions.js';

package/dist/types/components/formerrors.d.ts

@@ -0,0 +1 @@
+export * from '../components/form/formerrors/formerrors.js';

package/dist/types/components/formsection.d.ts

@@ -0,0 +1 @@
+export * from '../components/form/formsection/formsection.js';

package/dist/types/components/grid.d.ts

@@ -0,0 +1 @@
+export * from '../components/data/grid/grid.js';

package/dist/types/components/icon.d.ts

@@ -0,0 +1 @@
+export * from '../components/base/icon/icon.js';

package/dist/types/components/inputgroup.d.ts

@@ -0,0 +1 @@
+export * from '../components/form/inputgroup/inputgroup.js';

package/dist/types/components/label.d.ts

@@ -0,0 +1 @@
+export * from '../components/base/label/label.js';

package/dist/types/components/layout/container/container.d.ts

@@ -0,0 +1 @@
+export { Container, type ContainerConfig } from '../../../core/container.js';

package/dist/types/components/layout/fieldset/fieldset.d.ts

@@ -0,0 +1,30 @@
+import { Container, type ContainerConfig } from '../../../core/container.js';
+export interface FieldSetConfig extends ContainerConfig {
+    title?: string;
+    /** A line under the legend, read as the group's description. */
+    description?: string;
+    /** `box` (a framed group, default), `line` (a rule under the legend, no frame) or `plain` (just the legend). */
+    variant?: 'box' | 'line' | 'plain';
+    /** Shortcut for a responsive grid layout; items take `colspan` (a number or `'full'`). */
+    columns?: number;
+    collapsible?: boolean;
+    collapsed?: boolean;
+}
+export declare class FieldSet extends Container<FieldSetConfig> {
+    protected baseCls: string;
+    protected tag: 'fieldset';
+    private legend;
+    private bodyEl;
+    private toggleBtn?;
+    private descEl;
+    getBody(): HTMLElement;
+    protected build(): HTMLElement;
+    protected onRender(): void;
+    setTitle(title: string): void;
+    setDescription(text: string): void;
+    setVariant(variant: 'box' | 'line' | 'plain'): void;
+    setCollapsed(collapsed: boolean): void;
+    collapse(): void;
+    expand(): void;
+    toggle(): void;
+}

package/dist/types/components/layout/panel/panel.d.ts

@@ -0,0 +1,53 @@
+import { Container, type ContainerConfig } from '../../../core/container.js';
+import './reload.js';
+import { type ToolbarConfig } from '../toolbar/toolbar.js';
+import type { ButtonConfig } from '../../base/button/button.js';
+export interface PanelTool {
+    icon: string;
+    label: string;
+    handler?: (panel: Panel, ev: MouseEvent) => void;
+}
+export interface PanelConfig extends ContainerConfig {
+    title?: string;
+    icon?: string;
+    collapsible?: boolean;
+    collapsed?: boolean;
+    closable?: boolean;
+    closeAction?: 'destroy' | 'hide';
+    /** A ↻ button in the header that calls `onReload` (a Promise shows the loading mask until it settles). */
+    reloadable?: boolean;
+    onReload?: (panel: Panel) => void | Promise<unknown>;
+    tools?: PanelTool[];
+    tbar?: ToolbarConfig['items'];
+    bbar?: ToolbarConfig['items'];
+    buttons?: ButtonConfig[];
+    bodyCls?: string;
+}
+export declare class Panel<C extends PanelConfig = PanelConfig> extends Container<C> {
+    protected baseCls: string;
+    protected headerEl: HTMLElement;
+    protected titleEl: HTMLElement;
+    protected bodyEl: HTMLElement;
+    private toolsEl;
+    private iconHost;
+    private toggleBtn?;
+    private bars;
+    private bodyId;
+    private titleId;
+    getBody(): HTMLElement;
+    protected build(): HTMLDivElement;
+    protected onRender(): void;
+    private addTool;
+    private updateHeader;
+    /** Runs `onReload` (`before-reload` can cancel); a returned Promise keeps the loading mask (and a turning ↻) until it settles. */
+    reload(): Promise<boolean>;
+    setTitle(title: string): void;
+    setIcon(name: string): void;
+    /** Collapses/expands without events. Use `collapse()`/`expand()` for the full behavior. */
+    setCollapsed(collapsed: boolean): void;
+    collapse(): void;
+    expand(): void;
+    toggle(): void;
+    close(): void;
+    protected onDestroy(): void;
+}

package/dist/types/components/layout/panel/reload.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/components/layout/spacer/spacer.d.ts

@@ -0,0 +1,12 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+export interface SpacerConfig extends ComponentConfig {
+    /** Renders a vertical separator line. */
+    line?: boolean;
+}
+/** Without `width`/`flex` it takes the free space (`flex: 1`), pushing the next items away. */
+export declare class Spacer extends Component<SpacerConfig> {
+    protected baseCls: string;
+    protected tag: 'span';
+    protected onRender(): void;
+    setLine(line: boolean): void;
+}

package/dist/types/components/layout/toolbar/toolbar.d.ts

@@ -0,0 +1,15 @@
+import { Container, type ContainerConfig } from '../../../core/container.js';
+import { type AnyConfig } from '../../../core/registry.js';
+import '../spacer/spacer.js';
+export interface ToolbarConfig extends ContainerConfig {
+    vertical?: boolean;
+}
+/** Items may be `'->'` (fill space), `'-'` (separator) or `' '` (small gap). */
+export declare class Toolbar extends Container<ToolbarConfig> {
+    protected baseCls: string;
+    private rover?;
+    protected shorthand(s: string): AnyConfig;
+    protected build(): HTMLElement;
+    protected onRender(): void;
+    notifyMount(): void;
+}

package/dist/types/components/layout/viewport/viewport.d.ts

@@ -0,0 +1,7 @@
+import { Container, type ContainerConfig } from '../../../core/container.js';
+/** Root container that fills the window. Only one can exist at a time. */
+export declare class Viewport extends Container<ContainerConfig> {
+    protected baseCls: string;
+    constructor(config?: ContainerConfig);
+    protected onRender(): void;
+}

package/dist/types/components/listbox.d.ts

@@ -0,0 +1 @@
+export * from '../components/fields/listbox/listbox.js';

package/dist/types/components/lookupfield.d.ts

@@ -0,0 +1 @@
+export * from '../components/fields/lookupfield/lookupfield.js';

package/dist/types/components/menu.d.ts

@@ -0,0 +1 @@
+export * from '../components/overlays/menu/menu.js';

package/dist/types/components/messagebox.d.ts

@@ -0,0 +1 @@
+export * from '../components/overlays/messagebox/messagebox.js';

package/dist/types/components/navigation/breadcrumb/breadcrumb.d.ts

@@ -0,0 +1,32 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+export interface BreadcrumbItem {
+    text: string;
+    icon?: string;
+    /** Renders a real link (native navigation, middle-click, copy link). */
+    href?: string;
+    handler?: (item: BreadcrumbItem) => void;
+}
+export interface BreadcrumbConfig extends ComponentConfig {
+    items?: BreadcrumbItem[];
+    /** More items than this collapse the middle into a "…" menu. Minimum 3, default 4. */
+    maxItems?: number;
+    separator?: string;
+}
+export declare class Breadcrumb extends Component<BreadcrumbConfig> {
+    protected baseCls: string;
+    protected tag: 'nav';
+    private list;
+    private menu?;
+    protected onRender(): void;
+    private items;
+    /** Indexes hidden behind the "…" button (empty when everything fits). */
+    private collapsed;
+    private paint;
+    /** Runs `before-navigate` / handler / `navigate`. Returns false when cancelled. */
+    private go;
+    private showHidden;
+    setItems(items: BreadcrumbItem[]): void;
+    setMaxItems(max: number): void;
+    /** Any text, e.g. `'/'` or `'›'`. */
+    setSeparator(separator: string): void;
+}

package/dist/types/components/navigation/navmenu/navmenu.d.ts

@@ -0,0 +1,63 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+export interface NavItem {
+    id: string;
+    text: string;
+    icon?: string;
+    badge?: string | number;
+    items?: NavItem[];
+    disabled?: boolean;
+    hidden?: boolean;
+    /** Groups: start open. */
+    expanded?: boolean;
+    data?: unknown;
+}
+export interface NavMenuConfig extends ComponentConfig {
+    items?: NavItem[];
+    /** id of the active leaf. */
+    active?: string;
+    /** Rail: icons only. */
+    collapsed?: boolean;
+    /** Opening a group closes the others at its level. */
+    accordion?: boolean;
+}
+/** Sidebar tree: groups that open and close, one active leaf, badges, rail mode, filter and the APG tree keyboard model. */
+export declare class NavMenu extends Component<NavMenuConfig> {
+    protected baseCls: string;
+    protected tag: 'nav';
+    private items;
+    private open;
+    private active?;
+    private query;
+    private focusId?;
+    private root;
+    protected onRender(): void;
+    getItem(id: string, list?: NavItem[]): NavItem | undefined;
+    private parentsOf;
+    private openParents;
+    private matches;
+    /** Visible = not hidden, matches the filter, and a group has at least one visible child. */
+    private visible;
+    private isOpen;
+    private paint;
+    private node;
+    private activate;
+    private select;
+    /** Marks a leaf as the active page (and opens its parents). Does not emit `select`. */
+    setActive(id: string | undefined): void;
+    getActive(): NavItem | undefined;
+    expand(id: string): void;
+    collapse(id: string): void;
+    toggle(id: string): void;
+    private siblings;
+    expandAll(): void;
+    collapseAll(): void;
+    setItems(items: NavItem[]): void;
+    /** Changes an item in place (a badge, a label, disabled...). */
+    updateItem(id: string, patch: Partial<NavItem>): void;
+    setCollapsed(collapsed: boolean): void;
+    /** Hides what does not match and opens the groups that have a match; empty text clears the filter. */
+    filter(text: string): void;
+    private rows;
+    private focusRow;
+    private onKey;
+}

package/dist/types/components/navigation/stepper/stepper.d.ts

@@ -0,0 +1,31 @@
+import { Component, type ComponentConfig } from '../../../core/component.js';
+export interface Step {
+    id?: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    optional?: boolean;
+}
+export type StepState = 'pending' | 'done' | 'error';
+export interface StepperConfig extends ComponentConfig {
+    steps?: Step[];
+    active?: number;
+    /** Steps can be clicked. Default true. */
+    clickable?: boolean;
+}
+/** Where you are in a multi-step process: numbered steps with done / current / error states. */
+export declare class Stepper extends Component<StepperConfig> {
+    protected baseCls: string;
+    protected tag: 'nav';
+    private list;
+    private active;
+    private states;
+    protected onRender(): void;
+    private steps;
+    private paint;
+    setActive(i: number): void;
+    getActive(): number;
+    setStepState(i: number, state: StepState): void;
+    getStepState(i: number): StepState;
+    setSteps(steps: Step[]): void;
+}

package/dist/types/components/navigation/tabs/tabs.d.ts

@@ -0,0 +1,57 @@
+import { Container, type ContainerConfig } from '../../../core/container.js';
+import '../../layout/panel/reload.js';
+import { Component } from '../../../core/component.js';
+import { type AnyConfig } from '../../../core/registry.js';
+export interface TabsConfig extends ContainerConfig {
+    /** Initially active tab (index or id). */
+    active?: number | string;
+    position?: 'top' | 'left';
+    /** Build a panel's DOM only the first time its tab is activated. Default true. */
+    lazy?: boolean;
+    /** Default `closable` for tabs. */
+    closable?: boolean;
+    /** Default `reloadable` for tabs: a ↻ in the tab that calls the panel's `onReload`. */
+    reloadable?: boolean;
+}
+/**
+ * Items are the panels. Each may carry `title`, `icon`, `closable` and `disabled` for its tab header.
+ * Tabs reuse the `card` layout of Container for the panels.
+ */
+export declare class Tabs extends Container<TabsConfig> {
+    protected baseCls: string;
+    private barEl;
+    private panelsEl;
+    private tabs;
+    private pending;
+    private rover?;
+    constructor(config?: TabsConfig);
+    getBody(): HTMLElement;
+    protected build(): HTMLDivElement;
+    protected onRender(): void;
+    private forcing?;
+    /** Lazy panels (everything but the active one) are attached the first time they are activated. */
+    protected attach(p: Component, index: number): void;
+    /** Builds a pending panel's DOM now. */
+    private ensure;
+    private tabConfig;
+    private addHeader;
+    private syncHeaders;
+    getActive(): Component | undefined;
+    /** Activates a tab (instance, id or index). `before-change` can cancel. */
+    setActive(tab: Component | string | number): void;
+    insert(index: number, item: AnyConfig | Component | string): Component;
+    /**
+     * Reloads a tab: calls its panel's `onReload` (`before-reload` can cancel). While a returned Promise is pending the panel
+     * shows its loading mask and the tab's ↻ spins; `reload(panel)` fires when it is done.
+     */
+    reloadTab(tab: Component | string | number): Promise<boolean>;
+    /** Closes a tab (`before-close` can cancel). The neighbor becomes active. */
+    closeTab(tab: Component | string | number): void;
+    remove(child: Component | string | number, destroy?: boolean): Component | undefined;
+    /** Marks a tab header: a badge with the number of errors in its panel and a dot while something in it changed. */
+    setTabState(tab: Component, state: {
+        errors?: number;
+        dirty?: boolean;
+    }): void;
+    setTitle(tab: Component, title: string): void;
+}

package/dist/types/components/navmenu.d.ts

@@ -0,0 +1 @@
+export * from '../components/navigation/navmenu/navmenu.js';

package/dist/types/components/numberfield.d.ts

@@ -0,0 +1 @@
+export * from '../components/fields/numberfield/numberfield.js';