@techzyapp/ui-library 1.0.0

package/dist/theme/ConfigProvider.d.cts

@@ -0,0 +1,362 @@
+import { type ReactNode } from 'react';
+import { type ThemePalette } from './applyTheme';
+import { type AppMessages, type AppTranslator, type MessageOverrides, type Translator } from '../i18n/messages';
+export type ThemeMode = 'light' | 'dark';
+export interface ThemeColors {
+    /** Light-mode palette. Override any subset of the theme colors — the rest use the library defaults. */
+    light?: Partial<ThemePalette>;
+    /** Dark-mode overrides, layered on the (merged) light palette + the library's dark defaults. */
+    dark?: Partial<ThemePalette>;
+}
+/** A content locale the app supports — a tab in `<TranslatedFields>`. */
+export interface LocaleConfig {
+    /** BCP-47 locale code, e.g. `'en-US'`. Namespaces the form field names and is the tab's fallback label. */
+    code: string;
+    /** Human-readable tab label. Falls back to `code`. */
+    label?: string;
+}
+/** Theme settings — color overrides + initial mode. Lives under `Config.theme`. */
+export interface ThemeConfig {
+    /** Theme color overrides. Omit entirely to use the library's built-in theme. */
+    colors?: ThemeColors;
+    /** Initial color mode. */
+    mode?: ThemeMode;
+    /**
+     * Default font family — the app-wide default the user's Settings choice overrides (persisted). One of
+     * the pre-imported presets (`Inter` / `Roboto` / `Lato`) or any Google Font family name. Defaults to
+     * `Inter`. A non-preset family is loaded on demand at runtime.
+     */
+    fontFamily?: string;
+}
+/**
+ * The configurable key / param **names** the library's components read — grouped under `Config.keys`
+ * so they live in one place. Each is overridable; omit one to use its built-in default. Grows over
+ * time (e.g. `page` / `size` for paginated tables ⇒ `?page=1&size=10`).
+ */
+export interface KeysConfig {
+    /**
+     * URL query param name a **top-level** `<Tabs>` syncs its active tab to (e.g. `'view'` ⇒ `?view=…`),
+     * unless that strip sets its own `queryKey` (or `queryKey={null}` to opt out). Defaults to `'tab'`.
+     */
+    tabQueryKey?: string;
+    /**
+     * URL query param name a **nested** `<Tabs>` (one rendered inside another tab's panel) syncs to, so it
+     * doesn't collide with the outer strip's `tabQueryKey` (e.g. `?tab=…&nestedTab=…`). Auto-applied by
+     * nesting depth; overridable per strip via `queryKey`. Defaults to `'nestedTab'`.
+     */
+    nestedTabQueryKey?: string;
+    /**
+     * URL query param name a `<Stepper queryKey>` (the bare/`true` form) syncs its active step to
+     * (**1-based**, e.g. `?step=2`); a string `queryKey` overrides it per stepper. Defaults to `'step'`.
+     * (The sync itself is **opt-in** — a stepper with no `queryKey` never touches the URL.)
+     */
+    stepQueryKey?: string;
+    /**
+     * Top-level namespace word for `<TranslatedFields>`' form names + the nested object — e.g.
+     * `'languages'` ⇒ `languages[en-US].title`. Defaults to `'translations'`.
+     */
+    translationsNamespace?: string;
+}
+/**
+ * How a `<Table>` builds its **server-request** params — the query it hands the consumer (as `params` /
+ * `query`) in `onChange`, so a server-mode fetch doesn't hand-map page/size/search/sort every time. This is
+ * the **backend transport** layer, distinct from `keys.*QueryKey` (the browser-URL sync, always page-based
+ * for shareable links). Set once in `config.table.query`, override per table via the `queryMapping` prop.
+ * Every field is optional; the defaults reproduce the browser-URL shape (`?page=1&size=10&search=…&sort=-key`).
+ */
+export interface TableQueryConfig {
+    /** Request param name for the page / offset. Defaults to `'page'` (e.g. `'skip'` for an offset API). */
+    pageParam?: string;
+    /** Request param name for the page size. Defaults to `'size'` (e.g. `'limit'`). */
+    sizeParam?: string;
+    /** Request param name for the search query (omitted when the search is empty). Defaults to `'search'` (e.g. `'q'`). */
+    searchParam?: string;
+    /**
+     * Request param name holding the sort **key**. Defaults to `'sort'` (e.g. `'sortBy'`). With
+     * `sortFormat: 'field'` this single param also carries the direction (`-key` = desc); with `'separate'`
+     * the direction goes to `sortOrderParam`.
+     */
+    sortParam?: string;
+    /**
+     * Pagination style. `'page'` (default) emits the **1-based page number** as-is (`page=2`); `'offset'`
+     * emits a **zero-based offset** `(page - 1) * size` instead (`skip=10`), for skip/offset APIs.
+     */
+    pagination?: 'page' | 'offset';
+    /**
+     * Sort encoding. `'field'` (default) is a single param with a `-` prefix for descending (`sort=-price`);
+     * `'separate'` splits into two params — the key in `sortParam` + the direction in `sortOrderParam`
+     * (`sortBy=price&order=desc`); `'suffix'` appends the direction value to the key in a single param
+     * (`sort=priceAsc` / `sort=priceDesc` with `ascValue: 'Asc'` / `descValue: 'Desc'`).
+     */
+    sortFormat?: 'field' | 'separate' | 'suffix';
+    /** Direction param name when `sortFormat: 'separate'`. Defaults to `'order'`. */
+    sortOrderParam?: string;
+    /**
+     * Value emitted for an ascending sort — the `sortOrderParam` value when `sortFormat: 'separate'`, or the
+     * suffix appended to the key when `sortFormat: 'suffix'`. Defaults to `'asc'`.
+     */
+    ascValue?: string;
+    /**
+     * Value emitted for a descending sort — the `sortOrderParam` value when `sortFormat: 'separate'`, or the
+     * suffix appended to the key when `sortFormat: 'suffix'`. Defaults to `'desc'`.
+     */
+    descValue?: string;
+    /**
+     * What to emit for the size param when the **"All"** rows-per-page choice is active. A `string`/`number`
+     * sets `size=<allValue>` (e.g. `0` for APIs where `limit=0` means "all"); omit it (default) to drop the
+     * size param entirely (many APIs treat a missing limit as unbounded).
+     */
+    allValue?: string | number;
+    /**
+     * How a **`multiSelect`** filter serializes into the request query: `'repeat'` (default — `cat=a&cat=b`),
+     * `'csv'` (`cat=a,b`), or `'indexed'` (`cat[0]=a&cat[1]=b`).
+     */
+    multiSelectFormat?: 'repeat' | 'csv' | 'indexed';
+    /**
+     * Suffix appended to a **range** filter's param for its lower / upper bound — e.g. `Min`/`Max` (default)
+     * → `priceMin`/`priceMax`; set `'_gte'`/`'_lte'`, `'[gte]'`/`'[lte]'`, `'From'`/`'To'`, … to match your API.
+     */
+    rangeMinSuffix?: string;
+    rangeMaxSuffix?: string;
+}
+/** `<Table>`-specific configuration. Grows over time; today just the server-request query mapping. */
+export interface TableConfig {
+    /** How `<Table>` builds its server-request params (emitted as `params` / `query` in `onChange`). */
+    query?: TableQueryConfig;
+}
+/** Signed-in user shown in the shell header avatar + its account menu (see `HeaderConfig`). */
+export interface HeaderUser {
+    /** Full name — shown as the menu's name line. */
+    name?: string;
+    /** Email shown under the name in the account menu. */
+    email?: string;
+    /** Avatar image URL (falls back to a user icon). */
+    avatar?: string;
+}
+/**
+ * `RootLayout` header configuration — the shell's top-bar controls. Set it once app-wide in
+ * `config.header`, or per shell via the `RootLayout` `header` prop (the prop wins, merged over config).
+ */
+export interface HeaderConfig {
+    /** Show the built-in light/dark theme toggle. Defaults to `true`. */
+    theme?: boolean;
+    /**
+     * Make the shell header **stick to the top on scroll** (fixed) instead of scrolling away (static).
+     * This is the app-wide default; the user can flip it in the **Settings** drawer and their choice is
+     * persisted (`localStorage['tz-header-sticky']`), overriding this. Defaults to `false` (static).
+     */
+    sticky?: boolean;
+    /** Show the browser-fullscreen toggle (auto-hides where the Fullscreen API is unavailable). Defaults to `false`. */
+    fullscreen?: boolean;
+    /** Show the **Settings** button (opens the right-side drawer to pick the per-mode `accent`). Defaults to `true`. */
+    settings?: boolean;
+    /** Show the nav search over the sidebar's pages (with suggestions). Defaults to `true`. */
+    search?: boolean;
+    /**
+     * Show the header **language switcher** (the `Global`-icon dropdown of `config.i18n.languages`).
+     * Defaults to `true`, but it only renders when more than one UI language is configured — so pass
+     * `false` to hide it even with several languages (the panel stays on its current/default language).
+     */
+    languages?: boolean;
+    /** Show the breadcrumb trail at the top of the content. Defaults to **`true`**. */
+    breadcrumbs?: boolean;
+    /** Render the automatic page-title `h2` (the active route's `staticData.name`). Defaults to `true`. */
+    pageTitle?: boolean;
+    /** When provided, an account `Avatar` appears; its menu has a **Sign out** item that calls this. */
+    onLogout?: () => void;
+    /** Signed-in user — shown in the header avatar and as a header block atop the account menu. */
+    user?: HeaderUser;
+}
+/**
+ * UI-language config for the admin panel's **own** static strings (labels, placeholders, aria-labels).
+ * Distinct from `locales` (which is content-translation locales for `<TranslatedFields>`). The library
+ * ships built-in translations (English + Georgian), so listing `languages` here is enough to get a
+ * localized panel — no per-app setup. Any language the library doesn't ship is supplied via `messages`.
+ */
+export interface I18nConfig {
+    /**
+     * Active UI language on first load (a locale code, e.g. `'ka-GE'`). Defaults to English if listed in
+     * `languages`, else the first `languages` entry, else `'en-US'`. The user's switcher choice (persisted)
+     * overrides it.
+     */
+    language?: string;
+    /**
+     * The UI languages the panel offers — drives the Settings language switcher. One entry = a fixed
+     * language (no switcher). Defaults to English only. (Reuses the `{ code, label }` shape.)
+     */
+    languages?: LocaleConfig[];
+    /**
+     * Extra / override message catalogs for the **library's own** strings, merged **over** the built-ins
+     * and keyed by language code or base language (`'ka-GE'` or `'ka'`). Use this to localize into a
+     * language the library doesn't ship, or to tweak a built-in string. Unset keys fall back to English.
+     */
+    messages?: MessageOverrides;
+    /**
+     * Catalogs for the **consuming app's own** UI strings — its section titles, labels, business copy —
+     * keyed by language code/base then by any string key the app picks. Read via **`useTranslations()`**,
+     * which binds to the active UI language, so the app's text switches together with the panel. Resolution
+     * per key: exact code → base language → English (`'en'`) → the key itself. This is the app's own copy;
+     * `messages` above is only for the library's built-in strings.
+     */
+    appMessages?: AppMessages;
+}
+/**
+ * App-level configuration passed to `<ConfigProvider config={…}>`. Groups theming under `theme`,
+ * the configurable key/param names under `keys`, and keeps the rest (`locales`, …) at the top — a
+ * single place to grow.
+ */
+export interface Config {
+    /** Theme settings (color overrides + initial mode). Omit entirely to use the built-in theme. */
+    theme?: ThemeConfig;
+    /** Content locales the app supports — drive `<TranslatedFields>`' tabs (one per locale). */
+    locales?: LocaleConfig[];
+    /** UI-language config for the panel's own strings (the library ships the translations). See `I18nConfig`. */
+    i18n?: I18nConfig;
+    /**
+     * Configurable key / query-param names the components read — e.g. the `<Tabs>` query keys
+     * (`tabQueryKey` / `nestedTabQueryKey`) and the `<TranslatedFields>` namespace
+     * (`translationsNamespace`). Grows over time (`page`, `size`, …).
+     */
+    keys?: KeysConfig;
+    /** `<Table>` config — today the server-request query mapping (`table.query`) shared by every table. */
+    table?: TableConfig;
+    /**
+     * `RootLayout` header config, app-wide — the shell top-bar toggles (`theme` / `fullscreen` /
+     * `search` / `breadcrumbs` / `pageTitle`) + the account (`onLogout` / `user`). A `RootLayout`
+     * `header` prop is merged over this (the prop wins), so a specific shell can override.
+     */
+    header?: HeaderConfig;
+}
+interface ThemeContextValue {
+    mode: ThemeMode;
+    setMode: (mode: ThemeMode) => void;
+    toggleMode: () => void;
+    /** The persisted accent-color overrides **per mode** (a hex, or `null` when using that mode's default). */
+    accentColors: Record<ThemeMode, string | null>;
+    /** The configured/default `accent` **per mode** (before any override) — the "no override" values. */
+    defaultAccentColors: Record<ThemeMode, string>;
+    /** Set (or clear with `null`) the accent override for `mode` (defaults to the current) — persists + re-applies. */
+    setAccentColor: (color: string | null, mode?: ThemeMode) => void;
+    locales: LocaleConfig[];
+    /** Resolved translations namespace (`config.keys.translationsNamespace` ?? the built-in default). */
+    translationsNamespace: string;
+    /** Resolved top-level tabs query key (`config.keys.tabQueryKey` ?? the built-in default). */
+    tabQueryKey: string;
+    /** Resolved nested tabs query key (`config.keys.nestedTabQueryKey` ?? the built-in default). */
+    nestedTabQueryKey: string;
+    /** Resolved stepper query key (`config.keys.stepQueryKey` ?? the built-in default). */
+    stepQueryKey: string;
+    /** The `<Table>` server-request query mapping (`config.table.query` ?? `{}`). Defaults applied by `buildTableQuery`. */
+    tableQuery: TableQueryConfig;
+    /** App-wide `RootLayout` header config (`config.header` ?? `{}`); the `RootLayout` prop merges over it. */
+    header: HeaderConfig;
+    /** Whether the shell header sticks to the top on scroll (fixed) vs scrolls away (static). Persisted. */
+    headerSticky: boolean;
+    /** Set + persist the header sticky/static preference (overrides `config.header.sticky`). */
+    setHeaderSticky: (sticky: boolean) => void;
+    /** The active font family (drives `--tz-font-family`). Persisted; seeded from `config.theme.fontFamily`. */
+    fontFamily: string;
+    /** Set + persist the font family (a preset or any Google Font name; loaded on demand). */
+    setFontFamily: (family: string) => void;
+    /** Active UI language code (drives `t`). Persisted; seeded from `config.i18n.language` (default English). */
+    language: string;
+    /** Set + persist the active UI language (must be one of `languages`). */
+    setLanguage: (code: string) => void;
+    /** The UI languages the panel offers (from `config.i18n.languages`, default English only). */
+    languages: LocaleConfig[];
+    /** Translator for the library's built-in strings, bound to the active `language`. */
+    t: Translator;
+    /** Translator for the **app's own** strings (`config.i18n.appMessages`), bound to the active `language`. */
+    appT: AppTranslator;
+}
+/** The default font family (matches the `--tz-font-family` token's primary family). */
+export declare const DEFAULT_FONT_FAMILY = "Inter";
+/** The built-in default URL query param name a **top-level** `<Tabs>` syncs to (no `queryKey`/config). */
+export declare const DEFAULT_TABS_QUERY_KEY = "tab";
+/** The built-in default URL query param name a **nested** `<Tabs>` syncs to (no `queryKey`/config). */
+export declare const DEFAULT_NESTED_TAB_QUERY_KEY = "nestedTab";
+/** The built-in default URL query param name a `<Stepper>` syncs to (no `queryKey`/config). */
+export declare const DEFAULT_STEP_QUERY_KEY = "step";
+export interface ConfigProviderProps {
+    /** App config — theme overrides, initial mode, locales. Omit for the built-in defaults (light mode). */
+    config?: Config;
+    children: ReactNode;
+}
+export declare function ConfigProvider({ config, children }: ConfigProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useTheme(): ThemeContextValue;
+/**
+ * The content locales configured on `<ConfigProvider config={{ locales }}>`. Lenient — returns `[]`
+ * outside a provider (locales are optional), so `<TranslatedFields>` can also take a `locales` prop.
+ */
+export declare function useLocales(): LocaleConfig[];
+/**
+ * The translator for the library's built-in UI strings, bound to the active `config.i18n` language.
+ * **Lenient** — outside a provider it returns an English translator, so components render standalone
+ * (and in tests) with their default English labels. Use it for any built-in string:
+ * `t('select.noOptions')`.
+ */
+export declare function useT(): Translator;
+/**
+ * Translator for the **consuming app's own** strings — the catalogs passed to
+ * `<ConfigProvider config={{ i18n: { appMessages } }}>` — bound to the active UI language, so the app's
+ * copy switches together with the panel. Free-form string keys; per key it resolves exact code → base
+ * language → English (`'en'`) → the key itself, with `{name}` interpolation:
+ *
+ * ```tsx
+ * const t = useTranslations()
+ * <PageLayout title={t('customer-transactions.title')} />
+ * <p>{t('customer-transactions.count', { count: 128 })}</p>
+ * ```
+ *
+ * **Lenient** — outside a provider (or with no `appMessages`) it echoes the key back, so it's safe
+ * anywhere. Use `useT()` for the library's built-in strings; use this for your own.
+ */
+export declare function useTranslations(): AppTranslator;
+/**
+ * The active UI language + switcher data: `{ language, setLanguage, languages }`. Lenient outside a
+ * provider (English, single language, no-op setter) so it's safe to call anywhere.
+ */
+export declare function useLanguage(): {
+    language: string;
+    setLanguage: (code: string) => void;
+    languages: LocaleConfig[];
+};
+/**
+ * The translations namespace configured on `<ConfigProvider config={{ keys: { translationsNamespace } }}>`,
+ * resolved against the built-in default (`'translations'`). Lenient outside a provider. Use it to pass
+ * the same namespace to the helpers, e.g. `buildTranslations(codes, fields, useTranslationsNamespace())`.
+ */
+export declare function useTranslationsNamespace(): string;
+/**
+ * The default top-level tabs query key configured on `<ConfigProvider config={{ keys: { tabQueryKey } }}>`,
+ * resolved against the built-in default (`'tab'`). Lenient outside a provider. A top-level `<Tabs>` reads
+ * it as the fallback for an omitted `queryKey`, so every tab strip URL-syncs out of the box.
+ */
+export declare function useTabsQueryKey(): string;
+/**
+ * The default nested tabs query key configured on
+ * `<ConfigProvider config={{ keys: { nestedTabQueryKey } }}>`, resolved against the built-in default
+ * (`'nestedTab'`). Lenient outside a provider. A `<Tabs>` nested inside another tab's panel uses this
+ * (instead of `tabQueryKey`) so the two strips don't collide on the same URL param.
+ */
+export declare function useNestedTabQueryKey(): string;
+/**
+ * The default stepper query key configured on `<ConfigProvider config={{ keys: { stepQueryKey } }}>`,
+ * resolved against the built-in default (`'step'`). Lenient outside a provider. A `<Stepper queryKey>`
+ * (the bare/`true` opt-in form) reads it as the param name; a string `queryKey` overrides it.
+ */
+export declare function useStepQueryKey(): string;
+/**
+ * The `<Table>` server-request query mapping configured on `<ConfigProvider config={{ table: { query } }}>`
+ * (`{}` when unset / outside a provider). `<Table>` merges its own `queryMapping` prop over this, then feeds
+ * the result to `buildTableQuery`, which applies the field defaults — so an unconfigured table emits the
+ * default page-based `?page=…&size=…&search=…&sort=…` shape.
+ */
+export declare function useTableQueryConfig(): TableQueryConfig;
+/**
+ * The app-wide `RootLayout` header config set on `<ConfigProvider config={{ header }}>` (`{}` when
+ * unset / outside a provider). `RootLayout` merges its own `header` prop over this (the prop wins), so
+ * a specific shell can override the app-wide defaults.
+ */
+export declare function useHeaderConfig(): HeaderConfig;
+export {};