alepha/dist/react/ui/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { Static } from "alepha";
import { FormModel } from "alepha/react/form";
//#region ../../src/react/ui/atoms/uiAtom.d.ts
/**
 * Persisted UI state — color mode, theme palette, sidebar collapsed state, etc.
 *
 * The atom is bound to a single `alepha-ui` cookie via {@link UiPersistence},
 * so values survive page reloads and are available during SSR.
 */
declare const uiAtom: import("alepha").Atom<import("zod").ZodObject<{
  mode: import("zod").ZodEnum<{
    dark: "dark";
    light: "light";
    system: "system";
  }>;
  theme: import("zod").ZodString;
  sidebar: import("zod").ZodObject<{
    collapsed: import("zod").ZodBoolean;
  }, import("zod/v4/core").$strip>;
}, import("zod/v4/core").$strip>, "alepha.react.ui">;
type UiState = Static<typeof uiAtom.schema>;
//#endregion
//#region ../../src/react/ui/atoms/uiThemeListAtom.d.ts
/**
 * Available themes the user can pick from. Apps populate this atom on boot
 * (e.g. `alepha.store.set(uiThemeListAtom, MY_THEMES)`); UI consumers like
 * `<ButtonTheme/>` read it to render a picker. The selected theme id is
 * persisted separately in `uiAtom.theme`.
 *
 * Defaults to a single `"default"` entry so the registry stays usable when
 * an app doesn't declare its own list.
 */
declare const uiThemeListAtom: import("alepha").Atom<import("zod").ZodArray<import("zod").ZodObject<{
  id: import("zod").ZodString;
  label: import("zod").ZodString;
  swatch: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
  fontHref: import("zod").ZodOptional<import("zod").ZodString>;
}, import("zod/v4/core").$strip>>, "alepha.react.ui.themes">;
type UiThemeList = Static<typeof uiThemeListAtom.schema>;
type UiTheme = UiThemeList[number];
//#endregion
//#region ../../src/react/ui/components/ColorScheme.d.ts
/**
 * Applies `class="dark"` and an optional theme palette class
 * (`theme-<name>`) to the document root, syncing whenever the underlying
 * atom mutates.
 *
 * Mount once near the root of your tree (typically inside the layout).
 *
 * @example
 * <ColorScheme />
 */
declare function ColorScheme(): null;
//#endregion
//#region ../../src/react/ui/hooks/useColorMode.d.ts
type ColorMode = "light" | "dark" | "system";
type ResolvedColorMode = "light" | "dark";
/**
 * Read and update the user's color-mode preference. `"system"` resolves to
 * the OS preference and updates live as the OS toggles between light/dark.
 *
 * @example
 * const { mode, setMode, resolved } = useColorMode();
 * setMode("dark");
 * document.documentElement.classList.toggle("dark", resolved === "dark");
 */
declare const useColorMode: () => {
  mode: ColorMode;
  resolved: ResolvedColorMode;
  setMode: (next: ColorMode) => void;
};
//#endregion
//#region ../../src/react/ui/hooks/useSidebarState.d.ts
/**
 * Read and update the sidebar collapsed state. The value is persisted via the
 * `alepha-ui` cookie so it survives reloads and is available during SSR — no
 * flash of expanded-then-collapsed when the user prefers a collapsed shell.
 *
 * @example
 * const { collapsed, setCollapsed, toggle } = useSidebarState();
 */
declare const useSidebarState: () => {
  collapsed: boolean;
  setCollapsed: (next: boolean) => void;
  toggle: () => void;
};
//#endregion
//#region ../../src/react/ui/hooks/useTheme.d.ts
/**
 * Read and update the active theme palette name. UI consumers typically map
 * the value to a class on the document root (e.g. `theme-claude`).
 *
 * @example
 * const { theme, setTheme } = useTheme();
 * setTheme("claude");
 */
declare const useTheme: () => {
  theme: string;
  setTheme: (next: string) => void;
};
//#endregion
//#region ../../src/react/ui/services/SchemaControl.d.ts
/**
 * Schema-bound metadata read by `<Control>` (in `@alepha/ui`) to configure
 * how a field renders. Place under `$control` on any TypeBox schema option.
 *
 * Two forms:
 *
 * 1. **Object** — static configuration baked into the schema:
 *    ```ts
 *    z.string({ $control: { password: true, icon: "key" } })
 *    ```
 *
 * 2. **Function** — dynamic, computed from current form state:
 *    ```ts
 *    z.string({
 *      $control: ({ form, value }) => {
 *        if (form.currentValues.kind !== "advanced") return false; // hide
 *        return { items: () => fetchOptions(form.currentValues.kind) };
 *      },
 *    })
 *    ```
 *
 * The function may return:
 * - a partial `SchemaControl` to merge with explicit `<Control>` props
 * - `false` to hide the control entirely
 * - `undefined` to leave the field as-is
 */
interface SchemaControl {
  text?: boolean;
  area?: boolean;
  password?: boolean;
  switch?: boolean;
  number?: boolean;
  file?: boolean;
  date?: boolean;
  datetime?: boolean;
  time?: boolean;
  select?: boolean;
  combobox?: boolean;
  segmented?: boolean;
  slider?: boolean;
  object?: boolean;
  array?: boolean;
  /**
   * Icon name. The registry control maps this to its icon set
   * (lucide-react). Pass `null` to suppress the schema-inferred icon.
   */
  icon?: string | null;
  label?: string;
  description?: string;
  placeholder?: string;
  /**
   * HTML `autocomplete` attribute. Use standard tokens like
   * `"username"`, `"email"`, `"new-password"`, `"current-password"`,
   * `"street-address"`, `"address-line1"`, `"address-level2"` (city),
   * `"postal-code"`, `"country"`, `"cc-number"`, `"cc-exp"`,
   * `"cc-csc"`, `"cc-name"`, `"tel"`, etc.
   */
  autoComplete?: string;
  /**
   * Static or async option list for select / combobox / multi-select.
   * Each item is either a bare string (used as both value & label) or a
   * `{ value, label, description?, tag? }` object.
   */
  items?: Array<string | SchemaControlItem> | SchemaControlItemsFn;
  /**
   * Re-fetch `items` (when async) whenever any of these reference values
   * change. Useful for cascading selects.
   */
  itemsWatch?: unknown[];
  /**
   * Allow the user to create a new option by typing into a select /
   * multi-select. Pass `true` for `{ value: query, label: query }`, or a
   * function returning a custom option built from the query.
   */
  createNewEntry?: boolean | ((query: string) => {
    value: string;
    label: string;
  });
  /**
   * Width slot inside an `<AutoForm>` group. Mapped to a grid column span.
   * - `100` → full row
   * - `75`  → 3/4 row
   * - `66`  → 2/3 row
   * - `50`  → half
   * - `33`  → one third (default for plain primitives)
   * - `25`  → one quarter
   */
  width?: 100 | 75 | 66 | 50 | 33 | 25;
  /**
   * Render `null` (hide) when truthy. Equivalent to a function `$control`
   * returning `false`, but available as a static value.
   */
  hidden?: boolean;
  disabled?: boolean;
  readOnly?: boolean;
  /**
   * Render before/after the field. Both receive the resolved input.
   * Typed loosely — UI layer narrows to `ReactNode`.
   */
  top?: unknown;
  bottom?: unknown;
  /**
   * Render a managed upload control (image preview, multi, drag-drop)
   * that posts to the file API and stores the resulting file ID(s) in
   * the form. Pass `true` for defaults or an options object:
   *
   * ```ts
   * $control: { upload: { multi: true, accept: "image/*", maxSize: 5_000_000 } }
   * ```
   */
  upload?: boolean | {
    multi?: boolean;
    accept?: string;
    maxSize?: number;
    bucket?: string;
  };
  arrayProps?: {
    confirmDelete?: boolean | {
      title?: string;
      message?: string;
    };
    /** Computed label for each tab when an array uses tabs mode. */
    renderTabName?: (i: number, value: unknown) => string;
    sortable?: boolean;
    collapsible?: boolean;
    /** Force grouped (CreateForm-style) tabs even for short arrays. */
    forceTabs?: boolean;
  };
  [key: string]: unknown;
}
interface SchemaControlItem {
  value: string | number | boolean;
  label: string;
  description?: string;
  tag?: string;
}
type SchemaControlItemsFn = (query: string) => Array<string | SchemaControlItem> | Promise<Array<string | SchemaControlItem>>;
/**
 * Function form of `$control`. Receives the live form model + the current
 * field value, and returns a partial config (merged with explicit props),
 * `false` to hide, or `undefined` to leave as-is.
 */
type SchemaControlFn = (context: {
  form: FormModel<any>;
  value: unknown;
}) => Partial<SchemaControl> | false | undefined;
type SchemaControlOption = SchemaControl | SchemaControlFn;
/**
 * Resolve a raw `$control` value (object or function) into a concrete
 * partial config. Returns `null` when the field should be hidden.
 */
declare const resolveSchemaControl: (raw: unknown, context: {
  form: FormModel<any>;
  value: unknown;
}) => Partial<SchemaControl> | null;
declare module "alepha" {
  interface SchemaOptions {
    /**
     * UI metadata read by `<Control>` from `@alepha/ui`. See
     * {@link SchemaControl}.
     */
    $control?: SchemaControlOption;
  }
}
//#endregion
//#region ../../src/react/ui/services/UiPersistence.d.ts
/**
 * Binds the {@link uiAtom} to an `alepha-ui` cookie + injects an inline
 * boot script into the SSR head to prevent FOUC on first paint.
 *
 * Reading flow: on app boot the cookie is parsed and pushed into the atom
 * (via the `key` option on `$cookie`). Writing flow: every time the atom
 * mutates, the cookie is rewritten — a single `useStore(uiAtom)` call is
 * enough to persist UI preferences across reloads.
 *
 * Persists for 365 days; SameSite=lax so it travels on top-level navigation
 * but not on cross-origin requests.
 */
declare class UiPersistence {
  ui: import("alepha/server/cookies").AbstractCookiePrimitive<import("zod").ZodObject<{
    mode: import("zod").ZodEnum<{
      dark: "dark";
      light: "light";
      system: "system";
    }>;
    theme: import("zod").ZodString;
    sidebar: import("zod").ZodObject<{
      collapsed: import("zod").ZodBoolean;
    }, import("zod/v4/core").$strip>;
  }, import("zod/v4/core").$strip>>;
  head: import("alepha/react/head").HeadPrimitive;
}
//#endregion
//#region ../../src/react/ui/index.d.ts
declare module "alepha" {
  interface State {
    "alepha.react.ui": UiState;
    "alepha.react.ui.themes": UiThemeList;
  }
}
/**
 * Persisted UI state: color mode, theme palette, sidebar collapsed state.
 *
 * Backed by an `alepha-ui` cookie so preferences survive reloads and are
 * available during SSR (no flash of wrong theme).
 *
 * @module alepha.react.ui
 */
declare const AlephaReactUi: import("alepha").Service<import("alepha").Module>;
//#endregion
export { AlephaReactUi, ColorMode, ColorScheme, ResolvedColorMode, SchemaControl, SchemaControlFn, SchemaControlItem, SchemaControlItemsFn, SchemaControlOption, UiPersistence, UiState, UiTheme, UiThemeList, resolveSchemaControl, uiAtom, uiThemeListAtom, useColorMode, useSidebarState, useTheme };
//# sourceMappingURL=index.d.ts.map