moduix 0.7.0 → 0.8.0

package/README.md

@@ -1,18 +1,53 @@
+![moduix banner](https://raw.githubusercontent.com/Blinks44/moduix/main/apps/docs/public/banner.png)
+
+[![npm](https://img.shields.io/npm/v/moduix?logo=npm&label=npm)](https://www.npmjs.com/package/moduix)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Turborepo](https://img.shields.io/badge/Monorepo-Turborepo-EF4444)](https://turbo.build/)
+
 # moduix
 
-Ready-made React components for product interfaces. The library is built on top of Base UI primitives and follows a composition-first API strongly inspired by shadcn/ui: you assemble small named parts, keep behavior accessible, and customize styles through props, `className`, and CSS variables. Styles are written in native CSS with CSS Modules, so the package ships framework-agnostic component CSS without requiring a utility CSS runtime.
+Composable React components for product interfaces, built on top of
+[Base UI](https://base-ui.com/) primitives.
+
+moduix gives you ready-made components with accessible behavior, native CSS styles, and a
+composition-first API. It is inspired by the clarity of
+[shadcn/ui](https://ui.shadcn.com/), and it is trying to combine two useful workflows: install
+components as a regular npm package when that fits your project, or copy component source when
+you need direct ownership.
+
+## Why It Exists
+
+moduix started as an internal tool for shared product UI. We needed a component library that
+was practical enough for real application screens, predictable enough to use across teams, and
+small enough to stay easy to understand.
+
+The library is now public because it may be useful outside of the original company context. If
+it helps another team build consistent interfaces faster, that is already a good outcome.
 
-## Website
+## Principles
 
-The live documentation is temporarily available at https://moduix.blinks44.workers.dev/.
+- **Base UI underneath.** Components are built on accessible Base UI primitives instead of
+  reimplementing low-level interaction behavior.
+- **Small dependency surface.** Base UI is the only external UI primitive layer. The package
+  keeps the runtime stack intentionally small and does not bring a styling framework with it.
+- **Two installation paths.** Use moduix as an npm package, or copy component source into your
+  project when direct ownership is more important than package-managed updates.
+- **Composable API.** Components are exposed as named parts, so complex UI can be assembled
+  without hiding important structure.
+- **Native CSS.** Styles are distributed as CSS, use CSS custom properties, and are designed to
+  work with your existing styling approach.
+- **Not a shadcn/ui competitor.** shadcn/ui is a major inspiration for the developer experience.
+  moduix explores whether package-managed components and copy-owned components can coexist in
+  one library.
 
-## Install
+## Installation
 
 ```bash
 npm install moduix @base-ui/react
 ```
 
-`react`, `react-dom`, and `@base-ui/react` are peer dependencies. They stay in your application bundle, so the library does not ship duplicate React or Base UI runtimes.
+`react`, `react-dom`, and `@base-ui/react` are peer dependencies. They stay in your application
+bundle, so moduix does not ship duplicate React or Base UI runtimes.
 
 ## Usage
 
@@ -22,7 +57,7 @@ Import the library styles once in your application entry point:
 import 'moduix/style.css';
 ```
 
-Then import the components you need:
+Then import and compose the components you need:
 
 ```tsx
 import { Button, Dialog, DialogContent, DialogTitle, DialogTrigger } from 'moduix';
@@ -39,11 +74,13 @@ export function Example() {
 }
 ```
 
-The CSS file includes component styles and design tokens. It does not include global reset or application-level base styles, so those stay under the consuming project's control. If your bundler supports CSS imports from JavaScript, styles are also referenced by the library entry, but explicit `moduix/style.css` import is the most predictable setup for apps, SSR, and tests.
+The distributed stylesheet includes component styles and design tokens. It does not force a
+global application theme or utility CSS runtime.
 
 ## Styling
 
-Components expose stable `data-slot` attributes and accept `className` where customization is expected. Theme values are regular CSS custom properties:
+Components accept `className` where customization is expected and expose stable `data-slot`
+attributes for targeted styling. Theme values are regular CSS custom properties:
 
 ```css
 :root {
@@ -52,17 +89,37 @@ Components expose stable `data-slot` attributes and accept `className` where cus
 }
 ```
 
-The distributed stylesheet uses CSS cascade layers:
+Library CSS is organized with cascade layers:
 
 ```css
 @layer ui.reset, ui.tokens, ui.components;
 ```
 
-This keeps library styles predictable while still letting application styles override tokens or component classes.
+This keeps defaults predictable while still letting application styles override tokens,
+classes, or component-level variables.
+
+## What Is Included
+
+The package exports composed components for common product UI needs, including Accordion,
+AlertDialog, Autocomplete, Avatar, Button, Checkbox, Dialog, Drawer, Field, Form, Input,
+Menu, NavigationMenu, Popover, Select, Tabs, Toast, Tooltip, and supporting primitives.
+
+## Documentation
+
+- Documentation: https://moduix.blinks44.workers.dev/
+- npm package: https://www.npmjs.com/package/moduix
+- UI package README: `packages/ui/README.md`
+- Docs app README: `apps/docs/README.md`
+
+## Repository Quick Start
 
-## What is included
+From the monorepo root:
 
-The package exports composed components for common UI needs: Accordion, AlertDialog, Autocomplete, Avatar, Button, Checkbox, Dialog, Drawer, Field, Form, Input, Menu, NavigationMenu, Popover, Select, Tabs, Toast, Tooltip, and more. It also exports small shared primitives such as icons and close buttons.
+```bash
+npm install
+npm run build:ui
+npm run dev
+```
 
 ## Acknowledgements
 
@@ -76,16 +133,36 @@ This project could not exist without the work of these teams and communities:
 - [TanStack](https://tanstack.com/) for the application tooling used by the docs.
 - [Voidzero](https://voidzero.dev/) for awesome JS tools
 
-## Publishing Checklist
+## Contributing
 
-Before publishing a new version:
+Contributions are welcome, especially bug reports, accessibility fixes, documentation
+improvements, and focused component improvements.
 
-```bash
-npm run fmt
-npm run lint
-npm run tsc:check
-npm run build -w packages/ui
-npm pack --dry-run -w packages/ui
-```
+Before opening a pull request:
+
+1. Install dependencies from the repository root:
+
+   ```bash
+   npm install
+   ```
+
+2. Build the UI package when your change affects `packages/ui` or documentation examples:
+
+   ```bash
+   npm run build:ui
+   ```
+
+3. Run the required checks:
+
+   ```bash
+   npm run fmt:fix
+   npm run lint:check
+   npm run tsc:check
+   ```
+
+Keep pull requests small and specific. For component changes, update the related stories,
+exports, and documentation so the package and docs stay in sync.
 
-Check that the tarball contains `dist/index.js`, `dist/index.cjs`, `dist/index.d.ts`, `dist/index.css`, `package.json`, and this README.
+Feel free to use agents or code generation tools, but
+please review the result before submitting. The components are intentionally small and direct,
+so the goal is to keep the code readable, maintainable, and free from unnecessary abstractions.

package/dist/components/Breadcrumbs/Breadcrumbs.d.ts

@@ -0,0 +1,43 @@
+import { Menu as MenuPrimitive } from '@base-ui/react/menu';
+import * as React from 'react';
+type BreadcrumbsItemRenderProps = Omit<React.ComponentProps<'a'>, 'children'> & {
+    children: React.ReactNode;
+};
+type BreadcrumbsItem = {
+    key?: React.Key;
+    label: React.ReactNode;
+    href?: string;
+    target?: React.ComponentProps<'a'>['target'];
+    rel?: React.ComponentProps<'a'>['rel'];
+    onClick?: React.ComponentProps<'a'>['onClick'];
+    render?: (props: BreadcrumbsItemRenderProps) => React.ReactElement;
+};
+type BreadcrumbsClassNames = {
+    ellipsisTrigger?: MenuPrimitive.Trigger.Props['className'];
+    popup?: MenuPrimitive.Popup.Props['className'];
+    popupItem?: MenuPrimitive.Item.Props['className'];
+    portal?: MenuPrimitive.Portal.Props['className'];
+    positioner?: MenuPrimitive.Positioner.Props['className'];
+};
+type BreadcrumbsSlotProps = {
+    ellipsisTrigger?: Omit<MenuPrimitive.Trigger.Props, 'children' | 'className'>;
+    popup?: Omit<MenuPrimitive.Popup.Props, 'children' | 'className'>;
+    popupItem?: Omit<MenuPrimitive.Item.Props, 'children' | 'className'>;
+    popupLinkItem?: Omit<MenuPrimitive.LinkItem.Props, 'children' | 'className' | 'href' | 'render'>;
+    portal?: Omit<MenuPrimitive.Portal.Props, 'children' | 'className'>;
+    positioner?: Omit<MenuPrimitive.Positioner.Props, 'children' | 'className'>;
+};
+type BreadcrumbsProps = Omit<React.ComponentProps<'nav'>, 'children'> & {
+    items: BreadcrumbsItem[];
+    separator?: React.ReactNode;
+    maxItems?: number;
+    itemsBeforeCollapse?: number;
+    itemsAfterCollapse?: number;
+    ellipsisLabel?: React.ReactNode;
+    hiddenItemsMenuLabel?: string;
+    classNames?: BreadcrumbsClassNames;
+    slotProps?: BreadcrumbsSlotProps;
+};
+declare function Breadcrumbs({ className, items, separator, maxItems, itemsBeforeCollapse, itemsAfterCollapse, ellipsisLabel, hiddenItemsMenuLabel, classNames, slotProps, ...props }: BreadcrumbsProps): import("react/jsx-runtime").JSX.Element;
+export { Breadcrumbs };
+export type { BreadcrumbsProps, BreadcrumbsItem, BreadcrumbsItemRenderProps, BreadcrumbsClassNames, BreadcrumbsSlotProps, };

package/dist/components/Breadcrumbs/index.d.ts

@@ -0,0 +1,2 @@
+export { Breadcrumbs } from './Breadcrumbs';
+export type { BreadcrumbsProps, BreadcrumbsItem, BreadcrumbsItemRenderProps, BreadcrumbsClassNames, BreadcrumbsSlotProps, } from './Breadcrumbs';

package/dist/components/Lightbox/Lightbox.d.ts

@@ -0,0 +1,59 @@
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
+import * as React from 'react';
+type LightboxContentClassNames = {
+    portal?: DialogPrimitive.Portal.Props['className'];
+    backdrop?: DialogPrimitive.Backdrop.Props['className'];
+    viewport?: DialogPrimitive.Viewport.Props['className'];
+    frame?: string;
+};
+type LightboxContentSlotProps = {
+    portal?: Omit<DialogPrimitive.Portal.Props, 'className' | 'children'>;
+    backdrop?: Omit<DialogPrimitive.Backdrop.Props, 'className'>;
+    viewport?: Omit<DialogPrimitive.Viewport.Props, 'className' | 'children'>;
+};
+type LightboxContentProps = Omit<DialogPrimitive.Popup.Props, 'className'> & {
+    className?: DialogPrimitive.Popup.Props['className'];
+    classNames?: LightboxContentClassNames;
+    slotProps?: LightboxContentSlotProps;
+    container?: DialogPrimitive.Portal.Props['container'];
+    withBackdrop?: boolean;
+    closeLabel?: string;
+    closeButton?: DialogPrimitive.Close.Props['render'];
+    withCloseButton?: boolean;
+    closeOnContentClick?: boolean;
+};
+type LightboxImageProps = Omit<React.ComponentProps<'img'>, 'src'> & {
+    src: string;
+    /**
+     * Controls image source used in popup. Defaults to `src`.
+     */
+    previewSrc?: string;
+};
+type LightboxGalleryProps = {
+    selector?: string;
+    rootRef?: React.RefObject<HTMLElement | null>;
+    rootSelector?: string;
+    withBackdrop?: boolean;
+    closeLabel?: string;
+    className?: DialogPrimitive.Popup.Props['className'];
+    classNames?: LightboxContentClassNames;
+    slotProps?: LightboxContentSlotProps;
+    container?: DialogPrimitive.Portal.Props['container'];
+};
+declare const Lightbox: typeof DialogPrimitive.Root;
+declare const createLightboxHandle: typeof DialogPrimitive.createHandle;
+declare function LightboxTrigger({ className, render, ...props }: DialogPrimitive.Trigger.Props): import("react/jsx-runtime").JSX.Element;
+declare function LightboxPortal({ className, ...props }: DialogPrimitive.Portal.Props): import("react/jsx-runtime").JSX.Element;
+declare function LightboxBackdrop({ className, ...props }: DialogPrimitive.Backdrop.Props): import("react/jsx-runtime").JSX.Element;
+declare function LightboxViewport({ className, ...props }: DialogPrimitive.Viewport.Props): import("react/jsx-runtime").JSX.Element;
+declare function LightboxPopup({ className, ...props }: DialogPrimitive.Popup.Props): import("react/jsx-runtime").JSX.Element;
+declare function LightboxClose({ className, ...props }: DialogPrimitive.Close.Props): import("react/jsx-runtime").JSX.Element;
+declare function LightboxImage({ src, previewSrc, alt, className, ...props }: LightboxImageProps): import("react/jsx-runtime").JSX.Element;
+declare function LightboxContent({ className, classNames, slotProps, container, withBackdrop, withCloseButton, closeOnContentClick, closeLabel, closeButton, children, ...props }: LightboxContentProps): import("react/jsx-runtime").JSX.Element;
+declare function LightboxGallery({ selector, rootRef, rootSelector, withBackdrop, closeLabel, className, classNames, slotProps, container, }: LightboxGalleryProps): import("react/jsx-runtime").JSX.Element;
+type LightboxProps<Payload = unknown> = DialogPrimitive.Root.Props<Payload>;
+type LightboxHandle<Payload = unknown> = DialogPrimitive.Handle<Payload>;
+type LightboxTriggerProps = DialogPrimitive.Trigger.Props;
+type LightboxCloseProps = DialogPrimitive.Close.Props;
+export { Lightbox, createLightboxHandle, LightboxTrigger, LightboxPortal, LightboxBackdrop, LightboxViewport, LightboxPopup, LightboxContent, LightboxClose, LightboxImage, LightboxGallery, };
+export type { LightboxProps, LightboxHandle, LightboxTriggerProps, LightboxContentProps, LightboxCloseProps, LightboxImageProps, LightboxGalleryProps, LightboxContentClassNames, LightboxContentSlotProps, };

package/dist/components/Lightbox/index.d.ts

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

package/dist/components/List/List.d.ts

@@ -11,8 +11,15 @@ type ListProps = React.ComponentPropsWithoutRef<ListAs> & {
     size?: ListSize;
     tone?: ListTone;
 };
-type ListItemProps = React.ComponentProps<'li'>;
+type ListItemClassNames = {
+    marker?: string;
+    content?: string;
+};
+type ListItemProps = React.ComponentProps<'li'> & {
+    marker?: React.ReactNode;
+    classNames?: ListItemClassNames;
+};
 declare function List({ as, marker, gap, size, tone, className, ...props }: ListProps): import("react/jsx-runtime").JSX.Element;
-declare function ListItem({ className, ...props }: ListItemProps): import("react/jsx-runtime").JSX.Element;
+declare function ListItem({ className, classNames, marker, children, ...props }: ListItemProps): import("react/jsx-runtime").JSX.Element;
 export { List, ListItem };
-export type { ListProps, ListItemProps, ListAs, ListMarker, ListGap, ListSize, ListTone };
+export type { ListProps, ListItemProps, ListItemClassNames, ListAs, ListMarker, ListGap, ListSize, ListTone, };

package/dist/components/Pagination/Pagination.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+type PaginationToolbarVariant = 'default' | 'outline' | 'ghost';
+type PaginationToolbarSize = 'sm' | 'md' | 'lg';
+type PaginationSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type PaginationProps = Omit<React.ComponentProps<'nav'>, 'onChange'> & {
+    count: number;
+    page?: number;
+    defaultPage?: number;
+    onPageChange?: (page: number) => void;
+    visiblePages?: number;
+    showPages?: boolean;
+    showArrows?: boolean;
+    disabled?: boolean;
+    getPageHref?: (page: number) => string;
+    size?: PaginationSize;
+    toolbarVariant?: PaginationToolbarVariant;
+    toolbarSize?: PaginationToolbarSize;
+    previousLabel?: string;
+    nextLabel?: string;
+};
+declare function Pagination({ className, count, page, defaultPage, onPageChange, visiblePages, showPages, showArrows, disabled, getPageHref, size, toolbarVariant, toolbarSize, previousLabel, nextLabel, ...props }: PaginationProps): import("react/jsx-runtime").JSX.Element;
+export { Pagination };
+export type { PaginationProps, PaginationToolbarVariant, PaginationToolbarSize, PaginationSize };

package/dist/components/Pagination/index.d.ts

@@ -0,0 +1,2 @@
+export { Pagination } from './Pagination';
+export type { PaginationProps, PaginationSize, PaginationToolbarVariant, PaginationToolbarSize, } from './Pagination';