@navette-js/schemas 0.0.0-stage → 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NavetteJS
+
+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/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @navette-js/schemas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Layout components and schemas for Navette admin panels.
+
+Part of [Navette](https://github.com/NavetteJS/navette), admin panels for Node.js. Start a project with `npm create navette@latest`, or install the framework with `npm install @navette-js/panels`.
+
+**Beta:** the API may still change between beta releases.
+
+License: MIT. Third-party notices: see `THIRD-PARTY-NOTICES.md` where present.

package/lib/index.d.ts

@@ -0,0 +1,517 @@
+import { HtmlString, type ColorManager, type Lazy } from '@navette-js/support';
+/** What a schema expects from the stateful component hosting it. */
+export interface SchemaHost {
+    readonly id: string;
+    _errors: Record<string, string[]>;
+    getSchema(name: string): Schema | Promise<Schema>;
+}
+export type ComponentContext = {
+    livewire: SchemaHost;
+    component: Component;
+    operation: string | null;
+    record: unknown;
+    get: (path: string) => unknown;
+    state: unknown;
+};
+type SpanValue = number | string | ((ctx: ComponentContext) => number | string | Promise<number | string>);
+type ColumnSpan = Record<string, SpanValue> | number | string;
+export declare abstract class Component {
+    private _grow;
+    /** Inside a Flex: `false` keeps the natural width instead of filling the available space. */
+    grow(condition?: boolean): this;
+    canGrow(): boolean;
+    /** Default configuration for every instance later created by `make()`: `TextInput.configureUsing((input) => input.maxLength(255))`. */
+    static configureUsing<T>(this: abstract new (...args: any[]) => T, configure: (instance: T) => void): void;
+    protected _name: string | null;
+    protected _keyName: string | null;
+    protected _hidden: Lazy<boolean, ComponentContext>;
+    protected _visible: Lazy<boolean, ComponentContext>;
+    protected _columnSpan: ColumnSpan;
+    protected _extraAttributes: Record<string, string>;
+    protected _columnStart: number | null;
+    container: Schema;
+    hidden(condition?: Lazy<boolean, ComponentContext>): this;
+    visible(condition?: Lazy<boolean, ComponentContext>): this;
+    key(key: string | null): this;
+    /** Hidden for the given operation(s) (`'create'`, `'edit'`…). */
+    hiddenOn(operations: string | string[]): this;
+    /** Visible only for the given operation(s). */
+    visibleOn(operations: string | string[]): this;
+    /** A number applies from the `lg` breakpoint; an object replaces the default entirely. Values may be closures. */
+    columnSpan(span: ColumnSpan): this;
+    /** Starting grid column, from the `lg` breakpoint. */
+    columnStart(start: number | null): this;
+    extraAttributes(attributes: Record<string, string>): this;
+    get livewire(): SchemaHost;
+    isLiberatedFromContainerGrid(): boolean;
+    /** Server methods the component's JavaScript may call (announced to the browser). */
+    getExposedMethods(): string[];
+    /** False for an exposed method after which the host must re-render (e.g. next wizard step, to show validation errors). */
+    isRenderlessMethod(_method: string): boolean;
+    hasStatePath(): boolean;
+    /** Absolute component key: `<schema key>.<key or name>`, or null. */
+    getKey(): string | null;
+    getLivewireKey(): string | null;
+    getStatePath(): string;
+    getAlpineScopeConfiguration(): Record<string, unknown>;
+    context(): ComponentContext;
+    isVisible(): Promise<boolean>;
+    /** The component's own HTML, without its grid wrapper. */
+    abstract toHtml(): Promise<string>;
+    /** Grid column wrapper, rendered even when the component is hidden. */
+    toSchemaHtml(isVisible: boolean): Promise<string>;
+}
+export declare class Schema {
+    livewire: SchemaHost;
+    private _key;
+    private _components;
+    private _statePath;
+    private _columns;
+    private _root;
+    private _inline;
+    private _operation;
+    private _record;
+    private _extraClass;
+    private _partial;
+    private _dense;
+    constructor(livewire: SchemaHost);
+    static make(livewire: SchemaHost): Schema;
+    key(key: string): this;
+    components(components: Component[]): this;
+    schema(components: Component[]): this;
+    statePath(path: string | null): this;
+    columns(columns: Record<string, number> | number | null): this;
+    root(isRoot?: boolean): this;
+    inline(isInline?: boolean): this;
+    operation(operation: string | null): this;
+    record(record: unknown): this;
+    /** Class placed before the grid classes (e.g. `fi-section-content`). */
+    extraClass(name: string | null): this;
+    /** Tighter spacing between components (`fi-sc-dense`). */
+    dense(condition?: boolean): this;
+    /** Partially rendered schema: its root carries `wire:partial="schema.<key>"`. */
+    partiallyRendered(condition?: boolean): this;
+    private _partialName;
+    /** Root `wire:partial` name when it differs from the schema key (filters form: `table-filters-form`). */
+    partialName(name: string | null): this;
+    private _gap;
+    /** `false`: components touch, with no gap (no `fi-sc-has-gap`), as in a FusedGroup. */
+    gap(condition?: boolean): this;
+    private _fieldWrapperView;
+    /**
+     * Field wrapper for this schema: `'filament-forms::plain-field-wrapper'` keeps only a screen-reader label
+     * (FusedGroup fields). `null`: the usual wrapper.
+     */
+    fieldWrapperView(view: string | null): this;
+    getFieldWrapperView(): string | null;
+    getKey(): string;
+    getStatePath(): string;
+    getComponents(): Component[];
+    getOperation(): string | null;
+    getRecord(): unknown;
+    isInline(): boolean;
+    isRoot(): boolean;
+    /** All components, depth-first. */
+    getFlatComponents(): Component[];
+    /** Same, without hidden components or their descendants: a field inside a hidden section is neither validated nor saved. */
+    getVisibleFlatComponents(): Promise<Component[]>;
+    toHtml(): Promise<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;
+/** Stateful group: its children live under `<container path>.<name>` (used by filter forms). */
+export declare class StatefulGroup extends Component {
+    private children;
+    constructor(name: string, children: Component[]);
+    static make(name: string, children: Component[]): StatefulGroup;
+    hasStatePath(): boolean;
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+/** Groups components in a grid, without any chrome. */
+export declare class Group extends Component {
+    protected children: Component[];
+    protected _columns: Record<string, number> | number | null;
+    constructor(children?: Component[]);
+    static make(children?: Component[]): Group;
+    schema(components: Component[]): this;
+    columns(columns: Record<string, number> | number | null): this;
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+/** Column grid: two columns from `lg` by default. */
+export declare class Grid extends Group {
+    constructor(columns?: Record<string, number> | number);
+    static make(columns?: Record<string, number> | number | Component[]): Grid;
+}
+/**
+ * Components side by side from a breakpoint: each fills the available space,
+ * except those marked `grow(false)`, which keep their natural width.
+ */
+export declare class Flex extends Component {
+    private children;
+    private _from;
+    constructor(children?: Component[]);
+    static make(children?: Component[]): Flex;
+    schema(components: Component[]): this;
+    from(breakpoint: 'sm' | 'md' | 'lg' | 'xl' | '2xl'): this;
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+export declare const slug: (text: string) => string;
+/** Card grouping components, with an optional header (heading, actions). */
+export declare class Section extends Component {
+    private children;
+    private _columns;
+    private _heading;
+    private _afterHeader;
+    constructor(heading?: string | null);
+    static make(heading?: string | null): Section;
+    schema(components: Component[]): this;
+    columns(columns: Record<string, number> | number | null): this;
+    private _collapsible;
+    private _collapsed;
+    /** Collapsible by clicking its header; `collapsed()` starts it collapsed. */
+    collapsible(condition?: boolean): this;
+    collapsed(condition?: boolean): this;
+    /** Actions shown to the right of the heading. */
+    afterHeader(actions: Renderable[]): this;
+    /** Actions the section exposes for mounting. */
+    getActions(): Renderable[];
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+/**
+ * Raw markup in a schema. The content is inserted AS IS: never put a user- or database-supplied value in it
+ * without escaping it with `e()` from `@navette-js/support`.
+ */
+export declare class Html extends Component {
+    private content;
+    constructor(content: string | ((ctx: ComponentContext) => string | Promise<string>));
+    static make(content: string | ((ctx: ComponentContext) => string | Promise<string>)): Html;
+    toHtml(): Promise<string>;
+}
+/** A tab of a Tabs component: a label, an optional icon and its own schema. */
+export declare class Tab extends Component {
+    private children;
+    private _columns;
+    private _icon;
+    private label;
+    constructor(label: string);
+    static make(label: string): Tab;
+    schema(components: Component[]): this;
+    columns(columns: Record<string, number> | number | null): this;
+    icon(name: string | null): this;
+    getLabel(): string;
+    getIcon(): string | null;
+    /** Browser-side tab key (no schema prefix): `::data::` follows the schema state path, and is dropped in infolists. */
+    getTabKey(): string;
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+/** Layout tabs: every panel is rendered, the browser only shows the active one. */
+export declare class Tabs extends Component {
+    private tabs;
+    private label;
+    constructor(label: string);
+    static make(label: string): Tabs;
+    schema(tabs: Tab[]): this;
+    getExposedMethods(): string[];
+    getLazyLoadedTabBadges(): Record<string, unknown>;
+    getDeferredTabBadges(): Record<string, unknown>;
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+/** Render hook injection point, using the host's scopes. Liberated from the container grid. */
+export declare class RenderHook extends Component {
+    private hook;
+    constructor(hook: string);
+    static make(hook: string): RenderHook;
+    isLiberatedFromContainerGrid(): boolean;
+    toHtml(): Promise<string>;
+}
+/** Embeds another schema of the host (`form`, `infolist`…) as a root schema. */
+export declare class EmbeddedSchema extends Component {
+    private schemaName;
+    constructor(name: string);
+    static make(name: string): EmbeddedSchema;
+    toHtml(): Promise<string>;
+}
+/** `<form>` element: content and footer (actions), submitted to a host method. */
+export declare class Form extends Component {
+    private children;
+    private _footer;
+    private _id;
+    private _submit;
+    constructor(children: Component[]);
+    static make(children?: Component[]): Form;
+    id(id: string): this;
+    livewireSubmitHandler(method: string): this;
+    footer(components: Component[]): this;
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+/** Item rendered in an actions container: in practice an Action (actions package). */
+export interface Renderable {
+    isVisible(ctx: ComponentContext): Promise<boolean>;
+    toHtml(ctx: ComponentContext): Promise<string>;
+}
+/** Row of actions in a schema. */
+export declare class Actions extends Component {
+    private actions;
+    private _fullWidth;
+    private _alignment;
+    constructor(actions: Renderable[]);
+    static make(actions: Renderable[]): Actions;
+    fullWidth(condition?: boolean): this;
+    alignment(alignment: string | null): this;
+    toHtml(): 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. */
+export type InlineItem = Component | Renderable;
+/**
+ * Inline row mixing components and actions (footers, controls, after a label).
+ * Actions are mounted with `schemaComponent: mountKey` (the root schema by default, which finds them through the parent's `getActions()`).
+ * `actionView`: `'button'` (full button), `'link'` (link, or icon button for an `iconButton()` action), `'auto'` (icon button if `iconButton()`, button otherwise).
+ * `scope` overrides keys of the components' Alpine configuration (`path`, `containerPath`).
+ */
+export declare function renderInlineItems(parent: Component, items: InlineItem[], options?: {
+    alignment?: string | null;
+    scope?: Record<string, unknown>;
+    mountKey?: string | null;
+    actionView?: 'button' | 'link' | 'auto';
+}): Promise<string>;
+/**
+ * Titled frame grouping fields: a legend and a two-column grid by default.
+ * With `statePath()`, the fields live under that path and the fieldset gets a key (and an `id`).
+ */
+export declare class Fieldset extends Component {
+    private children;
+    private _columns;
+    private _label;
+    private _hiddenLabel;
+    private _contained;
+    private _markedAsRequired;
+    constructor(label?: Lazy<string | null, ComponentContext>);
+    static make(label?: Lazy<string | null, ComponentContext>): Fieldset;
+    schema(components: Component[]): this;
+    columns(columns: Record<string, number> | number | null): this;
+    label(label: Lazy<string | null, ComponentContext>): this;
+    /** Keeps the legend for screen readers only. */
+    hiddenLabel(condition?: boolean): this;
+    /** `false`: no border or padding. */
+    contained(condition?: boolean): this;
+    /** Asterisk after the legend (the fieldset itself is never validated). */
+    markAsRequired(condition?: boolean): this;
+    /** State path of the fields, relative to the container. */
+    statePath(path: string | null): this;
+    hasStatePath(): boolean;
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+/**
+ * Text in a schema: a plain `<span>`, or a badge with `badge()`. The content is escaped;
+ * an `HtmlString` (from `@navette-js/support`) is inserted as is, so build it only from escaped values.
+ */
+export declare class Text extends Component {
+    private _content;
+    private _badge;
+    private _color;
+    private _size;
+    private _weight;
+    private _fontFamily;
+    private _icon;
+    private _iconPosition;
+    private _iconSize;
+    private _tooltip;
+    private _copyable;
+    private _copyableState;
+    private _copyMessage;
+    private _copyMessageDuration;
+    constructor(content: Lazy<string | HtmlString | null, ComponentContext>);
+    static make(content: Lazy<string | HtmlString | null, ComponentContext>): Text;
+    content(content: Lazy<string | HtmlString | null, ComponentContext>): this;
+    /** Renders as a badge. */
+    badge(condition?: Lazy<boolean, ComponentContext>): this;
+    /** Color (`gray` by default; `primary`, `danger`…). */
+    color(color: Lazy<string | null, ComponentContext>): this;
+    /** Text or badge size (`xs`, `sm`, `md`, `lg`). */
+    size(size: string | null): this;
+    /** Font weight (`bold`, `semibold`, `medium`…). */
+    weight(weight: string | null): this;
+    /** Font family (`sans`, `serif`, `mono`). */
+    fontFamily(family: string | null): this;
+    /** Badge icon. */
+    icon(name: string | null): this;
+    iconPosition(position: 'before' | 'after'): this;
+    iconSize(size: string | null): this;
+    tooltip(text: Lazy<string | null, ComponentContext>): this;
+    /** Clicking copies the text (or `copyableState()`) to the clipboard. */
+    copyable(condition?: Lazy<boolean, ComponentContext>): this;
+    copyableState(state: Lazy<string | null, ComponentContext>): this;
+    copyMessage(message: string | null): this;
+    copyMessageDuration(milliseconds: number): this;
+    getContent(): Promise<string | HtmlString | null>;
+    toHtml(): Promise<string>;
+}
+/** Heroicon in a schema: decorative, unless a tooltip or an `aria-label` (extra attribute) describes it. */
+export declare class Icon extends Component {
+    private _icon;
+    private _color;
+    private _size;
+    private _tooltip;
+    constructor(name: Lazy<string | null, ComponentContext>);
+    static make(name: Lazy<string | null, ComponentContext>): Icon;
+    icon(name: Lazy<string | null, ComponentContext>): this;
+    /** Color (`primary` by default). */
+    color(color: Lazy<string | null, ComponentContext>): this;
+    /** Size (`xs` … `2xl`); `base` resets to the default size. */
+    size(size: string | null): this;
+    tooltip(text: Lazy<string | null, ComponentContext>): this;
+    toHtml(): Promise<string>;
+}
+/** Image in a schema. Only same-site (`/…`) or http(s) URLs are rendered. */
+export declare class Image extends Component {
+    private _url;
+    private _alt;
+    private _height;
+    private _width;
+    private _alignment;
+    private _tooltip;
+    constructor(url: Lazy<string, ComponentContext>, alt: Lazy<string, ComponentContext>);
+    static make(url: Lazy<string, ComponentContext>, alt: Lazy<string, ComponentContext>): Image;
+    url(url: Lazy<string, ComponentContext>): this;
+    alt(alt: Lazy<string, ComponentContext>): this;
+    private static dimension;
+    /** Height (`8rem` by default); a number is in pixels. */
+    imageHeight(height: number | string | null): this;
+    imageWidth(width: number | string | null): this;
+    imageSize(size: number | string): this;
+    /** Alignment (`start`, `center`, `end`). */
+    alignment(alignment: string | null): this;
+    alignStart(): this;
+    alignCenter(): this;
+    alignEnd(): this;
+    tooltip(text: Lazy<string | null, ComponentContext>): this;
+    toHtml(): Promise<string>;
+}
+/** Bulleted list: each item is a component; a string becomes a `Text`. Two columns from `sm`. */
+export declare class UnorderedList extends Component {
+    private children;
+    private _columns;
+    private _size;
+    constructor(items?: (Component | string | HtmlString)[]);
+    static make(items?: (Component | string | HtmlString)[]): UnorderedList;
+    private static normalize;
+    schema(items: (Component | string | HtmlString)[]): this;
+    columns(columns: Record<string, number> | number | null): this;
+    /** Text size (`xs`, `sm`, `md`, `lg`). */
+    size(size: string | null): this;
+    getChildSchemas(): Schema[];
+    toHtml(): Promise<string>;
+}
+/** Empty state: icon, heading, description and a footer (actions, components). */
+export declare class EmptyState extends Component {
+    private _heading;
+    private _description;
+    private _icon;
+    private _iconColor;
+    private _iconSize;
+    private _compact;
+    private _contained;
+    private _headingTag;
+    private _footer;
+    constructor(heading: Lazy<string, ComponentContext>);
+    static make(heading: Lazy<string, ComponentContext>): EmptyState;
+    heading(heading: Lazy<string, ComponentContext>): this;
+    description(description: Lazy<string | null, ComponentContext>): this;
+    icon(name: string | null): this;
+    /** Icon color (`primary` by default). */
+    iconColor(color: string | null): this;
+    iconSize(size: string | null): this;
+    /** Compact variant. */
+    compact(condition?: boolean): this;
+    /** `false`: no surrounding card. */
+    contained(condition?: boolean): this;
+    /** Heading tag (`h2` by default). */
+    headingTag(tag: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'): this;
+    /** Footer: inline actions and components. */
+    footer(items: InlineItem[]): this;
+    /** Footer actions, mounted on the root schema. */
+    getActions(): Renderable[];
+    toHtml(): Promise<string>;
+}
+/**
+ * Information box: a status (`info()`, `success()`, `warning()`, `danger()`) setting color and icon,
+ * heading, description, footer actions (as links) and control actions (on the right).
+ */
+export declare class Callout extends Component {
+    private _heading;
+    private _description;
+    private _status;
+    private _color;
+    private _hasColor;
+    private _icon;
+    private _iconColor;
+    private _iconSize;
+    private _footerActions;
+    private _footerActionsAlignment;
+    private _footer;
+    private _controlActions;
+    constructor(heading?: Lazy<string | null, ComponentContext>);
+    static make(heading?: Lazy<string | null, ComponentContext>): Callout;
+    heading(heading: Lazy<string | null, ComponentContext>): this;
+    description(description: Lazy<string | null, ComponentContext>): this;
+    /** Status: sets color, icon and a screen-reader prefix ("Note:"…). */
+    status(status: string | null): this;
+    danger(): this;
+    info(): this;
+    success(): this;
+    warning(): this;
+    /** Background color; `null` removes the status color (the icon keeps it). */
+    color(color: string | null): this;
+    icon(name: string | null): this;
+    iconColor(color: string | null): this;
+    /** Icon size (`lg` by default). */
+    iconSize(size: string | null): this;
+    /** Footer actions, rendered as links. */
+    actions(actions: Renderable[]): this;
+    footerActions(actions: Renderable[]): this;
+    /** Footer actions alignment (`start`, `center`, `end`, `between`). */
+    footerActionsAlignment(alignment: string): this;
+    /** Free-form footer (components and actions), replacing the footer actions. */
+    footer(items: InlineItem[] | null): this;
+    /** Small actions on the right of the callout (dismiss…). */
+    controlActions(actions: Renderable[]): this;
+    getColor(): string | null;
+    getIcon(): string | null;
+    /** Callout actions, mounted on the root schema. */
+    getActions(): Renderable[];
+    toHtml(): Promise<string>;
+}
+/**
+ * Fields joined under a single label: each field keeps only a screen-reader label,
+ * and the first validation error among the fields is shown under the group.
+ */
+export declare class FusedGroup extends Component {
+    private children;
+    private _columns;
+    private _label;
+    private _hiddenLabel;
+    private _markedAsRequired;
+    constructor(children?: Component[]);
+    static make(children?: Component[]): FusedGroup;
+    schema(components: Component[]): this;
+    columns(columns: Record<string, number> | number | null): this;
+    label(label: Lazy<string | null, ComponentContext>): this;
+    hiddenLabel(condition?: boolean): this;
+    /** Asterisk after the label (validation stays per field). */
+    markAsRequired(condition?: boolean): this;
+    getChildSchemas(): Schema[];
+    /** First error among the group's fields (including one on an item of a multi-valued field). */
+    private firstError;
+    toHtml(): Promise<string>;
+}
+export {};