@moduix/react 2.0.0 → 2.2.0

package/README.md

@@ -1,124 +1,45 @@
-![moduix banner](https://raw.githubusercontent.com/Blinks44/moduix/main/apps/docs/public/banner.png)
+![moduix banner](https://raw.githubusercontent.com/Blinks44/moduix/main/apps/docs/docs/public/banner.png)
 
 [![npm](https://img.shields.io/npm/v/@moduix/react?logo=npm&label=npm)](https://www.npmjs.com/package/@moduix/react)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE.md)
 [![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
+# @moduix/react
 
-React implementation of the moduix component system for product interfaces, built on top of
-[Ark UI](https://ark-ui.com/) primitives.
+Polished React components for product interfaces, built on
+[Ark UI](https://ark-ui.com/) and styled with native CSS.
 
-moduix gives you ready-made components with accessible behavior, native CSS styles, and a
-composition-first API. It supports two production workflows: install the package for managed
-updates, or copy registry component source when your application needs direct ownership.
+The package combines Ark's accessible interaction model with shadcn-inspired clarity: calm defaults,
+explicit named parts, consistent states, and a token-first theme contract. No styling framework is
+required.
 
-## Why It Exists
+[Documentation](https://moduix.dev/) ·
+[Quick start](https://moduix.dev/docs/quick-start) ·
+[Components](https://moduix.dev/docs/components) ·
+[Tokens](https://moduix.dev/docs/tokens)
 
-moduix is built for real product screens: predictable behavior, readable composition, small
-runtime surface, and CSS that can be owned by the application. The library is public and actively
-developed around Ark UI primitives, shadcn-compatible source delivery, and practical defaults for
-teams that need consistent interfaces.
+## Highlights
 
-## Principles
+- Ark-aligned composition, controlled and uncontrolled state, context, callbacks, and form behavior.
+- Consistent `36px` primary controls and `32px` popup rows through shared size tokens.
+- Native CSS, CSS Modules, cascade layers, semantic tokens, and component-level variables.
+- Stable moduix `data-slot` hooks alongside Ark part and state attributes.
+- Optional reset and curated `dense`, `soft`, and `contrast` presets.
+- React 18 and 19 support.
+- A matching hosted shadcn registry when source ownership is the better workflow.
 
-- **Ark UI underneath.** Components target Ark UI composition and accessibility primitives instead of
-  reimplementing low-level interaction behavior.
-- **Small dependency surface.** Ark 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.
-- **shadcn-compatible source delivery.** shadcn/ui remains a major inspiration for readable
-  component composition. moduix keeps that ownership model available through its registry.
+## Install
 
-## Installation
-
-moduix supports two installation paths:
-
-- Install the library as a regular npm package when you want package-managed updates.
-- Install component source into your own project with `shadcn` when you want direct ownership.
-
-| Choose this path            | When it fits best                                                                                                             |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| npm package                 | You want the fastest setup, package-managed updates, imports from `@moduix/react`, and styles from `@moduix/react/style.css`. |
-| `shadcn` copy-owned install | You want generated source files inside your app, direct local customization, and imports from `@/components/moduix/*`.        |
-
-### npm package
+Install the package and its Ark UI peer dependency:
 
 ```bash
 npm install @moduix/react @ark-ui/react
 ```
 
-`react`, `react-dom`, and `@ark-ui/react` are peer dependencies. They stay in your application
-bundle, so moduix does not ship duplicate React or Ark UI runtimes.
-
-### shadcn copy-owned install
-
-`shadcn` can install selected moduix components from the hosted registry directly into your
-project. The files become part of your codebase instead of staying in `node_modules`.
-
-Make sure your project resolves the `@/*` alias to `src/*` in both `tsconfig.json` and
-`tsconfig.app.json`, and mirror it in your bundler config.
-
-Create `components.json` in the project root when your app does not already have one:
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": false,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "src/index.css",
-    "baseColor": "neutral",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "iconLibrary": "lucide",
-  "rtl": false,
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "registries": {
-    "@moduix-react": "https://moduix.dev/r/react/{name}.json"
-  }
-}
-```
-
-```bash
-npx shadcn@latest add @moduix-react/button
-npx shadcn@latest add @moduix-react/accordion
-```
-
-The registry install also pulls in the shared moduix foundation files those components need, such as
-styles, icons, and small utilities.
-
-Import the generated foundation stylesheet once in your application entry point:
-
-```tsx
-import '@/lib/moduix/styles/style.css';
-```
-
-If you want the optional reset in the copy-owned path, import it explicitly before the main
-stylesheet:
-
-```tsx
-import '@/lib/moduix/styles/reset.css';
-import '@/lib/moduix/styles/style.css';
-```
-
-With the aliases above, generated files land in `src/components/moduix/*` and `src/lib/moduix/*`.
+`react`, `react-dom`, and `@ark-ui/react` are peer dependencies, so the package does not ship
+duplicate framework or primitive runtimes.
 
-## Usage
+## Add Styles
 
 Import the required foundation stylesheet once in your application entry point:
 
@@ -126,17 +47,19 @@ Import the required foundation stylesheet once in your application entry point:
 import '@moduix/react/style.css';
 ```
 
-This stylesheet is required. It provides the shared design tokens and base styles that component
-CSS depends on.
+This entrypoint provides shared design tokens and base styles. Component imports bring along their
+own CSS.
 
-If you want the optional reset, import it explicitly before the main stylesheet:
+The reset is optional and intentionally separate:
 
 ```tsx
 import '@moduix/react/reset.css';
 import '@moduix/react/style.css';
 ```
 
-Then import and compose the components you need:
+## Use Components
+
+Import public components from the package barrel and compose their named parts:
 
 ```tsx
 import { Button, Dialog } from '@moduix/react';
@@ -145,12 +68,20 @@ export function Example() {
   return (
     <Dialog.Root>
       <Dialog.Trigger asChild>
-        <Button>Open dialog</Button>
+        <Button>Open settings</Button>
       </Dialog.Trigger>
       <Dialog.Backdrop />
       <Dialog.Positioner>
         <Dialog.Content>
-          <Dialog.Title>Project settings</Dialog.Title>
+          <Dialog.Header>
+            <Dialog.Title>Project settings</Dialog.Title>
+            <Dialog.Description>Update how this workspace behaves.</Dialog.Description>
+          </Dialog.Header>
+          <Dialog.Footer>
+            <Dialog.CloseTrigger asChild>
+              <Button variant="outline">Done</Button>
+            </Dialog.CloseTrigger>
+          </Dialog.Footer>
         </Dialog.Content>
       </Dialog.Positioner>
     </Dialog.Root>
@@ -158,95 +89,91 @@ export function Example() {
 }
 ```
 
-`style.css` ships the shared design tokens and base styles. Component imports still bring along only
-the component CSS they use.
+moduix keeps important Ark anatomy visible. Higher-level convenience parts are documented as the
+recommended path where they exist, while low-level composition remains available for advanced
+cases.
 
-## Styling
+## Theme the System
 
-Components accept `className` where customization is expected and expose stable `data-slot`
-attributes for targeted styling. Theme values are regular CSS custom properties:
+Theme values are CSS custom properties. Change broad semantic decisions first and use component
+aliases for deliberate exceptions:
 
 ```css
 :root {
-  --color-primary: oklch(0.205 0 0);
-  --button-radius: 0.5rem;
+  --moduix-primary: oklch(0.52 0.18 145);
+  --moduix-radius: 0.75rem;
+  --moduix-size-md: 36px;
+  --moduix-size-sm: 32px;
 }
-```
 
-Library CSS is organized with cascade layers:
-
-```css
-@layer ui.reset, ui.tokens, ui.base, ui.components;
+.compact-toolbar {
+  --moduix-button-size-md: 32px;
+}
 ```
 
-This keeps defaults predictable while still letting application styles override tokens,
-classes, or component-level variables.
+The token hierarchy is:
 
-## What Is Included
+1. theme primitives such as `--moduix-primary`, `--moduix-spacing-2`, `--moduix-size-md`, and `--moduix-radius`;
+2. semantic aliases such as `--moduix-color-primary`, `--moduix-spacing-md`, and `--moduix-radius-md`;
+3. shared family defaults such as `--moduix-popup-item-min-height` and `--moduix-focus-ring-width`;
+4. component aliases such as `--moduix-input-height` and `--moduix-select-item-min-height`.
 
-The package exports composed components for common product UI needs, including Accordion, Avatar,
-Button, Checkbox, Combobox, Dialog, Drawer, Field, FileUpload, Menu, NumberInput, Popover,
-QrCode, Select, Tabs, Toast, Tooltip, TreeView, and supporting layout and display primitives.
+Library styles use predictable cascade layers:
 
-## Documentation
+```css
+@layer moduix.reset, moduix.tokens, moduix.base, moduix.components;
+```
 
-- Documentation: https://moduix.dev/
-- npm package: https://www.npmjs.com/package/@moduix/react
-- React package README: `packages/react/README.md`
-- Docs app README: `apps/docs/README.md`
+Components also expose `className`, `data-slot`, and the Ark `data-scope`, `data-part`, and
+state attributes supported by their primitives.
 
-## Repository Quick Start
+## Optional Presets
 
-From the monorepo root:
+Import one preset after `style.css` and activate it on the document root:
 
-```bash
-npm install
-npm run build:react
-npm run dev
+```tsx
+import '@moduix/react/style.css';
+import '@moduix/react/presets/soft.css';
 ```
 
-## Acknowledgements
-
-This project could not exist without the work of these teams and communities:
-
-- [Ark UI](https://ark-ui.com/) for the composition and accessibility primitives now shaping the library contract.
-- [shadcn/ui](https://ui.shadcn.com/) for the API inspiration and the culture of practical,
-  readable component composition.
-- [Tailwind CSS](https://tailwindcss.com/) for the reset.css implementation.
-- [Fumadocs](https://fumadocs.dev/) for the documentation foundation.
-- [TanStack](https://tanstack.com/) for the application tooling used by the docs.
-- [Voidzero](https://voidzero.dev/) for the JavaScript tooling used by the workspace.
+```html
+<html data-moduix-theme="soft"></html>
+```
 
-## Contributing
+Available presets are `dense`, `soft`, and `contrast`. See
+[Themes](https://moduix.dev/docs/themes) before combining presets or creating a reusable custom
+theme.
 
-Contributions are welcome, especially bug reports, accessibility fixes, documentation
-improvements, and focused component improvements.
+## Prefer to Own the Source?
 
-Before opening a pull request:
+The moduix registry uses the shadcn distribution format while preserving the same Ark-aligned
+component contracts. Create the ready-to-use `components.json` from the
+[complete Quick Start](https://moduix.dev/docs/quick-start), then add the components you need:
 
-1. Install dependencies from the repository root:
+```bash
+npx shadcn@latest add @moduix-react/button @moduix-react/dialog
+```
 
-   ```bash
-   npm install
-   ```
+Generated files are installed under `@/components/moduix/*` and `@/lib/moduix/*`. Read the
+[complete Quick Start](https://moduix.dev/docs/quick-start) for alias setup, registry inspection,
+dry runs, and generated stylesheet imports.
 
-2. Build the React package when your change affects `packages/react` or documentation examples:
+## Acknowledgements
 
-   ```bash
-   npm run build:react
-   ```
+- [Ark UI](https://ark-ui.com/) provides the primitive behavior and composition model.
+- [Chakra UI](https://chakra-ui.com/) informs Ark-aligned ergonomics and design-system craft.
+- [shadcn/ui](https://ui.shadcn.com/) inspires open-code delivery, beautiful defaults, and practical
+  documentation.
+- [UnoCSS](https://unocss.dev/) and [Tailwind CSS](https://tailwindcss.com/) provide foundations
+  adapted by the optional reset.
 
-3. Run the required checks:
+## Links
 
-   ```bash
-   npm run fmt:fix
-   npm run lint:check
-   npm run tsc:check
-   ```
+- [Documentation](https://moduix.dev/)
+- [npm package](https://www.npmjs.com/package/@moduix/react)
+- [Source repository](https://github.com/Blinks44/moduix)
+- [Issues](https://github.com/Blinks44/moduix/issues)
 
-Keep pull requests small and specific. For component changes, update the related stories, exports,
-local component notes, public docs, and registry output so the package and docs stay in sync.
+## License
 
-Agent-facing repository guidance lives in `AGENTS.md` and `.agents/skills`. Generated or
-agent-assisted changes should still preserve the library's direct Ark-first component contracts,
-small APIs, and readable implementation style.
+[MIT](./LICENSE.md)

package/dist/components/accordion/Accordion.css

@@ -1,65 +1,65 @@
-@layer ui.components {
+@layer moduix.components {
   @keyframes tIMeYW_accordion-item-content-open {
     from {
       height: 0;
-      opacity: var(--accordion-item-content-closed-opacity, .01);
+      opacity: var(--moduix-accordion-item-content-closed-opacity, .01);
     }
 
     to {
       height: var(--height);
-      opacity: var(--accordion-item-content-open-opacity, 1);
+      opacity: var(--moduix-accordion-item-content-open-opacity, 1);
     }
   }
 
   @keyframes tIMeYW_accordion-item-content-closed {
     from {
       height: var(--height);
-      opacity: var(--accordion-item-content-open-opacity, 1);
+      opacity: var(--moduix-accordion-item-content-open-opacity, 1);
     }
 
     to {
       height: 0;
-      opacity: var(--accordion-item-content-closed-opacity, .01);
+      opacity: var(--moduix-accordion-item-content-closed-opacity, .01);
     }
   }
 
   @keyframes tIMeYW_accordion-item-content-open-horizontal {
     from {
       width: 0;
-      opacity: var(--accordion-item-content-closed-opacity, .01);
+      opacity: var(--moduix-accordion-item-content-closed-opacity, .01);
     }
 
     to {
       width: var(--width);
-      opacity: var(--accordion-item-content-open-opacity, 1);
+      opacity: var(--moduix-accordion-item-content-open-opacity, 1);
     }
   }
 
   @keyframes tIMeYW_accordion-item-content-closed-horizontal {
     from {
       width: var(--width);
-      opacity: var(--accordion-item-content-open-opacity, 1);
+      opacity: var(--moduix-accordion-item-content-open-opacity, 1);
     }
 
     to {
       width: 0;
-      opacity: var(--accordion-item-content-closed-opacity, .01);
+      opacity: var(--moduix-accordion-item-content-closed-opacity, .01);
     }
   }
 
   .tIMeYW_root {
     box-sizing: border-box;
-    width: var(--accordion-width, 100%);
-    max-width: var(--accordion-max-width, 100%);
+    width: var(--moduix-accordion-width, 100%);
+    max-width: var(--moduix-accordion-max-width, 100%);
     min-width: 0;
-    color: var(--accordion-color, var(--color-foreground));
+    color: var(--moduix-accordion-color, var(--moduix-color-foreground));
     flex-direction: column;
     display: flex;
 
     &[data-orientation="horizontal"] {
-      width: var(--accordion-horizontal-width, auto);
-      height: var(--accordion-horizontal-height, 20rem);
-      max-height: var(--accordion-horizontal-max-height, 100%);
+      width: var(--moduix-accordion-horizontal-width, auto);
+      height: var(--moduix-accordion-horizontal-height, 20rem);
+      max-height: var(--moduix-accordion-horizontal-max-height, 100%);
       flex-direction: row;
     }
   }
@@ -68,16 +68,16 @@
     overflow-anchor: none;
 
     &[data-orientation="vertical"]:not(:last-child) {
-      border-bottom: var(--accordion-item-border-width, var(--border-width-sm)) solid
-        var(--accordion-item-border-color, var(--color-border));
+      border-bottom: var(--moduix-accordion-item-border-width, var(--moduix-border-width-sm)) solid
+        var(--moduix-accordion-item-border-color, var(--moduix-color-border));
     }
 
     &[data-orientation="horizontal"] {
       display: flex;
 
       &:not(:last-child) {
-        border-inline-end: var(--accordion-item-border-width, var(--border-width-sm)) solid
-          var(--accordion-item-border-color, var(--color-border));
+        border-inline-end: var(--moduix-accordion-item-border-width, var(--moduix-border-width-sm))
+          solid var(--moduix-accordion-item-border-color, var(--moduix-color-border));
       }
     }
   }
@@ -86,20 +86,20 @@
     box-sizing: border-box;
     justify-content: space-between;
     align-items: center;
-    gap: var(--accordion-trigger-gap, var(--spacing-4));
+    gap: var(--moduix-accordion-trigger-gap, var(--moduix-spacing-4));
     width: 100%;
-    padding-block: var(--accordion-trigger-padding-y, var(--spacing-2));
-    padding-inline: var(--accordion-trigger-padding-x, var(--spacing-3));
-    background-color: var(--accordion-trigger-bg, var(--color-muted));
+    padding-block: var(--moduix-accordion-trigger-padding-y, var(--moduix-spacing-2));
+    padding-inline: var(--moduix-accordion-trigger-padding-x, var(--moduix-spacing-3));
+    background-color: var(--moduix-accordion-trigger-bg, var(--moduix-color-muted));
     color: inherit;
     font: inherit;
-    font-size: var(--accordion-trigger-font-size, var(--text-md));
-    line-height: var(--accordion-trigger-line-height, var(--line-height-text-md));
+    font-size: var(--moduix-accordion-trigger-font-size, var(--moduix-text-md));
+    line-height: var(--moduix-accordion-trigger-line-height, var(--moduix-line-height-text-md));
     text-align: left;
     user-select: none;
     cursor: pointer;
-    transition: background-color var(--transition-default),
-      color var(--transition-default);
+    transition: background-color var(--moduix-transition-default),
+      color var(--moduix-transition-default);
     border: 0;
     outline: 0;
     margin: 0;
@@ -107,25 +107,25 @@
 
     @media (hover: hover) {
       &:hover {
-        background-color: var(--accordion-trigger-bg-hover, var(--color-accent));
+        background-color: var(--moduix-accordion-trigger-bg-hover, var(--moduix-color-accent));
       }
     }
 
     &:focus-visible {
       z-index: 1;
-      outline: var(--accordion-focus-ring-width, var(--border-width-md)) solid
-        var(--accordion-focus-ring-color, var(--color-ring));
-      outline-offset: calc(var(--accordion-focus-ring-offset, var(--border-width-sm)) * -1);
+      outline: var(--moduix-accordion-focus-ring-width, var(--moduix-focus-ring-width, var(--moduix-border-width-md)))
+        solid var(--moduix-accordion-focus-ring-color, var(--moduix-color-ring));
+      outline-offset: calc(var(--moduix-accordion-focus-ring-offset, var(--moduix-border-width-sm)) * -1);
       position: relative;
     }
 
     &:is([disabled], [data-disabled]) {
       cursor: default;
-      opacity: var(--accordion-disabled-opacity, var(--opacity-disabled));
+      opacity: var(--moduix-accordion-disabled-opacity, var(--moduix-opacity-disabled));
     }
 
     &[data-orientation="horizontal"] {
-      width: var(--accordion-horizontal-trigger-width, 2.5rem);
+      width: var(--moduix-accordion-horizontal-trigger-width, 2.5rem);
       writing-mode: sideways-lr;
       justify-content: center;
       height: 100%;
@@ -134,9 +134,9 @@
 
   .tIMeYW_itemIndicator {
     box-sizing: border-box;
-    width: var(--accordion-icon-size, .75rem);
-    height: var(--accordion-icon-size, .75rem);
-    transition: transform var(--accordion-icon-transition, var(--transition-default));
+    width: var(--moduix-accordion-icon-size, var(--moduix-spacing-3));
+    height: var(--moduix-accordion-icon-size, var(--moduix-spacing-3));
+    transition: transform var(--moduix-accordion-icon-transition, var(--moduix-transition-default));
     flex-shrink: 0;
     justify-content: center;
     align-items: center;
@@ -148,15 +148,15 @@
     }
 
     &[data-state="open"] {
-      transform: var(--accordion-icon-open-transform, rotate(45deg) scale(1.1));
+      transform: var(--moduix-accordion-icon-open-transform, rotate(45deg) scale(1.1));
     }
   }
 
   .tIMeYW_itemContent {
     box-sizing: border-box;
-    color: var(--accordion-item-content-color, var(--color-muted-foreground));
-    font-size: var(--accordion-item-content-font-size, var(--text-md));
-    line-height: var(--accordion-item-content-line-height, var(--line-height-text-md));
+    color: var(--moduix-accordion-item-content-color, var(--moduix-color-muted-foreground));
+    font-size: var(--moduix-accordion-item-content-font-size, var(--moduix-text-md));
+    line-height: var(--moduix-accordion-item-content-line-height, var(--moduix-line-height-text-md));
     overflow: hidden;
 
     &[hidden]:not([hidden="until-found"]) {
@@ -165,33 +165,33 @@
 
     &[data-state="open"][data-orientation="vertical"] {
       animation: tIMeYW_accordion-item-content-open
-        var(--accordion-item-content-transition, var(--transition-default));
+        var(--moduix-accordion-item-content-transition, var(--moduix-transition-default));
     }
 
     &[data-state="closed"][data-orientation="vertical"] {
       animation: tIMeYW_accordion-item-content-closed
-        var(--accordion-item-content-transition, var(--transition-default));
+        var(--moduix-accordion-item-content-transition, var(--moduix-transition-default));
     }
 
     &[data-state="open"][data-orientation="horizontal"] {
       animation: tIMeYW_accordion-item-content-open-horizontal
-        var(--accordion-item-content-transition, var(--transition-default));
+        var(--moduix-accordion-item-content-transition, var(--moduix-transition-default));
     }
 
     &[data-state="closed"][data-orientation="horizontal"] {
       animation: tIMeYW_accordion-item-content-closed-horizontal
-        var(--accordion-item-content-transition, var(--transition-default));
+        var(--moduix-accordion-item-content-transition, var(--moduix-transition-default));
     }
 
     &[data-orientation="horizontal"] > * {
-      width: var(--accordion-horizontal-content-width, 16rem);
+      width: var(--moduix-accordion-horizontal-content-width, 16rem);
     }
   }
 
   .tIMeYW_itemBody {
-    gap: var(--accordion-item-body-gap, var(--spacing-3));
+    gap: var(--moduix-accordion-item-body-gap, var(--moduix-spacing-3));
     min-width: 0;
-    padding: var(--accordion-item-body-padding, var(--spacing-3));
+    padding: var(--moduix-accordion-item-body-padding, var(--moduix-spacing-3));
     display: grid;
   }
 }