@veevarts/design-system 2.1.0-beta.24 → 2.1.0-beta.25

package/dist/patterns/AdminTable/styles.d.ts

@@ -10,7 +10,8 @@
  *
  * They are exported for the one screen that cannot use `AdminTable`: react-aria's
  * collection API rejects an interleaved `<tr>`, so a table that expands a row
- * into a full-width panel renders its own `<table>` and dresses it with these.
+ * into a full-width panel renders its own `<table>` and dresses it with these
+ * (`ExpandableTable` does, and so does the accounting ledger).
  *
  * The arbitrary values (`text-[11px]`, `tracking-[.04em]`) are the mockups'
  * measurements, pinned rather than rounded to the nearest scale step: these

package/dist/patterns/ExpandableTable/ExpandableTable.d.ts

@@ -0,0 +1,6 @@
+import { JSX } from 'react';
+import { ExpandableTableProps } from './types';
+export declare function ExpandableTable<Row>({ ariaLabel, columns, rows, getRowKey, getRowLabel, renderCell, renderExpanded, renderExpandedActions, getRowActions, rowNeedsFix, expandedKeys, defaultExpandedKeys, onExpandedChange, labels, emptyContent, className, 'data-testid': dataTestId, }: ExpandableTableProps<Row>): JSX.Element;
+export declare namespace ExpandableTable {
+    var displayName: string;
+}

package/dist/patterns/ExpandableTable/index.d.ts

@@ -0,0 +1,2 @@
+export { ExpandableTable } from './ExpandableTable';
+export type { ExpandableTableBreakpoint, ExpandableTableColumn, ExpandableTableExpandedChange, ExpandableTableLabels, ExpandableTableProps, ExpandableTableReason, ExpandableTableRowContext, } from './types';

package/dist/patterns/ExpandableTable/styles.d.ts

@@ -0,0 +1,43 @@
+import { ExpandableTableBreakpoint } from './types';
+/**
+ * warning-50 (`#FFFBEB`), the prototype's pale amber row. Not `--warn-fill`
+ * (warning-100): on that, the `--sub` text a row's second line uses drops to
+ * 4.35:1. On this one `--sub` holds 4.67:1 and `--warn` 4.85:1, pinned in the
+ * tests.
+ */
+export declare const NEEDS_FIX_ROW_TINT: "#fffbeb";
+/** The toggle's chevron: down while closed, up while open. */
+export declare const EXPANDABLE_TABLE_CHEVRON_ICON = "solar:alt-arrow-down-outline";
+/** Before the open panel's title. */
+export declare const EXPANDABLE_TABLE_PANEL_ICON = "solar:pen-2-outline";
+/** `hidden <bp>:table-cell` per breakpoint, written out so Tailwind sees every class. */
+export declare const expandableTableHideBelowClass: Record<ExpandableTableBreakpoint, string>;
+export declare const expandableTableClass: {
+    /** The `VerticalSteps` card; scrolls sideways rather than overflow the page. */
+    readonly root: "w-full overflow-x-auto rounded-2xl border border-acct-border bg-acct-surface";
+    readonly table: "w-full";
+    readonly th: "text-left text-[11px] font-semibold uppercase tracking-[.04em] text-acct-sub px-4 pt-4 pb-3 whitespace-nowrap bg-transparent";
+    readonly alignRight: "text-right";
+    /** Shrinks to the toggle and the icon buttons. */
+    readonly thActions: "w-px";
+    readonly row: "border-t border-acct-hair transition-colors duration-150 hover:bg-acct-page data-[hover=true]:bg-acct-page";
+    readonly rowOpen: "bg-acct-page hover:bg-acct-page";
+    /** The admin cell had HeroUI's padding under it; a native cell needs its own (12px). */
+    readonly td: import('tailwind-variants').CnReturn;
+    readonly tdActions: "w-px whitespace-nowrap py-2 pl-2 pr-3 align-middle";
+    readonly actions: "flex items-center justify-end gap-0.5";
+    readonly toggle: "gap-1.5 text-acct-ink2 data-[hover=true]:bg-acct-hair";
+    readonly toggleOpen: "bg-acct-surface shadow-sm ring-1 ring-acct-border data-[hover=true]:bg-acct-surface";
+    readonly chevron: "size-4 shrink-0 transition-transform duration-150 motion-reduce:transition-none [html[data-pos-reduce-motion=true]_&]:transition-none";
+    readonly chevronOpen: "rotate-180";
+    /** The open panel's row: same tint as the open summary line, no hairline between them. */
+    readonly panelRow: "bg-acct-page";
+    readonly panelCell: "px-4 pb-4 pt-0";
+    readonly panel: "rounded-xl border border-acct-border bg-acct-surface p-4 shadow-sm";
+    /** 12px uppercase in `--sub` (4.83:1 on white). */
+    readonly panelTitle: "mb-4 flex items-center gap-1.5 border-b border-acct-hair pb-3 text-xs font-semibold uppercase tracking-wide text-acct-sub";
+    readonly panelTitleIcon: "size-3.5 shrink-0";
+    readonly panelFooter: "mt-4 flex flex-wrap items-center justify-end gap-2 border-t border-acct-hair pt-3";
+    readonly done: "border-acct-border bg-acct-surface";
+    readonly empty: "px-4 py-10 text-center text-sm text-acct-sub";
+};

package/dist/patterns/ExpandableTable/types.d.ts

@@ -0,0 +1,99 @@
+import { ReactNode } from 'react';
+import { RowAction } from '../RowActions';
+/** A breakpoint below which a column (header and cells) is not drawn. */
+export type ExpandableTableBreakpoint = 'sm' | 'md' | 'lg';
+export interface ExpandableTableColumn {
+    /** Stable id. `renderCell` receives it to know which cell it is drawing. */
+    key: string;
+    /** Header text. */
+    label: ReactNode;
+    /** `'right'` for numbers (price); `'left'` by default. */
+    align?: 'left' | 'right';
+    /** Width hint for the column: px number or any CSS length. Omit to size to content. */
+    width?: number | string;
+    /** Not drawn below this breakpoint, so a narrow screen keeps the columns that matter. */
+    hideBelow?: ExpandableTableBreakpoint;
+}
+/**
+ * Every string the table draws or speaks, translated by the host. No English
+ * lives in the component.
+ */
+export interface ExpandableTableLabels {
+    /** Visible text of each row's toggle ("Quick edit"). */
+    toggle: string;
+    /**
+     * Accessible name of one row's toggle, and of the panel it opens:
+     * `(rowLabel) => \`Quick edit ${rowLabel}\``. Keep `toggle` inside it, so
+     * voice control can say what it sees (WCAG 2.5.3).
+     */
+    toggleRow: (rowLabel: string) => string;
+    /** Header of the controls column, read by screen readers only ("Actions"). */
+    actions: string;
+    /** The button at the foot of an open panel that closes it ("Done"). */
+    done: string;
+    /** Small heading at the top of an open panel ("Quick edit"). Omit for none. */
+    panelTitle?: ReactNode;
+}
+/**
+ * Why a row closed or opened. `toggle` is the row's own button; the rest only
+ * close: `done` is the Done button or `close()`, `enter` is Enter in a
+ * single-line field, `escape` is Escape anywhere in the panel. Changes apply
+ * as the host's fields change, so none of them reverts anything; a host that
+ * keeps a draft can discard it on `escape`.
+ */
+export type ExpandableTableReason = 'toggle' | 'done' | 'enter' | 'escape';
+export interface ExpandableTableExpandedChange {
+    /** The row that opened or closed. */
+    key: string;
+    expanded: boolean;
+    reason: ExpandableTableReason;
+}
+/** What `renderExpanded` and `renderExpandedActions` get besides the row. */
+export interface ExpandableTableRowContext {
+    rowIndex: number;
+    /** Closes this row's panel and returns focus to its toggle (reason `done`). */
+    close: () => void;
+}
+export interface ExpandableTableProps<Row> {
+    /** Accessible name of the table ("Ticket types"). */
+    ariaLabel: string;
+    columns: ExpandableTableColumn[];
+    rows: Row[];
+    /** Stable, unique id of a row: keys its group, its test ids and the open set. */
+    getRowKey: (row: Row) => string;
+    /** Short name of a row ("Adult"), used in the accessible names of its controls. */
+    getRowLabel: (row: Row) => string;
+    /** One cell of the summary line. */
+    renderCell: (row: Row, columnKey: string, rowIndex: number) => ReactNode;
+    /** The fields an open row shows under its summary line (the Quick edit form). */
+    renderExpanded: (row: Row, context: ExpandableTableRowContext) => ReactNode;
+    /** Buttons at the foot of an open row, before Done ("More details"). */
+    renderExpandedActions?: (row: Row, context: ExpandableTableRowContext) => ReactNode;
+    /**
+     * Icon buttons after the toggle, drawn by `RowActions` (Duplicate, All
+     * details, Delete). Name each with its subject: "Duplicate Adult".
+     */
+    getRowActions?: (row: Row, rowIndex: number) => RowAction[];
+    /**
+     * Rows that need a fix get a pale warning tint (warning-50) while closed,
+     * and `data-needs-fix="true"`. The tint is a cue, not the message: say what
+     * is missing in a cell, as text.
+     */
+    rowNeedsFix?: (row: Row) => boolean;
+    /** Open rows, controlled. Several can be open at once. */
+    expandedKeys?: Iterable<string>;
+    /** Open rows at first render, uncontrolled. */
+    defaultExpandedKeys?: Iterable<string>;
+    /** Every open or close, with the new open set and which row changed why. */
+    onExpandedChange?: (keys: Set<string>, change: ExpandableTableExpandedChange) => void;
+    labels: ExpandableTableLabels;
+    /** Shown in place of the rows when there are none. */
+    emptyContent?: ReactNode;
+    className?: string;
+    /**
+     * Root test id (default `expandable-table`). Per row: `-row-<key>` (with
+     * `data-expanded` and `data-needs-fix`), `-toggle-<key>`, `-panel-<key>`,
+     * `-done-<key>` and `-actions-<key>` (each action `-actions-<key>-<action>`).
+     */
+    'data-testid'?: string;
+}

package/dist/patterns/NeedsFixDot/NeedsFixDot.d.ts

@@ -0,0 +1,16 @@
+import { JSX } from 'react';
+export interface NeedsFixDotProps {
+    /**
+     * Read out in place of the dot ("Needs a fix"). Required: without it the
+     * state is color alone. It follows the label it sits beside, so include any
+     * punctuation your language wants between the two.
+     */
+    label: string;
+    className?: string;
+    /** Root test id. The visible dot is `${data-testid}-mark`. */
+    'data-testid'?: string;
+}
+export declare function NeedsFixDot({ label, className, 'data-testid': dataTestId, }: NeedsFixDotProps): JSX.Element;
+export declare namespace NeedsFixDot {
+    var displayName: string;
+}

package/dist/patterns/NeedsFixDot/firstNeedsFixKey.d.ts

@@ -0,0 +1,18 @@
+/** The shape `firstNeedsFixKey` reads: an `UnderlineTabItem`, or any keyed item. */
+export interface NeedsFixItem<K extends string = string> {
+    key: K;
+    needsFix?: boolean;
+    isDisabled?: boolean;
+}
+/**
+ * The key a details panel should open on: the first item that needs a fix and
+ * can be selected, else `fallback`.
+ *
+ * A pure helper rather than tab behaviour, because only the host knows when
+ * the panel "opens" — moving to the next record keeps the tab the user is on.
+ *
+ * ```ts
+ * if (justOpened) setTab(firstNeedsFixKey(tabs, 'general'));
+ * ```
+ */
+export declare function firstNeedsFixKey<K extends string>(items: ReadonlyArray<NeedsFixItem<K>>, fallback: K): K;

package/dist/patterns/NeedsFixDot/index.d.ts

@@ -0,0 +1,4 @@
+export { NeedsFixDot } from './NeedsFixDot';
+export { firstNeedsFixKey } from './firstNeedsFixKey';
+export type { NeedsFixDotProps } from './NeedsFixDot';
+export type { NeedsFixItem } from './firstNeedsFixKey';

package/dist/patterns/NeedsFixDot/styles.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The needs-fix dot's appearance, in one place.
+ *
+ * The color is inline, read from `adminSurfaceTokens`, not a Tailwind class:
+ * the dot carries meaning, so it must survive a consumer whose Tailwind
+ * `content` globs miss this package. Same reasoning as `VerticalSteps`'
+ * status tones and `StatusChip`'s `DOT_TONE`.
+ */
+/**
+ * `--warn` (warning-700), the tone `VerticalSteps` paints a step that needs a
+ * fix with. The prototype's amber-500 measures 2.15:1 on white, under the 3:1
+ * WCAG 1.4.11 asks of a graphic a sighted user reads state from; warning-700
+ * measures 5.02:1.
+ */
+export declare const NEEDS_FIX_DOT_COLOR: string;
+export declare const needsFixDotClass: {
+    readonly root: "inline-flex shrink-0 items-center";
+    /** 6px, the prototype's `size-1.5`, in rem so a root font size change scales it. */
+    readonly dot: "block size-1.5 shrink-0 rounded-full";
+};

package/dist/patterns/TimeField/TimeField.d.ts

@@ -0,0 +1,6 @@
+import { JSX } from 'react';
+import { TimeFieldProps } from './types';
+export declare function TimeField({ value: valueProp, defaultValue, onChange, label, 'aria-label': ariaLabel, placeholder, emptyContent, invalidMessage, minTime, minTimeMessage, listStart, listEnd, listStep, locale, isRequired, isDisabled, isInvalid, errorMessage, isClearable, clearLabel, onBlur, size, variant, labelPlacement, className, inputProps, popoverProps, 'data-testid': dataTestId, }: TimeFieldProps): JSX.Element;
+export declare namespace TimeField {
+    var displayName: string;
+}

package/dist/patterns/TimeField/index.d.ts

@@ -0,0 +1,3 @@
+export { TimeField } from './TimeField';
+export { parseTimeInput } from './time';
+export type { TimeFieldProps } from './types';

package/dist/patterns/TimeField/time.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The time logic behind {@link TimeField}, kept free of React so it can be
+ * tested and reused on its own. Every time in and out is 24-hour `"HH:mm"`.
+ */
+/** Minutes since midnight of an `"HH:mm"` time. */
+export declare function toMinutes(time: string): number;
+/**
+ * Read typed text as a time: `"HH:mm"`, or `null` when it is not one.
+ *
+ * Forgiving on purpose: `"7:15 pm"`, `"7:15pm"`, `"715p"`, `"7p"`, `"19:15"`,
+ * `"1915"` and `"7"` all work; case, spaces and dots do not matter
+ * (`"7:15 P.M."`). Without am/pm, hours 1–6 read as afternoon (no venue opens
+ * at 3 AM) and every other hour as 24-hour: `"3"` is 15:00, `"7"` is 07:00,
+ * `"19"` is 19:00, `"0"` is midnight.
+ *
+ * @example
+ * parseTimeInput('715p'); // '19:15'
+ * parseTimeInput('3');    // '15:00'
+ * parseTimeInput('25');   // null
+ */
+export declare function parseTimeInput(input: string): string | null;
+/**
+ * The suggested times: `start` to `end` inclusive, every `step` whole
+ * minutes. Empty when `step` is under a minute or `end` is before `start`.
+ */
+export declare function buildTimeOptions(start: string, end: string, step: number): string[];
+/**
+ * Whether the list keeps `time` while `query` is typed. It compares against
+ * the 12-hour form (`"7:30"`) and the 24-hour forms (`"19:30"`, `"07:30"`), so
+ * it does not depend on how the label is formatted: `"7"` keeps 7:00 and
+ * 7:30 AM and PM, `"7p"` only the PM ones, `"19"` the 7 PM ones, `"p"` every
+ * PM time.
+ */
+export declare function matchesTimeQuery(time: string, query: string): boolean;
+/**
+ * The label for a time in `locale`: `"7:15 PM"` in `en-US`, `"19:15"` in
+ * `en-GB`, `"7:15 p. m."` in `es-CO`. No-break spaces become plain ones, so
+ * the label matches what people type and what tests search for.
+ */
+export declare function formatTimeLabel(time: string, locale: string): string;

package/dist/patterns/TimeField/types.d.ts

@@ -0,0 +1,77 @@
+import { FocusEvent, ReactNode } from 'react';
+import { AutocompleteProps } from '../../components';
+/** One row of the list: the `"HH:mm"` key and its locale label. */
+export interface TimeFieldOption {
+    key: string;
+    label: string;
+}
+export interface TimeFieldProps {
+    /**
+     * The time as 24-hour `"HH:mm"` text, or `null` for none. Omit for
+     * uncontrolled mode.
+     */
+    value?: string | null;
+    /** Starting time in uncontrolled mode. */
+    defaultValue?: string | null;
+    /** Called with the committed `"HH:mm"`, or `null` when a clearable field is emptied. */
+    onChange?: (time: string | null) => void;
+    /** Visible label. Without one, pass `aria-label`. */
+    label?: ReactNode;
+    'aria-label'?: string;
+    /** "e.g. 7:15 PM". */
+    placeholder?: string;
+    /**
+     * Shown in the list when nothing matches the typed text, or the text was
+     * erased ("Type a time like 7:15 PM"). Required and non-empty: HeroUI's
+     * own is English, and an Autocomplete that hides an empty list loses its
+     * options to `aria-hidden` when they come back.
+     */
+    emptyContent: ReactNode;
+    /** Shown when the typed text is not a time ("Enter a time like 7:15 PM."). */
+    invalidMessage: ReactNode;
+    /**
+     * Earliest allowed `"HH:mm"`. Earlier times leave the list, and typing
+     * one, or receiving one as `value`, shows `minTimeMessage`.
+     */
+    minTime?: string;
+    /** Shown for a time before `minTime` ("Ends after it starts."). Defaults to `invalidMessage`. */
+    minTimeMessage?: ReactNode;
+    /** First time the list suggests. @default '07:00' */
+    listStart?: string;
+    /** Last time the list suggests, inclusive. @default '21:00' */
+    listEnd?: string;
+    /** Minutes between suggested times. @default 30 */
+    listStep?: number;
+    /**
+     * BCP 47 locale the times are written in: "7:15 PM" in `en-US`, "19:15"
+     * in `en-GB`. Pass the same one as `HeroUIProvider`. @default 'en-US'
+     */
+    locale?: string;
+    isRequired?: boolean;
+    isDisabled?: boolean;
+    /** Marks the field invalid from outside; `errorMessage` is shown with it. */
+    isInvalid?: boolean;
+    errorMessage?: ReactNode;
+    /**
+     * Whether the field may be emptied: a clear button shows, and leaving it
+     * empty commits `null`. Otherwise leaving it empty restores the time it
+     * had. @default false
+     */
+    isClearable?: boolean;
+    /** Accessible name of the clear button ("Clear time"); HeroUI gives it none. */
+    clearLabel?: string;
+    /** Called after the field has committed what was typed (react-hook-form's `field.onBlur`). */
+    onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
+    size?: AutocompleteProps['size'];
+    /** @default 'bordered' */
+    variant?: AutocompleteProps['variant'];
+    /** @default 'outside-top' */
+    labelPlacement?: AutocompleteProps['labelPlacement'];
+    className?: string;
+    /** Passed to HeroUI's input: `{ classNames: { inputWrapper: 'h-11' } }`. */
+    inputProps?: AutocompleteProps['inputProps'];
+    /** Passed to HeroUI's popover. */
+    popoverProps?: AutocompleteProps['popoverProps'];
+    /** Lands on the `<input>`. Options get `${data-testid}-option-${HH:mm}`. */
+    'data-testid'?: string;
+}

package/dist/patterns/UnderlineTabs/UnderlineTabs.d.ts

@@ -30,6 +30,12 @@ export interface UnderlineTabItem<K extends string = string> {
      * cannot be gifted").
      */
     hint?: string;
+    /**
+     * Something on this tab's panel needs a fix: a warning dot after the label,
+     * and `needsFixLabel` read out with the tab's name. Pick the tab a panel
+     * opens on with `firstNeedsFixKey(items, fallback)`.
+     */
+    needsFix?: boolean;
 }
 export interface UnderlineTabsProps<K extends string = string> {
     items: UnderlineTabItem<K>[];
@@ -49,10 +55,16 @@ export interface UnderlineTabsProps<K extends string = string> {
      * follows. `false`: neither, for a strip at the foot of a card.
      */
     showDivider?: boolean;
+    /**
+     * Spoken after the name of a tab with `needsFix` ("Needs a fix"), in place
+     * of the dot, which is hidden from assistive tech. Pass it whenever an
+     * item can need a fix: without it the state is color alone.
+     */
+    needsFixLabel?: string;
     className?: string;
     'data-testid'?: string;
 }
-export declare function UnderlineTabs<K extends string = string>({ items, value, onChange, ariaLabel, size, level, showDivider, className, 'data-testid': dataTestId, }: UnderlineTabsProps<K>): import("react/jsx-runtime").JSX.Element;
+export declare function UnderlineTabs<K extends string = string>({ items, value, onChange, ariaLabel, size, level, showDivider, needsFixLabel, className, 'data-testid': dataTestId, }: UnderlineTabsProps<K>): import("react/jsx-runtime").JSX.Element;
 export declare namespace UnderlineTabs {
     var displayName: string;
 }

package/dist/patterns/UnderlineTabs/styles.d.ts

@@ -12,5 +12,10 @@ export declare const underlineTabsSlots: Record<'md' | 'lg' | 'sm-primary' | 'sm
  * `base`, so both slots drop theirs (and `-mb-px`, which only overlapped it).
  */
 export declare const underlineTabsNoDivider: Pick<UnderlineTabsSlots, 'base' | 'tabList'>;
+/**
+ * The title of a tab with `needsFix`: the label, then the dot 6px after it
+ * (the prototype's `gap-1.5`), centred on the label's line.
+ */
+export declare const underlineTabsNeedsFixTitleClass = "inline-flex items-center gap-1.5";
 /** Added to the `md` cursor under reduced motion: it jumps instead of sliding. */
 export declare const stillCursorClass = "data-[animated=true]:transition-none";

package/dist/patterns/index.d.ts

@@ -59,6 +59,10 @@ export { TableSkeleton } from './TableSkeleton';
 export type { TableSkeletonProps, TableSkeletonClassNames } from './TableSkeleton';
 export { AdminTable, adminRowClass, adminTableClass, adminTableFooterClass, adminTdClass, adminThClass, } from './AdminTable';
 export type { AdminTableProps, AdminTableColumn, AdminTableClassNames } from './AdminTable';
+export { ExpandableTable } from './ExpandableTable';
+export type { ExpandableTableBreakpoint, ExpandableTableColumn, ExpandableTableExpandedChange, ExpandableTableLabels, ExpandableTableProps, ExpandableTableReason, ExpandableTableRowContext, } from './ExpandableTable';
+export { NeedsFixDot, firstNeedsFixKey } from './NeedsFixDot';
+export type { NeedsFixDotProps, NeedsFixItem } from './NeedsFixDot';
 export { AdminToolbar } from './AdminToolbar';
 export type { AdminToolbarProps, AdminToolbarSearchWidth, AdminToolbarSize } from './AdminToolbar';
 export { ToolbarButton } from './ToolbarButton';
@@ -67,6 +71,8 @@ export { UnderlineTabs } from './UnderlineTabs';
 export type { UnderlineTabsProps, UnderlineTabItem, UnderlineTabsSize, UnderlineTabsLevel } from './UnderlineTabs';
 export { AdminFieldLabel, AdminTextField, adminFieldErrorClass, adminFieldHelpButtonClass, adminFieldHelpContentClass, adminFieldHelpIconClass, adminFieldHintClass, adminFieldLabelClass, adminFieldLabelNoAutoMarkClass, adminFieldLabelRowClass, adminFieldLabelSuffixClass, adminFieldRequiredClass, adminInputClass, adminInputReadOnlyClass, adminInputWrapperClass, } from './AdminTextField';
 export type { AdminTextFieldProps, AdminFieldLabelProps, AdminFieldRequiredProps, AdminFieldHelpProps, } from './AdminTextField';
+export { TimeField, parseTimeInput } from './TimeField';
+export type { TimeFieldProps } from './TimeField';
 export { RowActions } from './RowActions';
 export type { RowActionsProps, RowAction } from './RowActions';
 export { PickerRow } from './PickerRow';

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@veevarts/design-system",
     "private": false,
-    "version": "2.1.0-beta.24",
+    "version": "2.1.0-beta.25",
     "type": "module",
     "main": "dist/index.js",
     "module": "dist/index.js",