@nxgt/material 3.34.0 → 3.35.1

package/dist/lib/components/ui/fields/attributes/partials/value-text.d.ts

@@ -0,0 +1,12 @@
+import { Attribute } from '../models/attribute.js';
+import { AttributeText } from '../use-attribute-text.js';
+type ValueTextProps = {
+    attribute: Attribute;
+    text: AttributeText;
+};
+/**
+ * An attribute's default value as a row shows it: a Yes or No for a boolean,
+ * a swatch beside a colour, the unit after a number, a dash when there is none.
+ */
+export declare function ValueText({ attribute, text }: ValueTextProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/attributes/schema.d.ts

@@ -0,0 +1,32 @@
+import { default as z } from 'zod';
+/** The codes an issue of {@link attributesListSchema} carries in `params.code`. */
+export type AttributeIssueCode = 'empty' | 'duplicate' | 'option' | 'boolean' | 'number' | 'date';
+/**
+ * The schema of a list of attributes with the rules the inline editor shows:
+ * a name that is set and that no other attribute has, and a default value
+ * that fits the type (a listed option, a boolean, a number, a date). An issue
+ * sits on the entry's `name` or `defaultValue`. Built on the first call, like
+ * `openingHoursListSchema`.
+ */
+export declare const attributesListSchema: () => z.ZodArray<z.ZodObject<{
+    defaultValue: z.ZodOptional<z.ZodNullable<z.ZodAny>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodNullable<z.ZodCoercedNumber<unknown>>>;
+    label: z.ZodString;
+    options: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    type: z.ZodEnum<{
+        BOOLEAN: "BOOLEAN";
+        COLOR: "COLOR";
+        DATE: "DATE";
+        DATETIME: "DATETIME";
+        MULTI_SELECT: "MULTI_SELECT";
+        NUMBER: "NUMBER";
+        RICH_TEXT: "RICH_TEXT";
+        SELECT: "SELECT";
+        STRING: "STRING";
+        TEXT: "TEXT";
+        TIME: "TIME";
+    }>;
+    unit: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodString;
+}, z.core.$strip>>;

package/dist/lib/components/ui/fields/attributes/use-announce.d.ts

@@ -0,0 +1,14 @@
+import { Attribute } from './models/attribute.js';
+import { AttributeText } from './use-attribute-text.js';
+declare const FALLBACKS: {
+    readonly lift: "Picked up {name}, position {position} of {count}. Use the arrow keys to move it, Space to drop it, Escape to cancel.";
+    readonly move: "{name} moved to position {position} of {count}.";
+    readonly drop: "{name} dropped at position {position} of {count}.";
+    readonly cancel: "Reorder cancelled. {name} is back at position {position} of {count}.";
+};
+/** The live region's text: what a reorder step says about one attribute. */
+export declare function useAnnounce(value: Attribute[], text: AttributeText): {
+    message: string;
+    say: (step: keyof typeof FALLBACKS, index: number, place: number) => void;
+};
+export {};

package/dist/lib/components/ui/fields/attributes/use-attribute-text.d.ts

@@ -0,0 +1,13 @@
+import { NameIssue } from './logic/names.js';
+import { Attribute } from './models/attribute.js';
+/** The translator and the words the attribute components print with. */
+export declare function useAttributeText(): {
+    t: (key: import('../../../../i18n/index.js').MaterialLocaleKey, fallback: string, options?: import('../../../../i18n/index.js').TranslationContext) => string;
+    language: "fr" | "en" | undefined;
+    typeName: (type: string) => string;
+    yesNo: (yes: boolean) => string;
+    /** What a row is called: its label, else its name, else "Untitled". */
+    title: (attribute: Attribute) => string;
+    nameMessage: (issue: NameIssue) => string;
+};
+export type AttributeText = ReturnType<typeof useAttributeText>;

package/dist/lib/components/ui/fields/attributes/use-attributes-editor.d.ts

@@ -0,0 +1,34 @@
+import { Attribute } from './models/attribute.js';
+import { AttributeText } from './use-attribute-text.js';
+type Options = {
+    value: Attribute[];
+    onValueChange?: (value: Attribute[]) => void;
+    text: AttributeText;
+};
+/**
+ * The editor's state and edits over a controlled list: which row is open,
+ * change one attribute (a new type resets what no longer fits), remove one,
+ * add one, and the reorder of `useReorder`. Focus is handed to a control by
+ * name once the edit has rendered.
+ */
+export declare function useAttributesEditor({ value, onValueChange, text }: Options): {
+    ids: string[];
+    openId: string | null;
+    reorder: {
+        order: number[];
+        message: string;
+        liftedId: string | null;
+        press: (id: string, key: string) => boolean;
+        dragTo: (from: string, to: string) => void;
+        release: () => void;
+    };
+    requestFocus: (name: string) => void;
+    focusKey: (name: string) => string;
+    toggle: (id: string) => void;
+    close: () => void;
+    change: (index: number, patch: Partial<Attribute>) => void;
+    remove: (index: number) => void;
+    add: () => void;
+};
+export type AttributesEditorState = ReturnType<typeof useAttributesEditor>;
+export {};

package/dist/lib/components/ui/fields/attributes/use-reorder.d.ts

@@ -0,0 +1,26 @@
+import { Attribute } from './models/attribute.js';
+import { AttributeText } from './use-attribute-text.js';
+type Options = {
+    value: Attribute[];
+    ids: string[];
+    text: AttributeText;
+    commit: (next: Attribute[], ids: string[]) => void;
+    requestFocus: (key: string) => void;
+};
+/**
+ * Reordering by the keyboard and by the pointer. A key lifts a row; the
+ * arrows move a draft order the list shows; Space or Enter drops it (one
+ * change, with every `priority` set), Escape puts it back. Each step is said
+ * through `message`, for the live region.
+ */
+export declare function useReorder({ value, ids, text, commit, requestFocus, }: Options): {
+    order: number[];
+    message: string;
+    liftedId: string | null;
+    press: (id: string, key: string) => boolean;
+    /** A pointer drag that ended over another row. */
+    dragTo: (from: string, to: string) => void;
+    /** The handle lost focus to another control: the row is dropped where it is. */
+    release: () => void;
+};
+export {};

package/dist/lib/components/ui/fields/contacts/contacts-dialog-form-field.d.ts

@@ -0,0 +1,9 @@
+import { ComponentProps } from 'react';
+import { UseControllerProps } from 'react-hook-form';
+export type ContactsDialogFieldProps<T extends Record<string, any>> = Pick<UseControllerProps<T>, 'control' | 'name'> & {
+    className?: string;
+    disabled?: boolean;
+    label?: string;
+} & Omit<ComponentProps<'div'>, 'name'>;
+/** `ContactsFormField` with `editing="dialog"`: a list, and a dialog per contact. */
+export declare function ContactsDialogField<T extends Record<string, any>>({ control, name, className, disabled, label, ...props }: ContactsDialogFieldProps<T>): import("react").JSX.Element;

package/dist/lib/components/ui/fields/contacts/contacts-editor.d.ts

@@ -0,0 +1,29 @@
+import { ReactNode } from 'react';
+import { HeadingLevel } from '../inline-editor/editor-header.js';
+import { Contact } from './models.js';
+export type ContactsEditorProps = {
+    value?: Contact[];
+    onValueChange?: (value: Contact[]) => void;
+    /** The heading; "Contacts" by default. */
+    label?: ReactNode;
+    /** The heading's level; `3` by default. The type headings sit one below it. */
+    headingLevel?: HeadingLevel;
+    /**
+     * `'list'` (the default): each type is one bordered list of rows.
+     * `'cards'`: each contact is its own tinted card, with a round tile for
+     * the primary one. The fields keep the library's field radius in both.
+     */
+    variant?: 'list' | 'cards';
+    disabled?: boolean;
+    className?: string;
+};
+/**
+ * Contacts edited in place, grouped by type: each row has its type icon, the
+ * type, value and label fields, call / write / open and copy actions, a star
+ * that makes it the primary contact of its type (shown first) and a remove
+ * button; "Add Contact" chips add one of a type. A wrong format or a duplicate
+ * is a `role="alert"` under its value. Below 640px each contact is a summary
+ * row that opens a bottom sheet with the same fields. It holds the value model
+ * of `Contacts` (`primary` is an optional addition).
+ */
+export declare function ContactsEditor({ value, onValueChange, label, headingLevel, variant, disabled, className, }: ContactsEditorProps): import("react").JSX.Element;

package/dist/lib/components/ui/fields/contacts/contacts-form-field.d.ts

@@ -4,5 +4,18 @@ export type ContactsFormFieldProps<T extends Record<string, any>> = Pick<UseCont
     className?: string;
     disabled?: boolean;
     label?: string;
+    /**
+     * `'inline'` (the default) edits the contacts in place
+     * (`ContactsEditor`); `'dialog'` keeps the list and the dialog that edits
+     * one contact at a time.
+     */
+    editing?: 'inline' | 'dialog';
+    /** `editing="inline"` only: `'list'` (default) or `'cards'`. */
+    variant?: 'list' | 'cards';
 } & Omit<ComponentProps<'div'>, 'name'>;
-export declare function ContactsFormField<T extends Record<string, any>>({ control, name, className, disabled, label, ...props }: ContactsFormFieldProps<T>): import("react").JSX.Element;
+/**
+ * Contacts in a React Hook Form field (an array of `{ type, value, label?,
+ * primary? }`). Inline by default; `editing="dialog"` is today's list and
+ * dialog.
+ */
+export declare function ContactsFormField<T extends Record<string, any>>({ editing, variant, ...props }: ContactsFormFieldProps<T>): import("react").JSX.Element;

package/dist/lib/components/ui/fields/contacts/contacts-summary.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from 'react';
+import { Contact } from './models.js';
+export type ContactsSummaryProps = {
+    /** The contacts, in the value model of `Contacts`. */
+    data?: Contact[] | null;
+    /** Names the region; "Contacts" by default. */
+    label?: string;
+    /** `'list'` (the default) or `'cards'`, as in `ContactsEditor`. */
+    variant?: 'list' | 'cards';
+    className?: string;
+    /**
+     * What shows when there is nothing to list. A quiet "No contacts" by default; your
+     * node replaces it, and `null` renders nothing.
+     */
+    empty?: ReactNode;
+};
+/**
+ * The read-only counterpart of `ContactsEditor`: the contacts by type, the
+ * primary one first in its type and marked, each with its type icon, its
+ * value as a link (call, write, open) and a copy button. With nothing to list it shows
+ * a quiet "No contacts" (see `empty`; `empty={null}` renders nothing).
+ */
+export declare function ContactsSummary({ data, label, variant, className, empty, }: ContactsSummaryProps): import("react").JSX.Element;

package/dist/lib/components/ui/fields/contacts/index.d.ts

@@ -1,5 +1,8 @@
 export * from './contact-dialog.js';
 export * from './contacts.js';
+export * from './contacts-editor.js';
 export * from './contacts-form-field.js';
+export * from './contacts-summary.js';
 export * from './models.js';
+export * from './schema.js';
 export * from './utils.js';

package/dist/lib/components/ui/fields/contacts/logic/check-contact.d.ts

@@ -0,0 +1,11 @@
+import { ContactType } from '../models.js';
+/** `empty` is not an error by itself: the row is still being typed. */
+export type ContactCheck = 'empty' | 'ok' | 'bad';
+/** The address of a website, `http:` or `https:` only. */
+export declare function parseWebsite(value: string): URL | null;
+/**
+ * The format check of one value: an email has an `@` and a dot, a website is
+ * an `http(s)` address, and a phone, mobile or fax number is 7 to 15 digits
+ * with the usual separators. It checks the shape, not that the line exists.
+ */
+export declare function checkContact(type: ContactType, value: string): ContactCheck;

package/dist/lib/components/ui/fields/contacts/logic/contact-action.d.ts

@@ -0,0 +1,11 @@
+import { ContactType } from '../models.js';
+/** What a contact can do for a person: call it, write to it, open it. */
+export type ContactAction = {
+    kind: 'call' | 'email' | 'open';
+    href: string;
+};
+/**
+ * The link a contact offers, or `null` (a fax number, or a value that is not
+ * well-formed). A website opens only if it is an `http(s)` address.
+ */
+export declare function contactAction(type: ContactType, value: string): ContactAction | null;

package/dist/lib/components/ui/fields/contacts/logic/duplicates.d.ts

@@ -0,0 +1,17 @@
+import { ContactType } from '../models.js';
+type Keyed = {
+    type: ContactType;
+    value: string;
+};
+/**
+ * What makes two contacts the same: the type and the value without its
+ * formatting (digits and `+` for a number, lower case for an email, the
+ * address without a trailing slash for a website).
+ */
+export declare function contactKey({ type, value }: Keyed): string;
+/**
+ * The index of the earlier contact this one repeats, or `-1`. A blank value
+ * repeats nothing, and the first of two equal contacts is not the duplicate.
+ */
+export declare function duplicateOf(items: readonly Keyed[], index: number): number;
+export {};

package/dist/lib/components/ui/fields/contacts/logic/issues.d.ts

@@ -0,0 +1,7 @@
+import { Contact } from '../models.js';
+/**
+ * How many contacts have a wrong format or repeat an earlier one. A format is
+ * judged only once its field was left (`left` holds the left rows' indexes),
+ * a duplicate at once.
+ */
+export declare function contactIssues(items: readonly Contact[], left: ReadonlySet<number>): number;

package/dist/lib/components/ui/fields/contacts/logic/primary.d.ts

@@ -0,0 +1,33 @@
+import { ContactType } from '../models.js';
+type Marked = {
+    type: ContactType;
+    primary?: boolean | null;
+};
+/** The types in the order the editor and the summary list them. */
+export declare const CONTACT_TYPE_ORDER: readonly ContactType[];
+/**
+ * Whether the contact is the primary one of its type. A value that marks
+ * several of a type is read as marking the first only: one primary per type.
+ */
+export declare function isPrimary(items: readonly Marked[], index: number): boolean;
+/**
+ * Marks the contact primary and clears the others of its type, or clears it
+ * when it was the primary one. The flag is left off, not `false`, where it
+ * is not set.
+ */
+export declare function togglePrimary<T extends Marked>(items: T[], index: number): T[];
+export type ContactEntry<T> = {
+    contact: T;
+    index: number;
+};
+export type ContactGroup<T> = {
+    type: ContactType;
+    entries: ContactEntry<T>[];
+};
+/**
+ * The contacts by type, in {@link CONTACT_TYPE_ORDER}, the primary one first
+ * in its group and the rest in their order. Each entry keeps its index in
+ * `items`, so an edit still reaches the right one.
+ */
+export declare function groupContacts<T extends Marked>(items: readonly T[]): ContactGroup<T>[];
+export {};

package/dist/lib/components/ui/fields/contacts/models.d.ts

@@ -17,9 +17,16 @@ export type Contact = {
      * @example Accueil
      */
     label?: string | null;
+    /**
+     * @description The contact to use first among those of its type. One per
+     * type: the inline editor keeps it so, and the first marked one wins in a
+     * value that marks several.
+     */
+    primary?: boolean | null;
 };
 export type ContactFieldValue = {
     type: ContactType;
     value: string;
     label?: string;
+    primary?: boolean;
 };

package/dist/lib/components/ui/fields/contacts/partials/contact-fields.d.ts

@@ -0,0 +1,29 @@
+import { Contact } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+type ContactFieldsProps = {
+    text: ContactText;
+    contact: Contact;
+    /** Its index in the whole value, for the duplicate check. */
+    index: number;
+    items: readonly Contact[];
+    /** The contact's stable row id: names the controls focus returns to. */
+    rowId: string;
+    /** The value field was left: its format is judged. */
+    left: boolean;
+    onLeave: () => void;
+    /** Scopes a focus name to this editor. */
+    focusKey: (name: string) => string;
+    /** Each contact's place in its type's group, 1-based: the accessible names. */
+    positions: ReadonlyMap<number, number>;
+    disabled?: boolean;
+    /** One column: the sheet's layout. */
+    stacked?: boolean;
+    onChange: (patch: Partial<Contact>) => void;
+};
+/**
+ * The three fields of one contact (type, value, label) with the messages that
+ * belong to the value: a wrong format, a duplicate or, once left, an empty
+ * value. Each message is a `role="alert"` linked to the value field.
+ */
+export declare function ContactFields({ text, contact, index, items, rowId, left, onLeave, focusKey, positions, disabled, stacked, onChange, }: ContactFieldsProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/contact-links.d.ts

@@ -0,0 +1,15 @@
+import { Contact } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+type ContactLinksProps = {
+    text: ContactText;
+    contact: Contact;
+    size?: 'sm' | 'default';
+    className?: string;
+};
+/**
+ * What a person can do with a contact: call it, write to it or open it (a
+ * link, only when the value is well-formed) and copy it ("Copied" is
+ * announced). Used by the editor's rows and by the summary.
+ */
+export declare function ContactLinks({ text, contact, size, className, }: ContactLinksProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/contact-row.d.ts

@@ -0,0 +1,14 @@
+import { Contact } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+import { ContactsEditorState } from '../use-contacts-editor.js';
+export type ContactRowProps = {
+    text: ContactText;
+    editor: ContactsEditorState;
+    items: Contact[];
+    index: number;
+    positions: ReadonlyMap<number, number>;
+    variant: 'list' | 'cards';
+    disabled?: boolean;
+};
+/** One contact on a tablet or a desktop: its icon, its fields and its actions. */
+export declare function ContactRow({ text, editor, items, index, positions, variant, disabled, }: ContactRowProps): import("react").JSX.Element;

package/dist/lib/components/ui/fields/contacts/partials/phone-sheet.d.ts

@@ -0,0 +1,14 @@
+import { Contact } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+import { ContactsEditorState } from '../use-contacts-editor.js';
+type PhoneSheetProps = {
+    text: ContactText;
+    editor: ContactsEditorState;
+    items: Contact[];
+    positions: ReadonlyMap<number, number>;
+    variant: 'list' | 'cards';
+    disabled?: boolean;
+};
+/** A phone's editor for one contact: the same fields and actions, in a bottom sheet. */
+export declare function PhoneSheet({ text, editor, items, positions, variant, disabled, }: PhoneSheetProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/quick-add.d.ts

@@ -0,0 +1,12 @@
+import { ContactType } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+type QuickAddProps = {
+    text: ContactText;
+    disabled?: boolean;
+    /** The scoped focus key of a control, so a remove can return to the chip. */
+    focusKey: (name: string) => string;
+    onAdd: (type: ContactType) => void;
+};
+/** "Add Contact" and one chip per type: adds an empty contact of that type. */
+export declare function QuickAdd({ text: { t, typeName }, disabled, focusKey, onAdd, }: QuickAddProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/row-actions.d.ts

@@ -0,0 +1,16 @@
+import { ContactText } from '../use-contact-text.js';
+type RowActionsProps = {
+    text: ContactText;
+    primary: boolean;
+    /** Names the contact in the remove button: "Remove Phone 1". */
+    typeName: string;
+    position: number;
+    /** The star's scoped focus key, so focus can return to it after the row moves. */
+    starFocusKey?: string;
+    disabled?: boolean;
+    onPrimary: () => void;
+    onRemove: () => void;
+};
+/** The star that makes a contact the primary one of its type, and the trash. */
+export declare function RowActions({ text: { t }, primary, typeName, position, starFocusKey, disabled, onPrimary, onRemove, }: RowActionsProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/summary-item.d.ts

@@ -0,0 +1,11 @@
+import { Contact } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+type SummaryItemProps = {
+    text: ContactText;
+    contact: Contact;
+    primary: boolean;
+    variant: 'list' | 'cards';
+};
+/** One contact in the read-only summary: icon, label, value, a primary mark and its actions. */
+export declare function SummaryItem({ text, contact, primary, variant, }: SummaryItemProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/summary-row.d.ts

@@ -0,0 +1,14 @@
+import { Contact } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+type SummaryRowProps = {
+    text: ContactText;
+    items: Contact[];
+    index: number;
+    primary: boolean;
+    variant: 'list' | 'cards';
+    disabled?: boolean;
+    onOpen: () => void;
+};
+/** A contact on a phone: label, value and a mark for primary or a problem; it opens the sheet. */
+export declare function SummaryRow({ text: { t, typeName }, items, index, primary, variant, disabled, onOpen, }: SummaryRowProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/type-group.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+import { ContactType } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+type TypeGroupProps = {
+    text: ContactText;
+    type: ContactType;
+    count: number;
+    variant: 'list' | 'cards';
+    /** The type heading's level; `4` by default. */
+    headingLevel?: number;
+    children: ReactNode;
+};
+/** One type's contacts under its heading: a bordered card, or a stack of cards. */
+export declare function TypeGroup({ text: { t, typeName }, type, count, variant, headingLevel, children, }: TypeGroupProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/type-icon.d.ts

@@ -0,0 +1,12 @@
+import { ContactType } from '../models.js';
+type TypeIconProps = {
+    type: ContactType;
+    /** `cards` rounds the tile more, like the rest of the cards variant. */
+    variant?: 'list' | 'cards';
+    /** The primary contact of its type, tinted stronger in the cards variant. */
+    primary?: boolean;
+    className?: string;
+};
+/** The tile with a contact type's icon; decoration, the row names the type. */
+export declare function TypeIcon({ type, variant, primary, className }: TypeIconProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/contacts/partials/value-field.d.ts

@@ -0,0 +1,25 @@
+import { Contact } from '../models.js';
+import { ContactText } from '../use-contact-text.js';
+type ValueFieldProps = {
+    text: ContactText;
+    contact: Contact;
+    index: number;
+    items: readonly Contact[];
+    /** The name of this field's focus key, and how a name is scoped. */
+    focusName: string;
+    focusKey: (name: string) => string;
+    positions: ReadonlyMap<number, number>;
+    /** The field was left: a wrong format or an empty value shows. */
+    left: boolean;
+    onLeave: () => void;
+    disabled?: boolean;
+    onChange: (patch: Partial<Contact>) => void;
+};
+/**
+ * The value input and the messages that belong to it: a wrong format, a
+ * duplicate (live) or, once the field was left, a wrong format or an empty
+ * value. Each message is a
+ * `role="alert"` the input is described by.
+ */
+export declare function ValueField({ text, contact, index, items, focusName, focusKey, positions, left, onLeave, disabled, onChange, }: ValueFieldProps): import("react").JSX.Element;
+export {};