@ufoui/core 0.0.5 → 0.0.12

package/internal/controlGrid/controlGrid.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode } from 'react';
+import { ElementTextPlacement } from '../../utils';
+/**
+ * Props for the ControlGrid component.
+ *
+ * Layout container for form control, label and description.
+ *
+ * @category Slot
+ */
+export interface ControlGridProps {
+    /** Main control element such as checkbox, switch or slider. */
+    control?: ReactNode;
+    /** Label displayed next to the control. */
+    label?: ReactNode;
+    /** Supporting text such as description or error message. */
+    description?: ReactNode;
+    /** Placement of label relative to the control. */
+    textPlacement: ElementTextPlacement;
+    /** Additional root class name. */
+    className?: string;
+    /** Spans description across all grid columns. */
+    spanDesc?: boolean;
+}
+/**
+ * Layout helper that arranges control, label and description.
+ *
+ * @function
+ * @param props Component properties.
+ *
+ * @category Slot
+ */
+export declare const ControlGrid: import('react').ForwardRefExoticComponent<ControlGridProps & import('react').RefAttributes<HTMLDivElement>>;

package/internal/controlLabel/controlLabel.d.ts

@@ -0,0 +1,31 @@
+import { ElementType, ReactNode, RefObject } from 'react';
+import { ElementFont } from '../../utils';
+export interface ControlLabelProps {
+    /** Label content. */
+    label?: ReactNode;
+    /** ID of the associated control element. Used when tag is 'label'. */
+    htmlFor?: string;
+    /** DOM id applied to the label element. */
+    id?: string;
+    /** Reference to a control element that should receive focus when the label is clicked. */
+    focusRef?: RefObject<HTMLElement>;
+    /** Displays a required indicator next to the label. */
+    required?: boolean;
+    /** Font applied to the label text. */
+    font?: ElementFont;
+    /** HTML tag used to render the label element. Default: 'label'. */
+    tag?: ElementType;
+}
+/**
+ * Renders a label for form controls.
+ *
+ * Supports both native label behaviour and ARIA labeling for custom controls.
+ * When tag is 'label', htmlFor associates the label with a form element.
+ * When focusRef is provided, clicking the label focuses the referenced control.
+ *
+ * @function
+ * @param props Component properties.
+ *
+ * @category Slot
+ */
+export declare const ControlLabel: ({ label, htmlFor, id, required, font, focusRef, tag: Tag, }: ControlLabelProps) => import("react/jsx-runtime").JSX.Element | null;

package/internal/description/description.d.ts

@@ -0,0 +1,18 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export interface DescriptionProps extends HTMLAttributes<HTMLElement> {
+    /** Supporting description text. */
+    description?: ReactNode;
+    /** Error message text. Overrides description when present. */
+    error?: ReactNode;
+}
+/**
+ * Renders supporting text such as description or error message.
+ *
+ * Error message takes precedence over description.
+ *
+ * @function
+ * @param props Component properties.
+ *
+ * @category Slot
+ */
+export declare const Description: ({ description, error, ...rest }: DescriptionProps) => import("react/jsx-runtime").JSX.Element | null;

package/internal/index.d.ts

@@ -0,0 +1,6 @@
+export * from './inlineTooltip';
+export * from './slots/slot';
+export * from './stateLayer/stateLayer';
+export * from './controlGrid/controlGrid';
+export * from './controlLabel/controlLabel';
+export * from './description/description';

package/internal/inlineTooltip/index.d.ts

@@ -0,0 +1 @@
+export * from './inlineTooltipManager';

package/internal/inlineTooltip/inlineTooltipManager.d.ts

@@ -6,7 +6,7 @@ interface InlineTooltipManagerProps extends HTMLProps<HTMLSpanElement> {
     align: ElementAlign;
 }
 export declare const InlineTooltipManager: {
-    ({ tooltip, align, triggerRef, }: InlineTooltipManagerProps): React.ReactPortal;
+    ({ tooltip, align, triggerRef }: InlineTooltipManagerProps): React.ReactPortal;
     displayName: string;
 };
 export {};

package/internal/slots/slot.d.ts

@@ -0,0 +1,44 @@
+import { ReactNode } from 'react';
+/**
+ * Props for the Slot component.
+ *
+ * @category Slot
+ */
+interface SlotProps {
+    /** Element rendered before the content. */
+    start?: ReactNode;
+    /** Element rendered after the content. */
+    end?: ReactNode;
+    /** Main slot content. */
+    content: ReactNode;
+    /** Root class name. */
+    className?: string;
+}
+/**
+ * Layout helper that renders start, content, and end regions.
+ *
+ * @function
+ * @param props Component properties.
+ *
+ * @category Slot
+ */
+export declare const Slot: ({ start, end, content, className }: SlotProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Slot wrapper for leading content.
+ *
+ * @function
+ * @param props Component properties.
+ *
+ * @category Slot
+ */
+export declare const Leading: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Slot wrapper for trailing content.
+ *
+ * @function
+ * @param props Component properties.
+ *
+ * @category Slot
+ */
+export declare const Trailing: (props: SlotProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/internal/stateLayer/stateLayer.d.ts

@@ -0,0 +1,33 @@
+import { SurfaceColor } from '../../utils';
+/**
+ * Props for StateLayer component.
+ *
+ * @category Internal components
+ */
+export interface StateLayerProps {
+    /** Background color token. */
+    color?: SurfaceColor;
+    /** Additional class name. */
+    className?: string;
+}
+/**
+ * StateLayer component.
+ *
+ * Renders a visual state layer used for hover, focus, pressed and selected effects.
+ *
+ * @param color Background color token.
+ * @param className Additional class name.
+ *
+ * @function
+ *
+ * @example
+ * <Component>
+ *   <StateLayer />
+ * </Component>
+ *
+ * @example
+ * <StateLayer color="primary" />
+ *
+ * @category Internal components
+ */
+export declare const StateLayer: ({ color, className }: StateLayerProps) => import("react/jsx-runtime").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ufoui/core",
-  "version": "0.0.5",
+  "version": "0.0.12",
   "description": "Lightweight Material Design 3 UI components for React",
   "type": "module",
   "main": "./index.mjs",
@@ -14,10 +14,19 @@
   },
   "keywords": [
     "react",
+    "react-components",
     "components",
+    "material-design",
+    "material-design-3",
+    "md3",
+    "material-you",
     "ui",
+    "ui-kit",
+    "component-library",
+    "typescript",
+    "esm",
     "ufoui",
-    "core"
+    "ufo-ui"
   ],
   "peerDependencies": {
     "react": "^18.0.0",
@@ -35,4 +44,4 @@
     "./style.css": "./index.css",
     "./style": "./index.css"
   }
-}
+}

package/utils/color.d.ts

@@ -80,7 +80,6 @@ export declare const getSemanticColorClasses: (color: SemanticColor) => {
  * for all semantic, extended, and surface tokens defined in {@link ThemeColor}.
  * Enables consistent inverse lookups for text/background pairings.
  *
- * Commonly used by {@link getSurfaceColorClasses}.
  *
  * @category Color
  */
@@ -148,104 +147,12 @@ export declare const inverseColorMap: {
     readonly onSuccessContainer: "successContainer";
     readonly onErrorContainer: "errorContainer";
 };
-/**
- * Returns utility class names (`uui-*`) for a given surface color and its mapped “on” color.
- *
- * @remarks
- * Uses the {@link inverseColorMap} to find the related “on” color
- * (e.g. `'surfaceContainer'` → `'onSurface'`).
- * Produces `text`, `border`, and `background` variants for both.
- * All names are kebab-cased (e.g. `'surfaceContainerHigh'` → `'surface-container-high'`).
- *
- * @param color - Surface color key (e.g. `'surfaceContainerHigh'`).
- * @returns Object with `uui-text-*`, `uui-border-*`, and `uui-bg-*` class names for base and on-color.
- *
- * @example
- * ```ts
- * getSurfaceColorClasses('surfaceContainer');
- * // → { textColor: 'uui-text-surface-container', textOnColor: 'uui-text-on-surface', ... }
- * ```
- * @category Color
- */
-export declare const getSurfaceColorClasses: (color: SurfaceColor) => {
-    readonly textColor: `uui-text-${string}`;
-    readonly textOnColor: `uui-text-${string}`;
-    readonly borderColor: `uui-border-${string}`;
-    readonly borderOnColor: `uui-border-${string}`;
-    readonly bgColor: `uui-bg-${string}`;
-    readonly bgOnColor: `uui-bg-${string}`;
-};
-/**
- * Returns utility class names (`uui-*`) for any theme color token.
- *
- * @remarks
- * Generates `text`, `border`, and `background` class names based on the provided
- * {@link ThemeColor}. If the color key is invalid, `'primary'` is used as fallback.
- *
- * @param color - Theme color token (e.g. `'primary'`, `'surfaceContainerHigh'`, `'error'`).
- * @returns An object with `uui-text-*`, `uui-border-*`, and `uui-bg-*` class names.
- *
- * @example
- * ```ts
- * getColorClasses('error');
- * // → { textColor: 'uui-text-error', borderColor: 'uui-border-error', bgColor: 'uui-bg-error' }
- * ```
- * @category Color
- */
-export declare const getColorClasses: (color: ThemeColor) => {
-    readonly textColor: `uui-text-${string}`;
-    readonly borderColor: `uui-border-${string}`;
-    readonly bgColor: `uui-bg-${string}`;
-};
 /**
  * Represents the available border color options.
  *
  * @category Color
  */
 export type BorderColor = SurfaceColor;
-/**
- * Returns the appropriate border color class for a given configuration.
- *
- * @remarks
- * Typical border colors are `'outline'` and `'outlineVariant'`, matching MD3 tokens.
- * @param borderColor - Border color keyword or surface color token.
- * @returns The resolved border color class (e.g. `'uui-border-surface-container-high'`).
- *
- * @example
- * ```ts
- * getBorderColorClass('surfaceContainer'); // → 'uui-border-surface-container'
- * ```
- * @category Color
- */
-export declare function getBorderColorClass(borderColor: BorderColor): `uui-border-${string}`;
-/**
- * Returns all CSS variable references for a **semantic color**.
- *
- * @remarks
- * Generates `var(--uui-color-*)` tokens only for semantic colors
- * defined in {@link SemanticColor} (e.g. `primary`, `error`, `success`).
- * Useful for dynamic component theming and inline styles.
- *
- * @param color - Semantic color key (e.g. `'primary'`, `'error'`, `'info'`).
- * @returns Object containing `var(--uui-color-...)` references for all variants.
- *
- * @example
- * ```ts
- * const vars = getSemanticColorVar('primary');
- * // → "var(--uui-color-primary)", "var(--uui-color-on-primary)"
- * ```
- * @category Color
- */
-export declare const getSemanticColorVar: (color: SemanticColor) => {
-    color: string;
-    onColor: string;
-    container: string;
-    onContainer: string;
-    fixed: string;
-    fixedDim: string;
-    onFixed: string;
-    onFixedVariant: string;
-};
 /**
  * Returns basic CSS variable references for a **surface color**.
  *
@@ -312,14 +219,5 @@ export declare const hexToRgb: (colorValue: string) => string;
  * @category Color
  */
 export declare function getTintOverlayColor(elevation: number, tintColor: string): string;
-/**
- * Returns a set of predefined utility class names for fixed theme colors.
- *
- * Each entry maps text, border, outline, and background variants like:
- * `textSurface`, `bgOnSurface`, `borderOutlineVariant`, etc.
- *
- * @returns Object with fixed color class mappings.
- */
-export declare const getFixedColorClasses: () => Record<string, string>;
 export declare function capitalize(s: string): string;
 export declare function getBorderColor(borderColor?: BorderColor): BorderColor;

package/utils/getWrapperStyle.d.ts

@@ -0,0 +1,53 @@
+import { CSSProperties } from 'react';
+/**
+ * Props for wrapper-level behavior.
+ *
+ * Applies outer layout such as margin, positioning and stacking.
+ * Does not affect internal layout or content.
+ *
+ * @category Utils
+ */
+export type WrapperProps = {
+    /** Margin on all sides. */
+    m?: number | string;
+    /** Horizontal margin (left + right). */
+    mx?: number | string;
+    /** Vertical margin (top + bottom). */
+    my?: number | string;
+    /** Margin top. */
+    mt?: number | string;
+    /** Margin bottom. */
+    mb?: number | string;
+    /** Margin left. */
+    ml?: number | string;
+    /** Margin right. */
+    mr?: number | string;
+    /** Top offset. */
+    top?: number | string;
+    /** Right offset. */
+    right?: number | string;
+    /** Bottom offset. */
+    bottom?: number | string;
+    /** Left offset. */
+    left?: number | string;
+    /** Stacking order. */
+    zIndex?: number;
+    /** CSS position value. */
+    position?: CSSProperties['position'];
+};
+/**
+ * Resolves wrapper props into style and remaining props.
+ *
+ * Margin shorthands priority:
+ * mt/ml/... overrides mx/my, which overrides m.
+ *
+ * @function
+ * @param props Wrapper configuration.
+ * @returns Object containing wrapperStyle and otherProps.
+ *
+ * @category Utils
+ */
+export declare function getWrapperStyle(props: WrapperProps): {
+    wrapperStyle: CSSProperties;
+    otherProps: {};
+};

package/utils/index.d.ts

@@ -7,3 +7,4 @@ export * from './generateSchemes';
 export * from './toasts';
 export * from './uniqueID';
 export * from './controlStyle';
+export * from './getWrapperStyle';

package/utils/toasts/ensureViewport.d.ts

@@ -1,2 +1,7 @@
-export declare const TOAST_VIEWPORT_ID = "uui-toast-viewport-root";
+/**
+ * Ensures that a global toast viewport exists.
+ *
+ * If the user already rendered ToastViewport manually,
+ * no additional viewport is created.
+ */
 export declare function ensureViewport(): void;

package/utils/toasts/toast.d.ts

@@ -1,29 +1,85 @@
 import { ReactNode } from 'react';
 import { SurfaceColor } from '../index';
+/**
+ * Status variant applied to a toast.
+ *
+ * @category Toast
+ */
 export type ToastStatus = 'success' | 'error' | 'warning' | 'info';
+/**
+ * Options used to create or update a toast.
+ *
+ * @category Toast
+ */
 export interface ToastOptions {
-    id?: string;
-    title?: string;
-    description?: string;
+    /** Action element rendered inside the toast. */
+    action?: ReactNode | ((id: string) => ReactNode);
+    /** Surface color token overriding background and text colors. */
     color?: SurfaceColor;
-    status?: ToastStatus;
+    /** Full custom content replacing default layout. */
+    content?: ReactNode;
+    /** Supporting message text. */
+    description?: string;
+    /** Leading visual element such as an icon. */
     icon?: ReactNode;
-    action?: ReactNode | ((id: string) => ReactNode);
-    duration?: number;
+    /** Optional identifier. Generated automatically if not provided. */
+    id?: string;
+    /** Priority toasts appear before normal queued toasts. */
+    priority?: boolean;
+    /** Status variant applied as CSS modifier class. */
+    status?: ToastStatus;
+    /** Time in milliseconds before the toast is automatically dismissed. */
+    timeout?: number;
+    /** Primary heading text. */
+    title?: string;
 }
+/**
+ * Message descriptor used by promise helper.
+ *
+ * @category Toast
+ */
+type ToastPromiseMessage<T> = string | ToastOptions | ((v: T) => string | ToastOptions);
+/**
+ * Creates and displays a toast.
+ *
+ * Accepts either a message string or a ToastOptions object.
+ *
+ * @function
+ */
 declare function show(input: string | ToastOptions): string;
+/**
+ * Toast API used to create, update and manage notifications.
+ *
+ * @category Toast
+ */
 export declare const toast: typeof show & {
-    update: (id: string, partial: Partial<ToastOptions>) => void;
+    /** Updates an existing toast. */
+    update: (id: string, partial: import('./toastStore').ToastUpdate) => void;
+    /** Removes a toast by id. */
     dismiss: (id: string) => void;
+    /** Removes all toasts. */
     clear: () => void;
+    /** Creates a success toast. */
     success: (description: string, o?: ToastOptions) => string;
+    /** Creates an error toast. */
     error: (description: string, o?: ToastOptions) => string;
+    /** Creates an informational toast. */
     info: (description: string, o?: ToastOptions) => string;
+    /** Creates a warning toast. */
     warning: (description: string, o?: ToastOptions) => string;
+    /**
+     * Displays toast lifecycle bound to a promise.
+     *
+     * Promise toasts use priority so the user immediately
+     * sees feedback for the triggered action.
+     *
+     * @category Toast
+     * @function
+     */
     promise<T>(p: Promise<T>, m: {
-        loading: string;
-        success: string | ((v: T) => string);
-        error: string | ((e: unknown) => string);
+        loading: ToastPromiseMessage<void>;
+        success: ToastPromiseMessage<T>;
+        error: ToastPromiseMessage<unknown>;
     }): Promise<T>;
 };
 export {};

package/utils/toasts/toastStore.d.ts

@@ -1,11 +1,65 @@
 import { ToastOptions } from './toast';
+/**
+ * Internal toast state stored in the toast store.
+ *
+ * @category Toast
+ */
 export type ToastState = Required<Pick<ToastOptions, 'id'>> & Omit<ToastOptions, 'id'>;
+/**
+ * Partial update object used when modifying a toast.
+ *
+ * @category Toast
+ */
+export type ToastUpdate = Partial<Omit<ToastOptions, 'id'>>;
+/**
+ * Subscriber function receiving current toast list.
+ *
+ * @category Toast
+ */
 export type ToastStoreSubscriber = (toasts: ToastState[]) => void;
+/**
+ * Internal store managing toast lifecycle and subscriptions.
+ *
+ * @category Toast
+ */
 export declare const toastStore: {
+    /**
+     * Subscribes to toast state updates.
+     *
+     * @function
+     */
     subscribe(subscriber: ToastStoreSubscriber): () => void;
+    /**
+     * Adds a new toast to the store.
+     *
+     * Priority toasts are inserted at the beginning
+     * so they appear before normal queued toasts.
+     *
+     * @function
+     */
     add(toast: ToastState): void;
-    update(id: string, partial: Partial<ToastOptions>): void;
+    /**
+     * Updates an existing toast.
+     *
+     * @function
+     */
+    update(id: string, partial: ToastUpdate): void;
+    /**
+     * Removes a toast from the store.
+     *
+     * @function
+     */
     remove(id: string): void;
+    /**
+     * Removes all toasts.
+     *
+     * @function
+     */
     clear(): void;
+    /**
+     * Returns current toast list snapshot.
+     *
+     * @function
+     */
     getState(): ToastState[];
 };