@navette-js/schemas 1.0.0-beta.4 → 1.0.0-beta.5

package/lib/index.d.ts

@@ -29,6 +29,13 @@ export declare abstract class Component {
     protected _keyName: string | null;
     protected _hidden: Lazy<boolean, ComponentContext>;
     protected _visible: Lazy<boolean, ComponentContext>;
+    protected _lazyLoaded: Lazy<boolean, ComponentContext>;
+    /**
+     * Renders the component's content (its child schema) only when it enters the viewport, in a separate request: a loading
+     * indicator is shown meanwhile. The component needs a unique key (a heading, or `key()`).
+     */
+    lazyLoaded(condition?: Lazy<boolean, ComponentContext>): this;
+    getLazyLoadedCondition(): Lazy<boolean, ComponentContext>;
     protected _columnSpan: ColumnSpan;
     protected _extraAttributes: Record<string, string>;
     protected _columnStart: ColumnPlacement[];
@@ -104,6 +111,14 @@ export declare class Schema {
     private _rootHeadingLevel;
     constructor(livewire: SchemaHost);
     static make(livewire: SchemaHost): Schema;
+    private _lazy;
+    private _lazyKey;
+    /** Renders the components only when the schema enters the viewport (see `Component.lazyLoaded()`). */
+    lazyLoaded(condition?: boolean | (() => boolean | Promise<boolean>)): this;
+    isLazyLoaded(): Promise<boolean>;
+    /** Key identifying a lazy schema (its own key by default; a layout component's child schema uses the component's key). */
+    lazyKey(key: string | null): this;
+    getLazyKey(): string;
     key(key: string): this;
     components(components: Component[]): this;
     schema(components: Component[]): this;
@@ -152,6 +167,8 @@ export declare class Schema {
     /** Same, without hidden components or their descendants: a field inside a hidden section is neither validated nor saved. */
     getVisibleFlatComponents(): Promise<Component[]>;
     toHtml(): Promise<string>;
+    /** Placeholder of a lazy schema: a loading indicator that asks for the schema when it enters the viewport. */
+    toDeferredLoadingHtml(): string;
 }
 /** Child schema of a layout component: shares the parent's key and state path, without being a root. */
 export declare function childSchema(parent: Component, components: Component[]): Schema;
@@ -172,6 +189,9 @@ export declare class Group extends Component {
     static make(children?: Component[]): Group;
     schema(components: Component[]): this;
     columns(columns: Record<string, number> | number | null): this;
+    /** State path of the components, relative to the container (`address`: their state lives under `address.*`). */
+    statePath(path: string | null): this;
+    hasStatePath(): boolean;
     getChildSchemas(): Schema[];
     toHtml(): Promise<string>;
 }
@@ -216,6 +236,7 @@ export declare class Section extends Component {
     private _contentBefore;
     private _compact;
     private _secondary;
+    private _divided;
     private _contained;
     private _collapsible;
     private _collapsed;
@@ -242,6 +263,8 @@ export declare class Section extends Component {
     compact(condition?: Lazy<boolean, ComponentContext>): this;
     /** Less contrasting background, for a section on a background of the same color (nested sections…). */
     secondary(condition?: Lazy<boolean, ComponentContext>): this;
+    /** Dividing lines between the components of the content. */
+    divided(condition?: Lazy<boolean, ComponentContext>): this;
     /** `false`: no card around the section. */
     contained(condition?: Lazy<boolean, ComponentContext>): this;
     /** Collapsible by clicking its header; `collapsed()` starts it collapsed. */
@@ -395,16 +418,37 @@ export interface Renderable {
     toHtml(ctx: ComponentContext): Promise<string>;
 }
 /** Row of actions in a schema. */
+/** Content placed around a component: text, components and actions, or a function of the context returning them. */
+export type ComponentSlot = Lazy<string | HtmlString | InlineItem | (string | HtmlString | InlineItem)[] | null, ComponentContext>;
 export declare class Actions extends Component {
     private actions;
     private _fullWidth;
     private _alignment;
+    private _label;
+    private _beforeLabel;
+    private _afterLabel;
+    private _aboveContent;
+    private _belowContent;
     constructor(actions: Renderable[]);
     static make(actions: Renderable[]): Actions;
     fullWidth(condition?: boolean): this;
     alignment(alignment: string | null): this;
+    /** Label shown above the actions, like a field label. */
+    label(label: Lazy<string | null, ComponentContext>): this;
+    /** Text, components or actions before the label. */
+    beforeLabel(content: ComponentSlot): this;
+    /** Text, components or actions after the label (a status badge…). */
+    afterLabel(content: ComponentSlot): this;
+    /** Text, components or actions between the label and the actions. */
+    aboveContent(content: ComponentSlot): this;
+    /** Text, components or actions below the actions. */
+    belowContent(content: ComponentSlot): this;
+    /** Actions this component exposes for mounting (its key is sent with each of them). */
+    getActions(): Renderable[];
     toHtml(): Promise<string>;
 }
+/** Renders a slot of a component as an inline row: strings become `Text` components. */
+export declare function renderSlot(parent: Component, content: ComponentSlot, mountKey?: string | null): Promise<string>;
 /** Color manager used outside a panel; inside a panel, the host panel's manager takes precedence. */
 export declare const useColorManager: (manager: ColorManager) => void;
 /** Item in an inline row: a schema component or an action. */

package/lib/index.js

@@ -1,6 +1,6 @@
 // @navette-js/schemas — Schema, Component and the layout components.
 // Each component renders in two steps: async property resolution, then a synchronous EJS view (ADR 0003).
-import { Attributes, HtmlString, cls, e, evaluate, icon, js, renderHook, views, configured, configureUsing } from '@navette-js/support';
+import { Attributes, HtmlString, cls, e, evaluate, icon, js, loadingIndicator, renderHook, views, configured, configureUsing } from '@navette-js/support';
 import { t } from '@navette-js/support/i18n';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
@@ -42,6 +42,13 @@ export class Component {
     _keyName = null;
     _hidden = false;
     _visible = true;
+    _lazyLoaded = false;
+    /**
+     * Renders the component's content (its child schema) only when it enters the viewport, in a separate request: a loading
+     * indicator is shown meanwhile. The component needs a unique key (a heading, or `key()`).
+     */
+    lazyLoaded(condition = true) { this._lazyLoaded = condition; return this; }
+    getLazyLoadedCondition() { return this._lazyLoaded; }
     _columnSpan = { default: 1 };
     _extraAttributes = {};
     _columnStart = [];
@@ -152,6 +159,14 @@ export class Schema {
     _rootHeadingLevel = 2;
     constructor(livewire) { this.livewire = livewire; }
     static make(livewire) { return configured(new Schema(livewire)); }
+    _lazy = false;
+    _lazyKey = null;
+    /** Renders the components only when the schema enters the viewport (see `Component.lazyLoaded()`). */
+    lazyLoaded(condition = true) { this._lazy = condition; return this; }
+    async isLazyLoaded() { return Boolean(typeof this._lazy === 'function' ? await this._lazy() : this._lazy); }
+    /** Key identifying a lazy schema (its own key by default; a layout component's child schema uses the component's key). */
+    lazyKey(key) { this._lazyKey = key; return this; }
+    getLazyKey() { return this._lazyKey ?? this._key; }
     key(key) { this._key = key; return this; }
     components(components) { this._components = components; for (const c of components)
         c.container = this; return this; }
@@ -214,13 +229,16 @@ export class Schema {
         return out;
     }
     async toHtml() {
+        const isLazy = await this.isLazyLoaded();
+        if (isLazy && typeof this.livewire.isDeferredSchemaLoaded === 'function' && !(await this.livewire.isDeferredSchemaLoaded(this)))
+            return this.toDeferredLoadingHtml();
         const withVisibility = await Promise.all(this._components.map(async (c) => [c, await c.isVisible()]));
         if (!withVisibility.some(([, v]) => v))
             return '';
         const attributes = new Attributes(this._extraClass ? { class: this._extraClass } : {})
             .when(!this._inline, (a) => a.grid(this._columns))
             .merge({
-            'wire:partial': this._partialName ?? (this._partial ? `schema.${this._key}` : null),
+            'wire:partial': this._partialName ?? (this._partial ? `schema.${this._key}` : isLazy ? `schema.${this.getLazyKey()}` : null),
             'x-data': this._root ? `filamentSchema({ livewireId: ${js(this.livewire.id)}, schemaKey: ${js(this._key)} })` : null,
             'x-on:form-validation-error.window': this._root ? 'handleFormValidationError' : null,
             'x-on:reset-schema-component-state.window': this._root ? 'handleClientSideStateReset' : null,
@@ -235,11 +253,21 @@ export class Schema {
         }
         return `<div ${attributes.toHtml()}>${parts.join('')}</div>`;
     }
+    /** Placeholder of a lazy schema: a loading indicator that asks for the schema when it enters the viewport. */
+    toDeferredLoadingHtml() {
+        const key = this.getLazyKey();
+        const attributes = new Attributes(this._extraClass ? { class: this._extraClass } : {}).merge({ 'wire:partial': `schema.${key}`, 'x-data': `filamentSchema({ livewireId: ${js(this.livewire.id)}, schemaKey: ${js(key)}, isLoadingDeferred: true })`, role: 'status', 'aria-busy': 'true' }).class(['fi-sc', 'fi-sc-loading']);
+        return `<div ${attributes.toHtml()}>${loadingIndicator(new Attributes(), 'lg')}<span class="fi-sr-only">${e(t('filament::components/loading-section.label'))}</span></div>`;
+    }
 }
 /** Child schema of a layout component: shares the parent's key and state path, without being a root. */
 export function childSchema(parent, components) {
     const c = parent.container;
-    return new Schema(c.livewire).key(c.getKey()).statePath(c.getStatePath() || null).operation(c.getOperation()).record(c.getRecord()).root(false).parentComponent(parent).components(components);
+    const schema = new Schema(c.livewire).key(c.getKey()).statePath(c.getStatePath() || null).operation(c.getOperation()).record(c.getRecord()).root(false).parentComponent(parent).components(components);
+    const lazy = parent.getLazyLoadedCondition();
+    if (lazy !== false)
+        schema.lazyLoaded(typeof lazy === 'function' ? () => evaluate(lazy, parent.context()) : lazy).lazyKey(parent.getKey());
+    return schema;
 }
 /** Stateful group: its children live under `<container path>.<name>` (used by filter forms). */
 export class StatefulGroup extends Component {
@@ -261,7 +289,15 @@ export class Group extends Component {
     static make(children = []) { return configured(new Group(children)); }
     schema(components) { this.children = components; return this; }
     columns(columns) { this._columns = columns; return this; }
-    getChildSchemas() { return [childSchema(this, this.children).columns(this._columns)]; }
+    /** State path of the components, relative to the container (`address`: their state lives under `address.*`). */
+    statePath(path) { this._name = path; return this; }
+    hasStatePath() { return this._name !== null; }
+    getChildSchemas() {
+        const schema = childSchema(this, this.children).columns(this._columns);
+        if (this.hasStatePath())
+            schema.key(this.getKey()).statePath(this.getStatePath());
+        return [schema];
+    }
     async toHtml() {
         const attributes = new Attributes().merge({ ...this._extraAttributes }).toHtml();
         return `<div${attributes ? ` ${attributes}` : ''}>${await this.getChildSchemas()[0].toHtml()}</div>`;
@@ -318,6 +354,7 @@ export class Section extends Component {
     _contentBefore = false;
     _compact = false;
     _secondary = false;
+    _divided = false;
     _contained = true;
     _collapsible = null;
     _collapsed = false;
@@ -344,6 +381,8 @@ export class Section extends Component {
     compact(condition = true) { this._compact = condition; return this; }
     /** Less contrasting background, for a section on a background of the same color (nested sections…). */
     secondary(condition = true) { this._secondary = condition; return this; }
+    /** Dividing lines between the components of the content. */
+    divided(condition = true) { this._divided = condition; return this; }
     /** `false`: no card around the section. */
     contained(condition = true) { this._contained = condition; return this; }
     /** Collapsible by clicking its header; `collapsed()` starts it collapsed. */
@@ -428,6 +467,7 @@ export class Section extends Component {
                 'fi-compact': Boolean(await evaluate(this._compact, ctx)),
                 'fi-collapsible': isCollapsible,
                 'fi-collapsed': isCollapsible && isCollapsed,
+                'fi-divided': Boolean(await evaluate(this._divided, ctx)),
                 'fi-secondary': Boolean(await evaluate(this._secondary, ctx)),
             }]);
         let header = '';
@@ -652,27 +692,57 @@ export class Form extends Component {
         return `<form ${attributes.toHtml()}>${await content.toHtml()}${await footer.toHtml()}</form>`;
     }
 }
-/** Row of actions in a schema. */
 export class Actions extends Component {
     actions;
     _fullWidth = false;
     _alignment = null;
+    _label = null;
+    _beforeLabel = null;
+    _afterLabel = null;
+    _aboveContent = null;
+    _belowContent = null;
     constructor(actions) { super(); this.actions = actions; }
     static make(actions) { return configured(new Actions(actions)); }
     fullWidth(condition = true) { this._fullWidth = condition; return this; }
     alignment(alignment) { this._alignment = alignment; return this; }
+    /** Label shown above the actions, like a field label. */
+    label(label) { this._label = label; return this; }
+    /** Text, components or actions before the label. */
+    beforeLabel(content) { this._beforeLabel = content; return this; }
+    /** Text, components or actions after the label (a status badge…). */
+    afterLabel(content) { this._afterLabel = content; return this; }
+    /** Text, components or actions between the label and the actions. */
+    aboveContent(content) { this._aboveContent = content; return this; }
+    /** Text, components or actions below the actions. */
+    belowContent(content) { this._belowContent = content; return this; }
+    /** Actions this component exposes for mounting (its key is sent with each of them). */
+    getActions() { return this.actions; }
     async toHtml() {
         const ctx = this.context();
+        const key = this.getKey();
+        const mountContext = key !== null ? { ...(this.livewire?.getActionMountContext?.() ?? {}), schemaComponent: key } : null;
         const visible = [];
         for (const a of this.actions)
             if (await a.isVisible(ctx))
-                visible.push(await a.toHtml(ctx));
-        if (!visible.length)
+                visible.push(await a.toHtml(ctx, mountContext));
+        const label = await evaluate(this._label, ctx);
+        const slot = (content) => renderSlot(this, content, key);
+        const labelHtml = isBlank(label) ? '' : `<div class="fi-sc-actions-label-ctn">${await slot(this._beforeLabel)}<div class="fi-sc-actions-label">${e(label)}</div>${await slot(this._afterLabel)}</div>`;
+        const above = await slot(this._aboveContent), below = await slot(this._belowContent);
+        if (!visible.length && !labelHtml && !above && !below)
             return '';
         const inner = cls(['fi-ac', { 'fi-width-full': this._fullWidth }, this._alignment ? `fi-align-${this._alignment}` : null]);
-        return `<div ${new Attributes().merge({ id: this.getKey() }).class(['fi-sc-actions']).toHtml()}><div class="${inner}">${visible.join('')}</div></div>`;
+        return `<div ${new Attributes().merge({ id: key, ...this._extraAttributes }).class(['fi-sc-actions']).toHtml()}>${labelHtml}${above}${visible.length ? `<div class="${inner}">${visible.join('')}</div>` : ''}${below}</div>`;
     }
 }
+/** Renders a slot of a component as an inline row: strings become `Text` components. */
+export async function renderSlot(parent, content, mountKey = null) {
+    const value = await evaluate(content, parent.context());
+    if (value === null || value === undefined || value === '')
+        return '';
+    const items = (Array.isArray(value) ? value : [value]).map((item) => (typeof item === 'string' || item instanceof HtmlString ? Text.make(item) : item));
+    return renderInlineItems(parent, items, { mountKey, actionView: 'link' });
+}
 let colorManager = null;
 /** Color manager used outside a panel; inside a panel, the host panel's manager takes precedence. */
 export const useColorManager = (manager) => { colorManager = manager; };
@@ -917,7 +987,8 @@ export class Image extends Component {
     async toHtml() {
         const ctx = this.context();
         const url = String((await evaluate(this._url, ctx)) ?? '');
-        if (!/^(\/(?!\/)|https?:\/\/)/i.test(url))
+        // Relative and http(s) URLs, or an inline image (`data:image/…;base64,`: scripts never run in an <img>).
+        if (!/^(\/(?!\/)|https?:\/\/|data:image\/(png|jpeg|gif|webp|svg\+xml);base64,[A-Za-z0-9+/=]+$)/i.test(url))
             return '';
         const tooltip = tooltipExpression(await evaluate(this._tooltip, ctx));
         const attributes = new Attributes(this._extraAttributes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navette-js/schemas",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.5",
   "description": "Layout components and schemas for Navette admin panels.",
   "license": "MIT",
   "type": "module",
@@ -38,7 +38,7 @@
     "node"
   ],
   "dependencies": {
-    "@navette-js/support": "1.0.0-beta.4"
+    "@navette-js/support": "1.0.0-beta.5"
   },
   "publishConfig": {
     "access": "public",