@a4ui/core 0.38.1 → 0.39.0

package/README.md

@@ -11,7 +11,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@a4ui/core.svg)](https://www.npmjs.com/package/@a4ui/core)
 [![minzipped size](https://img.shields.io/bundlephobia/minzip/@a4ui/core.svg)](https://bundlephobia.com/package/@a4ui/core)
 
-Accessible SolidJS **Spatial Glass** component library — 75+ components,
+Accessible SolidJS **Spatial Glass** component library — 240+ components,
 layouts, runtime themes, a motion system, **1500+ icons** (lucide), and
 framework-agnostic Web Components. Named after the 4 people in the Rivera
 family. 🙂
@@ -35,7 +35,8 @@ Three layers, one identity:
 npm install @a4ui/core
 ```
 
-Peer dependency: `solid-js` (>= 1.9).
+Peer dependencies: `solid-js` (>= 1.9) and, optionally, `tailwindcss` (`^3.4.0` or
+`^4.0.0`; the setup differs, see below).
 
 **Starting fresh?** Scaffold a preconfigured Solid + Vite + A4ui app (with or
 without Tailwind):
@@ -47,7 +48,33 @@ npm create a4ui@latest my-app
 
 ## Use
 
-**With Tailwind** (recommended) — add the A4ui preset so the components'
+**With Tailwind 4** — import `@a4ui/core/theme.css` after Tailwind in your CSS, and
+nothing else. It carries the tokens, the glass classes, the `light:` variant and
+the `@source` that scans the components:
+
+```css
+/* src/index.css */
+@import 'tailwindcss';
+@import '@a4ui/core/theme.css';
+```
+
+```tsx
+import './index.css'
+import { Button } from '@a4ui/core'
+
+export default () => <Button variant="primary">Save</Button>
+```
+
+Tailwind 4 ignores `tailwind.config.js` and its `presets:` unless `@config` names
+it, so the Tailwind 3 setup below builds without error on Tailwind 4 and produces
+no A4ui styles. If you see unstyled components, check this first.
+
+`theme.css` pins the scales the components were written for, so in your own code
+`shadow-sm`, `rounded-sm`, `blur-sm`, `ring`, the default palette and the default
+border color mean what they mean in Tailwind 3 (details in
+[`INTEGRATIONS.md`](./INTEGRATIONS.md#tailwind-4)).
+
+**With Tailwind 3** — add the A4ui preset so the components'
 utilities and glass classes (`bg-primary/90`, `.card`, `.glow-edge`) resolve
 against A4ui's tokens, and import the token stylesheet once:
 
@@ -78,7 +105,8 @@ import { Button } from '@a4ui/core'
 ```
 
 (`styles.css` ships only the CSS variables + motion keyframes — it needs the
-Tailwind preset to generate the component utilities; `full.css` is the
+Tailwind 3 preset to generate the component utilities; `theme.css` already includes it;
+`full.css` is the
 self-contained alternative. The framework-agnostic `elements` bundle ships its
 own precompiled CSS too.)
 
@@ -108,7 +136,7 @@ Browse the full set at [lucide.dev/icons](https://lucide.dev/icons).
 
 A4ui is **tree-shakeable** — `sideEffects` is `["**/*.css"]`, so the only thing
 that lands in your bundle is what you actually `import`. You never pay for the
-75+ components you don't use, and adding components to the library **doesn't grow
+240+ components you don't use, and adding components to the library **doesn't grow
 your app**. Import à la carte:
 
 ```tsx
@@ -122,11 +150,12 @@ Approximate **gzipped** weights (measured on 0.13.0; JS excludes the `solid-js`,
 | ----------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **First component** (e.g. `Button` + the `cn` helper) | ~10–11 kB                | One-time baseline (includes `tailwind-merge`). Shared by every component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **Typical extra primitive**                           | ~0.1–0.5 kB              | `Button` alone 10.7 kB → `Button + Card + Badge + Input` 11.1 kB. Heavier ones (`DataGrid`, `Calendar`, `Combobox`, `Tour`) cost more via their Kobalte/behavior deps.                                                                                                                                                                                                                                                                                                                                                                                                  |
-| **Whole barrel** (`@a4ui/core`, all 75+ used)         | ~53.0 kB                 | Only if you literally import everything — the realistic ceiling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **Whole barrel** (`@a4ui/core`, everything used)      | ~53.0 kB                 | Only if you literally import everything — the realistic ceiling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `@a4ui/core/commerce`                                 | ~3.0 kB                  | ProductCard, CartSummary, PriceTag…                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `@a4ui/core/charts`                                   | ~2.5 kB                  | Sparkline, BarChart, DonutChart (native SVG).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `@a4ui/core/styles.css`                               | ~5.3 kB                  | Tokens + motion keyframes (needs the Tailwind preset for utilities).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `@a4ui/core/full.css`                                 | ~14.1 kB                 | Every utility precompiled — for **no-Tailwind** apps. With Tailwind, your own purge ships far less.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `@a4ui/core/theme.css`                                | ~8 kB                    | Tailwind 4 entry: tokens, motion, starfield and glass rules, all emitted. Your Tailwind build adds the utilities.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `@a4ui/core/elements` (Web Components)                | ~63.9 kB JS + ~14 kB CSS | Self-contained (Solid + motion compiled in). For React/Vue/vanilla.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `motion` (the animation engine)                       | ~45 kB                   | **External / opt-in** — pulled in **only** if you import an animated component (`Stat`, `HoldToConfirm`, `Curtain`, `Parallax`, `ScrambleText`, `FillText`, `TextReveal`, `NotificationStack`, `MultiStateBadge`, `Expandable`, `Magnetic`, `ScrollProgress`, `GradientText`, `SpeedDial`, or the `flyToCart`/`animate`/`createCountUp` helpers). Engine-free ones (`LoadingDots`, `NowPlaying`, `Typewriter`, `Spotlight`, `Ripple`, `TiltCard` — CSS/WAAPI) and static UIs never load it; that's also why `<Button ripple>` and `<Card tilt spotlight>` cost nothing. |
 
@@ -180,9 +209,36 @@ recolors live, then copy the exported CSS or JSON and apply it as a
 `ThemeDefinition`. This is separate from the light/dark `setTheme`/`toggleTheme`
 mode switch — a theme recolors underneath either mode.
 
+### Right-to-left
+
+Wrap the app (or any subtree) in `DirectionProvider`. It sets `dir` on the DOM,
+tells Kobalte which way arrow keys move (Tabs, Menubar, Slider, menus), and
+copies the direction onto overlays that render in `<body>` (Modal, Drawer,
+Popover, Dropdown, Tooltip, Command):
+
+```tsx
+import { DirectionProvider, useDirection } from '@a4ui/core'
+
+render(
+  () => (
+    <DirectionProvider dir="rtl" locale="ar">
+      <App />
+    </DirectionProvider>
+  ),
+  document.getElementById('root')!,
+)
+```
+
+Components use logical Tailwind utilities (`ms-*`, `start-*`, `text-start`), so
+nothing else needs configuring. Mount `<Toaster />` inside the provider. `Drawer`
+and `Sidebar` take `side="start" | "end"`, which follows the direction;
+`Drawer`'s `"left" | "right"` stay physical. Charts, maps, code blocks and
+other geometry-bound widgets keep their own left-to-right layout. The docs have
+an RTL switch on every example.
+
 ## Components
 
-75+ components across ten categories (this is a sample — see the
+240+ components across eleven categories (this is a sample — see the
 **[docs site](https://a4ui.pages.dev/)** or `src/index.ts` for the
 full list):
 
@@ -193,7 +249,7 @@ full list):
 | Data & display | `Table`, `DataGrid`, `Tree`, `Calendar`, `Timeline`, `Stat`, `Descriptions`, `SpecSheet`, `RatingsSummary`, `LogoWall`, `ChatThread`, `Message`, `Attachment`, `Citation`, `CodeTabs`, `DataView`, `BalanceCard`, `TransactionFeed`, `KpiBlock`, `BlockEditor`, `CalendarHeatmap`                                                                 |
 | Navigation     | `Tabs`, `Breadcrumb`, `Pagination`, `Command`, `Anchor`, `Stepper`, `BottomNavigation`, `CategoryStrip`, `Spaces`, `SideRail`, `Sidebar`, `NavigationMenu`                                                                                                                                                                                        |
 | Feedback       | `Alert`, `AnnouncementBar`, `Toast`, `Progress`, `Skeleton`, `Empty`, `Result`, `NotificationCenter`                                                                                                                                                                                                                                              |
-| Layout         | `AppShell`, `SpaceBackground`, `ThemedScenery`, `Card`, `Splitter`, `Affix`, `NavGroup`, `FloatingToolbar`, `ArtifactPanel`, `MasterDetail`, `ScrollArea`, `Item`, `Prose`                                                                                                                                                                        |
+| Layout         | `AppShell`, `SpaceBackground`, `ThemedScenery`, `DirectionProvider`, `Card`, `Splitter`, `Affix`, `NavGroup`, `FloatingToolbar`, `ArtifactPanel`, `MasterDetail`, `ScrollArea`, `Item`, `Prose`                                                                                                                                                   |
 | Commerce       | `ProductCard`, `ProductGrid`, `PriceTag`, `PriceBlock`, `QuantityStepper`, `CartLine`, `CartSummary`, `FilterGroup`, `FacetSidebar`, `ConditionScale`                                                                                                                                                                                             |
 | Charts         | `Sparkline`, `BarChart`, `AreaChart`, `PieChart`, `DonutChart`, `RadialBarChart` (native SVG, theme-tinted)                                                                                                                                                                                                                                       |
 | Sections       | `SiteNav`, `Hero`, `FeatureGrid`, `Testimonials`, `Faq`, `CtaBanner`, `ContactSection`, `SiteFooter`, `TeamGrid` (data-driven page blocks: plain props, no JSX required)                                                                                                                                                                          |
@@ -275,7 +331,8 @@ Drop this into your project's `AGENTS.md` / `CLAUDE.md` to prime your agent:
 
 > This project uses **@a4ui/core** (SolidJS "Spatial Glass" design system). Import
 > components as named exports from `@a4ui/core`; import `@a4ui/core/styles.css`
-> once in the app entry; add `@a4ui/core/preset` to `tailwind.config` (optional).
+> once in the app entry; add `@a4ui/core/preset` to `tailwind.config` (optional). On
+> Tailwind 4, `@import '@a4ui/core/theme.css'` after Tailwind replaces both.
 > Props are typed with JSDoc/`@example` in the package's `.d.ts`.
 > **For the A4ui look, follow the Spatial Glass recipe** (in `llms.txt` and
 > https://a4ui.pages.dev/#/guide-spatial-glass): put an `<Aurora/>` backdrop