addon-ui 0.9.2 → 0.10.0

package/README.md

@@ -67,12 +67,12 @@ This library now ships with dedicated documentation files for each component in
 - [IconButton](docs/IconButton.md)
 - [List](docs/List.md) (covers List and ListItem)
 - [Modal](docs/Modal.md)
-- [Odometer](docs/Odometer.md) (component + useOdometer hook)
+- [Odometer](docs/Odometer.md) (component + `useOdometer` hook)
 - [ScrollArea](docs/ScrollArea.md)
 - [Select](docs/Select.md)
 - [SvgSprite](docs/SvgSprite.md)
 - [Switch](docs/Switch.md)
-- [Tabs](docs/Tabs.md) (includes Tabs, TabsList, TabsTrigger, TabsContent)
+- [Tabs](docs/Tabs.md) (includes `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`)
 - [Tag](docs/Tag.md)
 - [TextArea](docs/TextArea.md)
 - [TextField](docs/TextField.md)
@@ -83,7 +83,7 @@ This library now ships with dedicated documentation files for each component in
 - [View](docs/View.md)
 - [ViewDrawer](docs/ViewDrawer.md)
 - [ViewModal](docs/ViewModal.md)
-- [Viewport](docs/Viewport.md) (ViewportProvider + useViewport)
+- [Viewport](docs/Viewport.md) (`ViewportProvider` + `useViewport`)
 
 Notes:
 
@@ -134,15 +134,40 @@ export default defineConfig({
     plugins: [
         ui({
             themeDir: "./theme", // Directory for theme files
-            configFileName: "ui.config", // Name of config files
-            styleFileName: "ui.style", // Name of style files
+            configName: "ui.config", // Name of config files
+            styleName: "ui.style", // Name of style files
             mergeConfig: true, // Merge configs from different directories
             mergeStyles: true, // Merge styles from different directories
+            splitChunks: true, // Enable automatic chunk splitting for components
         }),
     ],
 });
 ```
 
+### Plugin Options
+
+| Option        | Type                                               | Default       | Description                                                                                            |
+| :------------ | :------------------------------------------------- | :------------ | :----------------------------------------------------------------------------------------------------- |
+| `themeDir`    | `string`                                           | `"."`         | Directory path where plugin configuration and style files are located.                                 |
+| `configName`  | `string`                                           | `"config.ui"` | Name of the configuration file.                                                                        |
+| `styleName`   | `string`                                           | `"style.ui"`  | Name of the SCSS style file.                                                                           |
+| `mergeConfig` | `boolean`                                          | `true`        | Whether to merge configuration files from different directories.                                       |
+| `mergeStyles` | `boolean`                                          | `true`        | Whether to merge style files from different directories.                                               |
+| `splitChunks` | `boolean \| (name: string) => string \| undefined` | `true`        | Enables automatic chunk splitting. If a function is provided, it can be used to customize chunk names. |
+
+#### Customizing Chunk Names
+
+You can pass a callback function to `splitChunks` to customize the generated chunk names:
+
+```ts
+ui({
+    splitChunks: name => {
+        if (name === "button") return "ui-core-button";
+        return `ui-${name}`;
+    },
+});
+```
+
 ### Configuration Files
 
 The `addon-ui` configuration is designed to retrieve configuration from each extension separately, allowing for
@@ -271,7 +296,7 @@ extensions with the same functionality but different visual appearances.
 
 ### Global Theme Customization
 
-You can customize the theme globally by passing props to the UIProvider:
+You can customize the theme globally by passing props to the `UIProvider`:
 
 ```jsx
 import {UIProvider} from "addon-ui";
@@ -289,6 +314,8 @@ const customTheme = {
     icons: {
         // Custom icons
     },
+    // Specify the DOM element to set theme/view/browser attributes on
+    container: "#app-root",
 };
 
 function App() {
@@ -296,6 +323,17 @@ function App() {
 }
 ```
 
+### UIProvider Props
+
+| Prop         | Type                           | Default     | Description                                               |
+| :----------- | :----------------------------- | :---------- | :-------------------------------------------------------- |
+| `components` | `ComponentsProps`              | `{}`        | Component-specific configuration overrides.               |
+| `icons`      | `Icons`                        | `{}`        | Custom SVG icons registration.                            |
+| `extra`      | `ExtraProps`                   | `{}`        | App-wide extra properties.                                |
+| `storage`    | `ThemeStorageContract \| true` | `undefined` | Persistence storage for theme settings.                   |
+| `container`  | `string \| Element \| false`   | `"html"`    | Target element for attributes. Set to `false` to disable. |
+| `view`       | `string`                       | `undefined` | Custom view identifier for specific styling.              |
+
 ### Using Extra Props
 
 Extra Props is a powerful feature that allows you to extend component props with custom properties. This is particularly
@@ -438,12 +476,13 @@ function App() {
 
 ## Theming and style reuse
 
-- Global theme tokens (colors, typography, spacing, transitions) live in your ui.style.scss. Components consume them
-  through fallbacks.
-- Each component also exposes its own `--component-*` variables. See the CSS variables tables in the docs to know
-  exactly what you can override.
-- Light/dark modes: use `@import "addon-ui/theme";` and the provided `@include light { ... }` / `@include dark { ... }`
-  mixins in your theme SCSS to scope tokens per color scheme.
+- Global theme tokens (colors, typography, spacing, transitions) live in your `ui.style.scss`.
+- Each component also exposes its own `--component-*` variables. See the CSS variables tables in the docs to know exactly what you can override.
+- **Theme Mixins**: Use `@import "addon-ui/theme";` to access `@include light { ... }` and `@include dark { ... }` mixins.
+- **Universal Targeting**: These mixins are container-agnostic. They work correctly whether the `theme` attribute is on a parent element or directly on the component itself.
+- **Context-Aware**:
+    - When used at the top level, they generate global selectors: `[theme="dark"] { ... }`.
+    - When used inside a component, they generate scoped selectors: `[theme="dark"] .my-comp, .my-comp[theme="dark"] { ... }`.
 
 ## Radix UI and third-party integrations
 

package/dist-types/components/Select/Select.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { SelectProps } from "@radix-ui/react-select";
-export { SelectProps };
+export { type SelectProps };
 declare const _default: React.NamedExoticComponent<SelectProps>;
 export default _default;
 //# sourceMappingURL=Select.d.ts.map

package/dist-types/components/Select/SelectIcon.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { SelectIconProps } from "@radix-ui/react-select";
-export { SelectIconProps };
+export { type SelectIconProps };
 declare const _default: React.NamedExoticComponent<SelectIconProps & React.RefAttributes<HTMLSpanElement>>;
 export default _default;
 //# sourceMappingURL=SelectIcon.d.ts.map

package/dist-types/components/Select/SelectValue.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { SelectValueProps } from "@radix-ui/react-select";
-export { SelectValueProps };
+export { type SelectValueProps };
 declare const _default: React.NamedExoticComponent<SelectValueProps & React.RefAttributes<HTMLSpanElement>>;
 export default _default;
 //# sourceMappingURL=SelectValue.d.ts.map

package/dist-types/components/TextField/TextField.d.ts

@@ -1,5 +1,5 @@
 import React, { ComponentProps, ReactNode } from "react";
-import { TextFieldVariant, TextFieldSize, TextFieldRadius, TextFieldAccent } from "./types";
+import { TextFieldAccent, TextFieldRadius, TextFieldSize, TextFieldVariant } from "./types";
 export interface TextFieldActions {
     select(): void;
     focus(): void;
@@ -20,6 +20,7 @@ export interface TextFieldProps extends ComponentProps<"input"> {
     inputClassName?: string;
     afterClassName?: string;
     beforeClassName?: string;
+    strict?: boolean;
 }
 declare const _default: React.NamedExoticComponent<Omit<TextFieldProps, "ref"> & React.RefAttributes<TextFieldActions>>;
 export default _default;

package/dist-types/components/TextField/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalizes user-typed numeric input.
+ *
+ * - Allows partial values ("-", ".", "1e", "1e-")
+ * - Supports decimals and scientific notation
+ */
+export declare const normalizeNumberInput: (raw: string) => string;
+//# sourceMappingURL=utils.d.ts.map

package/dist-types/components/Truncate/Truncate.d.ts

@@ -1,10 +1,10 @@
 import React, { ComponentProps } from "react";
-import { HighlightProps } from "../Highlight";
 export interface TruncateProps extends ComponentProps<"span"> {
     text?: string;
     middle?: boolean;
     separator?: string;
-    highlight?: Omit<HighlightProps, "textToHighlight">;
+    contentClassname?: string;
+    render?: (text: string) => React.ReactNode;
 }
 declare const _default: React.NamedExoticComponent<Omit<TruncateProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
 export default _default;

package/dist-types/components/Truncate/utils.d.ts

@@ -0,0 +1,2 @@
+export declare const calculateMiddleTruncate: (text: string, maxWidth: number, font: string, letterSpacing: string, separator: string) => string;
+//# sourceMappingURL=utils.d.ts.map

package/dist-types/plugin/index.d.ts

@@ -1,9 +1,35 @@
 export interface PluginOptions {
+    /**
+     * Directory path where plugin configuration and style files are located, relative to the project root.
+     * @default "."
+     */
     themeDir?: string;
-    configFileName?: string;
-    styleFileName?: string;
+    /**
+     * Name of the configuration file.
+     * @default "config.ui"
+     */
+    configName?: string;
+    /**
+     * Name of the style file.
+     * @default "style.ui"
+     */
+    styleName?: string;
+    /**
+     * Whether to merge configuration files from different app directories.
+     * @default true
+     */
     mergeConfig?: boolean;
+    /**
+     * Whether to merge style files from different app directories.
+     * @default true
+     */
     mergeStyles?: boolean;
+    /**
+     * Configuration for splitting chunks.
+     * Can be a boolean to enable/disable or a callback to customize chunk names.
+     * @default true
+     */
+    splitChunks?: boolean | ((name: string) => string | undefined);
 }
 declare const _default: import("adnbn").PluginDefinition<[options?: PluginOptions | undefined]>;
 export default _default;

package/dist-types/providers/theme/ThemeProvider.d.ts

@@ -2,7 +2,95 @@ import { FC, PropsWithChildren } from "react";
 import { ThemeStorageContract } from "../../types/theme";
 import { Config } from "../../types/config";
 export interface ThemeProviderProps extends Pick<Config, "components"> {
+    /**
+     * Theme persistence storage configuration.
+     *
+     * @remarks
+     * - When `undefined`, theme changes are stored only in component state (memory) and reset on page reload.
+     * - When `true`, uses the default `ThemeStorage` implementation (typically localStorage).
+     * - When a custom `ThemeStorageContract` object is provided, uses that implementation for theme persistence.
+     *
+     * The storage is used to save, retrieve, and watch for theme changes across sessions or tabs.
+     *
+     * @default undefined
+     *
+     * @example
+     * ```tsx
+     * // No persistence (memory only)
+     * <ThemeProvider>
+     *   <App />
+     * </ThemeProvider>
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Use default storage (localStorage)
+     * <ThemeProvider storage={true}>
+     *   <App />
+     * </ThemeProvider>
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Use custom storage implementation
+     * const customStorage: ThemeStorageContract = {
+     *   get: async () => { ... },
+     *   change: async (theme) => { ... },
+     *   toggle: async () => { ... },
+     *   watch: (callback) => { ... }
+     * };
+     *
+     * <ThemeProvider storage={customStorage}>
+     *   <App />
+     * </ThemeProvider>
+     * ```
+     */
     storage?: ThemeStorageContract | true;
+    /**
+     * The DOM element where the provider will set attributes "browser"
+     *
+     * @remarks
+     * - When a string is provided, it's used as a CSS selector to find the element via `document.querySelector`.
+     * - When an Element is provided, attributes are set directly on that element.
+     * - When `false`, no element attributes are set.
+     *
+     * Attributes are automatically cleaned up when the component unmounts.
+     *
+     * @default "html"
+     *
+     * @example
+     * ```tsx
+     * // Use default html element
+     * <ThemeProviderProps>
+     *   <App />
+     * </ThemeProviderProps>
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Use custom selector
+     * <ThemeProviderProps container="#app-root">
+     *   <App />
+     * </ThemeProviderProps>
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Use direct element reference
+     * <ThemeProviderProps container={document.body}>
+     *   <App />
+     * </ThemeProviderProps>
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Disable container attributes
+     * <ThemeProviderProps container={false}>
+     *   <App />
+     * </ThemeProviderProps>
+     * ```
+     */
+    container?: string | Element | false;
 }
 declare const ThemeProvider: FC<PropsWithChildren<ThemeProviderProps>>;
 export default ThemeProvider;

package/dist-types/providers/ui/UIProvider.d.ts

@@ -4,7 +4,28 @@ import { Config } from "../../types/config";
 import "./styles/default.scss";
 import "./styles/reset.scss";
 import "addon-ui-style.scss";
-export interface UIProviderProps extends Partial<Config>, Pick<ThemeProviderProps, "storage"> {
+export interface UIProviderProps extends Partial<Config>, Pick<ThemeProviderProps, "storage" | "container"> {
+    /**
+     * A custom view identifier that allows developers to specify a unique name for styling customization.
+     * This value is set as a "view" attribute on the container element and can be targeted through SCSS mixins
+     * to apply view-specific styles and behavior.
+     *
+     * @example
+     * ```tsx
+     * <UIProvider view="dashboard">
+     *   <App />
+     * </UIProvider>
+     * ```
+     *
+     * @example
+     * ```scss
+     * @include view("dashboard") {
+     *   .some-class {
+     *     // Custom styles for dashboard view
+     *   }
+     * }
+     * ```
+     */
     view?: string;
 }
 declare const UIProvider: FC<PropsWithChildren<UIProviderProps>>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "addon-ui",
   "type": "module",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "A comprehensive React UI component library designed exclusively for the AddonBone browser extension framework with customizable theming and consistent design patterns",
   "keywords": [
     "react",
@@ -106,7 +106,7 @@
     "@types/node": "^22.13.10",
     "@types/react": "^19.0.10",
     "@types/react-dom": "^19.0.4",
-    "adnbn": "^0.5.4",
+    "adnbn": "^0.5.7",
     "depcheck": "^1.4.7",
     "eslint": "^9.21.0",
     "eslint-plugin-react-hooks": "^5.1.0",
@@ -141,12 +141,7 @@
   },
   "overrides": {
     "flat-cache": "^6.1.18",
-    "html-rspack-tags-plugin": {
-      "glob": "^10.4.5"
-    },
-    "test-exclude": {
-      "glob": "^10.4.5"
-    }
+    "glob": "^13.0.0"
   },
   "eslintConfig": {
     "extends": [

package/src/components/Select/Select.tsx

@@ -6,7 +6,7 @@ import {Root, SelectProps} from "@radix-ui/react-select";
 
 import {useComponentProps} from "../../providers";
 
-export {SelectProps};
+export {type SelectProps};
 
 const Select: FC<SelectProps> = props => {
     const {...other} = {...useComponentProps("select"), ...props};

package/src/components/Select/SelectIcon.tsx

@@ -8,7 +8,7 @@ import {useComponentProps} from "../../providers";
 
 import styles from "./select.module.scss";
 
-export {SelectIconProps};
+export {type SelectIconProps};
 
 const SelectIcon: ForwardRefRenderFunction<HTMLSpanElement, SelectIconProps> = (props, ref) => {
     const {className, ...other} = {...useComponentProps("selectIcon"), ...props};

package/src/components/Select/SelectValue.tsx

@@ -8,7 +8,7 @@ import {useComponentProps} from "../../providers";
 
 import styles from "./select.module.scss";
 
-export {SelectValueProps};
+export {type SelectValueProps};
 
 const SelectValue: ForwardRefRenderFunction<HTMLSpanElement, SelectValueProps> = (props, ref) => {
     const {className, ...other} = {...useComponentProps("selectValue"), ...props};

package/src/components/TextField/TextField.tsx

@@ -1,12 +1,14 @@
 import React, {
-    ChangeEventHandler,
+    ChangeEvent,
     ComponentProps,
     forwardRef,
+    KeyboardEvent,
     memo,
     ReactNode,
     useCallback,
     useEffect,
     useImperativeHandle,
+    useMemo,
     useRef,
     useState,
 } from "react";
@@ -16,7 +18,8 @@ import classnames from "classnames";
 import {cloneOrCreateElement} from "../../utils";
 import {useComponentProps} from "../../providers";
 
-import {TextFieldVariant, TextFieldSize, TextFieldRadius, TextFieldAccent} from "./types";
+import {normalizeNumberInput} from "./utils";
+import {TextFieldAccent, TextFieldRadius, TextFieldSize, TextFieldVariant} from "./types";
 
 import styles from "./text-field.module.scss";
 
@@ -44,6 +47,7 @@ export interface TextFieldProps extends ComponentProps<"input"> {
     inputClassName?: string;
     afterClassName?: string;
     beforeClassName?: string;
+    strict?: boolean;
 }
 
 const TextField = forwardRef<TextFieldActions, TextFieldProps>((props, ref) => {
@@ -55,7 +59,8 @@ const TextField = forwardRef<TextFieldActions, TextFieldProps>((props, ref) => {
         label,
         fullWidth,
         type = "text",
-        value: propValue = "",
+        strict,
+        value: propValue,
         defaultValue,
         before,
         after,
@@ -64,12 +69,20 @@ const TextField = forwardRef<TextFieldActions, TextFieldProps>((props, ref) => {
         afterClassName,
         beforeClassName,
         onChange,
+        onKeyDown,
         ...other
     } = {...useComponentProps("textField"), ...props};
 
-    const [value, setValue] = useState<string | number | undefined>(defaultValue || propValue);
+    const [value, setValue] = useState<string>(() => {
+        if (propValue != null) return String(propValue);
+        if (defaultValue != null) return String(defaultValue);
+        return "";
+    });
+
     const inputRef = useRef<HTMLInputElement | null>(null);
 
+    const strictNumberType = useMemo(() => type === "number" && !!strict, [type, strict]);
+
     useImperativeHandle(
         ref,
         () => ({
@@ -83,22 +96,61 @@ const TextField = forwardRef<TextFieldActions, TextFieldProps>((props, ref) => {
                 return inputRef.current?.value;
             },
             setValue(value: string | number | undefined) {
-                setValue(value);
+                setValue(value == null ? "" : String(value));
             },
         }),
         []
     );
 
-    const handleChange = useCallback<ChangeEventHandler<HTMLInputElement>>(
-        event => {
-            setValue(event.currentTarget.value);
-            onChange?.(event);
+    const handleChange = useCallback(
+        (event: ChangeEvent<HTMLInputElement>) => {
+            let newValue = event.currentTarget.value ?? "";
+
+            if (strictNumberType) {
+                newValue = normalizeNumberInput(newValue);
+            }
+
+            setValue(newValue);
+
+            onChange?.({
+                ...event,
+                currentTarget: {
+                    ...event.currentTarget,
+                    value: newValue,
+                },
+            });
+        },
+        [onChange, strictNumberType]
+    );
+
+    const handleKeyDown = useCallback(
+        (event: KeyboardEvent<HTMLInputElement>) => {
+            if (strictNumberType && event.key.length === 1) {
+                // Only handle single-character printable keys here
+                // composition and paste handled in onChange
+                const {selectionStart, selectionEnd, value} = event.currentTarget;
+
+                const start = selectionStart ?? value.length;
+                const end = selectionEnd ?? start;
+
+                const next = value.slice(0, start) + event.key + value.slice(end);
+                const normalized = normalizeNumberInput(next);
+
+                if (normalized !== next) {
+                    event.preventDefault();
+                }
+            }
+
+            onKeyDown?.(event);
         },
-        [onChange]
+        [onKeyDown, strictNumberType]
     );
 
     useEffect(() => {
-        setValue(propValue);
+        const text = propValue == null ? "" : String(propValue);
+
+        setValue(strictNumberType ? normalizeNumberInput(text) : text);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [propValue]);
 
     return (
@@ -124,12 +176,13 @@ const TextField = forwardRef<TextFieldActions, TextFieldProps>((props, ref) => {
             <input
                 {...other}
                 ref={inputRef}
-                type={type}
+                type={strictNumberType ? "text" : type}
+                inputMode={strictNumberType ? "decimal" : other.inputMode}
                 value={value}
-                defaultValue={defaultValue}
                 aria-label={label}
                 className={classnames(styles["text-field__input"], inputClassName)}
                 onChange={handleChange}
+                onKeyDown={handleKeyDown}
             />
             {cloneOrCreateElement(after, {className: classnames(styles["text-field__after"], afterClassName)}, "span")}
         </div>

package/src/components/TextField/text-field.module.scss

@@ -10,7 +10,7 @@ $root: text-field;
   font-weight: var(--text-field-font-weight, 400);
   font-size: var(--text-field-font-size, 14px);
   letter-spacing: var(--text-field-letter-spacing, 0.5px);
-  line-height: var(--text-field-line-height, var(--line-height, 1 rem));
+  line-height: var(--text-field-line-height, var(--line-height, 1rem));
   padding: var(--text-field-padding, 8px 12px);
   border-radius: var(--text-field-border-radius, 8px);
   transition:
@@ -43,10 +43,12 @@ $root: text-field;
     outline: none;
     background: transparent;
     transition: color var(--text-field-speed-color, var(--speed-color));
+    appearance: textfield;
 
     &:focus {
       outline: none;
     }
+
     &:disabled {
       cursor: not-allowed;
     }

package/src/components/TextField/utils.ts

@@ -0,0 +1,56 @@
+/**
+ * Normalizes user-typed numeric input.
+ *
+ * - Allows partial values ("-", ".", "1e", "1e-")
+ * - Supports decimals and scientific notation
+ */
+export const normalizeNumberInput = (raw: string): string => {
+    if (!raw) return "";
+
+    const filtered = raw.replace(/[^0-9eE+\-.]/g, "");
+
+    let result = "";
+    let hasExponent = false;
+    let hasDot = false;
+    let isInExponent = false;
+    let canUseSign = true;
+
+    for (let i = 0; i < filtered.length; i++) {
+        const ch = filtered[i];
+
+        if (ch >= "0" && ch <= "9") {
+            result += ch;
+            canUseSign = false;
+            continue;
+        }
+
+        if (ch === ".") {
+            if (!isInExponent && !hasDot) {
+                result += ch;
+                hasDot = true;
+            }
+            continue;
+        }
+
+        if (ch === "e" || ch === "E") {
+            if (!hasExponent) {
+                if (/\d/.test(result)) {
+                    result += ch;
+                    hasExponent = true;
+                    isInExponent = true;
+                    canUseSign = true;
+                }
+            }
+            continue;
+        }
+
+        if (ch === "+" || ch === "-") {
+            if (canUseSign) {
+                result += ch;
+                canUseSign = false;
+            }
+        }
+    }
+
+    return result;
+};