@assure-one/design-system 1.41.2 → 1.43.0

package/dist/brand-scope-BOKu4iOc.d.ts

@@ -0,0 +1,262 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import { ReactNode } from 'react';
+import { C as ComboboxMessages } from './types-DlqmlVyZ.js';
+import { C as ControlSize } from './vocab-DornLJbW.js';
+
+/**
+ * L1a behaviour primitive (private). Not exported from the package.
+ *
+ * The canonical option model of every list-shaped control (W4-09; target
+ * architecture §32): `Select`, the coming `Combobox` (W4-10) and its
+ * `MultiSelect` preset (W4-11), the `SearchSelect` adapter (W4-12) and the
+ * `PeoplePicker` pattern all read one shape, in place of the six that ship
+ * today (`{value,label}`, `{id,label,group…}`, `{id,label,email}`,
+ * `{id,fullName}`, `{key,label,dot}`, `string[]`).
+ *
+ * Two halves:
+ *
+ * - {@link Option} and its accessors: what a row *is*. Consumers with domain
+ *   objects pass {@link OptionAccessors} (`getOptionValue`/`getOptionLabel`)
+ *   instead of remapping, and {@link toOptions} normalises everything — a
+ *   `string[]`, domain objects, `Option`s — into one array the list renders.
+ * - The selection helpers: what a control's *value* is, discriminated by
+ *   `multiple` (single `TValue | null`, multi `TValue[]`; §32 "Value"). `""`
+ *   keeps meaning empty in 2.x (§32 "Compat"), so {@link normalizeSingleValue}
+ *   folds it to `null` at the boundary.
+ *
+ * No React, no client directive, no DOM: plain functions over plain data, so
+ * the same module serves a Server Component, a test and the keyboard helper.
+ */
+/**
+ * One row of a list-shaped control.
+ *
+ * `value` is never `""`: emptiness is `value === null` on the control, not a
+ * sentinel row (§32). `label` is the string typeahead, filtering and the
+ * accessible name read; `description` and `icon` are rendered, never searched.
+ * `keywords` widen the match without showing. `meta` carries consumer data
+ * through to `renderOption` / `onValueChange` details untouched.
+ *
+ * @experimental
+ */
+interface Option<TValue extends string = string, TMeta = unknown> {
+    value: TValue;
+    label: string;
+    description?: ReactNode;
+    /** Leading visual: icon, avatar, flag, colour swatch. */
+    icon?: ReactNode;
+    disabled?: boolean;
+    group?: string | undefined;
+    keywords?: readonly string[] | undefined;
+    meta?: TMeta;
+}
+/**
+ * How a list reads a consumer's own item type. Only `getOptionValue` and
+ * `getOptionLabel` are required: an item with no `disabled`/`group`/`keywords`
+ * accessor is enabled, ungrouped and matched on its label alone.
+ *
+ * @experimental
+ */
+interface OptionAccessors<TItem, TValue extends string = string> {
+    getOptionValue: (item: TItem) => TValue;
+    getOptionLabel: (item: TItem) => string;
+    getOptionDisabled?: ((item: TItem) => boolean) | undefined;
+    getOptionGroup?: ((item: TItem) => string | undefined) | undefined;
+    getOptionKeywords?: ((item: TItem) => readonly string[] | undefined) | undefined;
+}
+
+/** The English defaults (the `combobox` namespace of the catalogue). */
+declare const DEFAULT_COMBOBOX_MESSAGES: ComboboxMessages;
+/** The sizes a combobox offers: the shared control scale (A1). @experimental */
+type ComboboxSize = ControlSize;
+/** What `renderOption` is told about the row it renders. @experimental */
+interface ComboboxOptionState {
+    selected: boolean;
+    highlighted: boolean;
+    disabled: boolean;
+}
+/**
+ * Class overrides per part, for the consumer who must restyle one slot
+ * without reaching into the DOM.
+ *
+ * @experimental
+ */
+interface ComboboxClassNames {
+    root?: string;
+    control?: string;
+    input?: string;
+    chip?: string;
+    content?: string;
+    list?: string;
+    item?: string;
+}
+/** @experimental */
+interface ComboboxBaseProps<TItem, TValue extends string> extends Partial<OptionAccessors<TItem, TValue>> {
+    /** The rows: `Option`s, strings, or domain objects read through the accessors. */
+    options: readonly TItem[];
+    id?: string | undefined;
+    /** The form field name. Without it nothing is submitted. */
+    name?: string | undefined;
+    /** The `id` of the form to submit with when the control is rendered outside it. */
+    form?: string | undefined;
+    required?: boolean | undefined;
+    disabled?: boolean | undefined;
+    readOnly?: boolean | undefined;
+    invalid?: boolean | undefined;
+    /** The accessible name of a combobox outside a `Field`. */
+    "aria-label"?: string | undefined;
+    "aria-labelledby"?: string | undefined;
+    "aria-describedby"?: string | undefined;
+    placeholder?: string | undefined;
+    /** Outer height from the shared control scale. Default `md` (36px). */
+    size?: ComboboxSize | undefined;
+    /** A leading glyph inside the control, decorative. */
+    icon?: ReactNode | undefined;
+    /** Show a clear button while a value is set. Default `true`. */
+    clearable?: boolean | undefined;
+    /** Open the list when the input receives focus. Default `false`. */
+    openOnFocus?: boolean | undefined;
+    /** Whether the list surface flips to stay in the viewport. Default `true`. */
+    avoidCollisions?: boolean | undefined;
+    open?: boolean | undefined;
+    defaultOpen?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /** The typed query (controlled). */
+    search?: string | undefined;
+    defaultSearch?: string | undefined;
+    /** Called with every query the user types (an async source fetches here). */
+    onSearchChange?: ((query: string) => void) | undefined;
+    /**
+     * Filter `options` by the query (`true`, the default). `false` when the
+     * consumer filters — the options are already the answer to the query.
+     */
+    shouldFilter?: boolean | undefined;
+    /** An async source is fetching: a spinner in the control, `loadingState` in the list. */
+    loading?: boolean | undefined;
+    emptyState?: ReactNode | undefined;
+    loadingState?: ReactNode | undefined;
+    /** Rendered above the list, inside the popover. */
+    header?: ReactNode | undefined;
+    /** Rendered below the list, inside the popover. */
+    footer?: ReactNode | undefined;
+    /** Offer a "Create …" row for a query that matches no option exactly. */
+    onCreate?: ((query: string) => void) | undefined;
+    /** Replaces the content of a row. */
+    renderOption?: ((option: Option<TValue, unknown>, state: ComboboxOptionState) => ReactNode) | undefined;
+    messages?: Partial<ComboboxMessages> | undefined;
+    className?: string | undefined;
+    classNames?: ComboboxClassNames | undefined;
+    /** The input element. */
+    ref?: React$1.Ref<HTMLInputElement> | undefined;
+}
+/** @experimental */
+interface ComboboxSingleProps<TItem, TValue extends string> extends ComboboxBaseProps<TItem, TValue> {
+    multiple?: false | undefined;
+    /** The picked value, or `null`. `""` means empty (2.x compat). */
+    value?: TValue | "" | null | undefined;
+    defaultValue?: TValue | "" | null | undefined;
+    onValueChange?: ((value: TValue | null, details: {
+        option: Option<TValue, unknown> | null;
+    }) => void) | undefined;
+    /** Replaces the closed control's text for the picked option. */
+    renderValue?: ((option: Option<TValue, unknown>) => ReactNode) | undefined;
+    /** Close the list after a pick. Default `true`. */
+    closeOnSelect?: boolean | undefined;
+}
+/** What `renderValue` receives in `multiple` mode besides the picked options. @experimental */
+interface ComboboxSelectionControls<TValue extends string> {
+    /** Removes one value from the selection. */
+    remove: (value: TValue) => void;
+}
+/** @experimental */
+interface ComboboxMultipleProps<TItem, TValue extends string> extends ComboboxBaseProps<TItem, TValue> {
+    multiple: true;
+    /** The picked values, in pick order. Empty strings are dropped. */
+    value?: readonly (TValue | "")[] | undefined;
+    defaultValue?: readonly (TValue | "")[] | undefined;
+    onValueChange?: ((value: TValue[], details: {
+        option: Option<TValue, unknown> | null;
+    }) => void) | undefined;
+    /**
+     * Replaces the chips inside the control: called with the picked options
+     * and `remove`. Return `null` to render nothing there.
+     */
+    renderValue?: ((options: Option<TValue, unknown>[], controls: ComboboxSelectionControls<TValue>) => ReactNode) | undefined;
+    /** Close the list after a pick. Default `false`: keep picking. */
+    closeOnSelect?: boolean | undefined;
+    /** Drop picked rows from the list (the chips already show them). Default `false`. */
+    hideSelected?: boolean | undefined;
+}
+/**
+ * The props, discriminated by `multiple` (target architecture §32 "Value"):
+ * a single pick is `TValue | null`, a multi pick is `TValue[]`.
+ *
+ * @experimental
+ */
+type ComboboxProps<TItem = Option, TValue extends string = string> = ComboboxSingleProps<TItem, TValue> | ComboboxMultipleProps<TItem, TValue>;
+/**
+ * The searchable pick: one input, a portalled listbox, the option model.
+ * See the module comment.
+ *
+ * @experimental
+ */
+declare function Combobox<TItem = Option, TValue extends string = string>(props: ComboboxProps<TItem, TValue>): react_jsx_runtime.JSX.Element;
+declare namespace Combobox {
+    var displayName: string;
+}
+
+/**
+ * Brand scope — ambient product theming.
+ *
+ * The `brand` color family (bg-brand, hover:bg-brand-hover, bg-brand-bg,
+ * border-brand-line, text-fg-on-brand, plus the accent/focus/primary
+ * interaction tokens) follows the nearest `[data-brand]` scope and defaults to
+ * Pro. Authors type the STATE only; the product comes from the scope. Set it
+ * once high in the tree — ideally on the same root as the `.dark` class
+ * (`<html>`/`<body>`) — so Radix-portalled surfaces inherit it through the DOM.
+ *
+ *   <html data-brand="tax">           // whole shell renders teal
+ *   <div {...brandScope("audit")}>    // a subtree renders blue
+ *
+ * For the rarer case of multiple scopes on one page WITH portalled content
+ * (a Dialog/Popover that escapes its scoped subtree to document.body), wrap the
+ * region in <BrandScope> / <BrandScopeProvider> and have the portalled
+ * `*Content` re-stamp `data-brand={useBrandScope()}` on its own element.
+ */
+type BrandProduct = "pro" | "audit" | "books" | "tax";
+/**
+ * `data-brand` attribute object to spread on any element (mirrors
+ * `serviceToneStyle`). This is the primary API for opting a subtree into a
+ * product without naming the product in a utility class.
+ */
+declare function brandScope(product: BrandProduct): {
+    "data-brand": BrandProduct;
+};
+/** Every product, in suite order — for switchers and story matrices. */
+declare const BRAND_PRODUCTS: BrandProduct[];
+/** Human label for a product, for switchers and headings. */
+declare const brandLabel: Record<BrandProduct, string>;
+/**
+ * Provides the active product to descendants so portalled surfaces can
+ * re-stamp `data-brand` on themselves via {@link useBrandScope}. Purely a
+ * structural carrier — the visual theming still comes from the `[data-brand]`
+ * attribute in the DOM, not from this context.
+ */
+declare function BrandScopeProvider({ product, children, }: {
+    product: BrandProduct;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** Read the ambient product from the nearest provider (defaults to Pro). */
+declare function useBrandScope(): BrandProduct;
+interface BrandScopeProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The product this subtree renders as. */
+    product: BrandProduct;
+}
+/**
+ * Convenience wrapper that stamps `data-brand` on a `<div>` AND provides the
+ * product via context, so a portalled descendant can re-stamp itself. Use
+ * `brandScope()` directly when you want the attribute on your own element.
+ */
+declare const BrandScope: React$1.ForwardRefExoticComponent<BrandScopeProps & React$1.RefAttributes<HTMLDivElement>>;
+
+export { BRAND_PRODUCTS as B, type ComboboxSize as C, DEFAULT_COMBOBOX_MESSAGES as D, type Option as O, type BrandProduct as a, brandLabel as b, type ComboboxMultipleProps as c, type ComboboxProps as d, BrandScope as e, type BrandScopeProps as f, BrandScopeProvider as g, Combobox as h, type ComboboxBaseProps as i, type ComboboxClassNames as j, type ComboboxOptionState as k, type ComboboxSelectionControls as l, type ComboboxSingleProps as m, type OptionAccessors as n, brandScope as o, useBrandScope as u };